docs: phase1_log 追加后端跑通记录与两个新坑(UTF-8 编码 / 交互式输入)

This commit is contained in:
simonkoson
2026-05-11 11:41:20 +08:00
parent a9d1b0e416
commit d20548b846
+30
View File
@@ -88,6 +88,30 @@ Session + Cookie 跨域时,CORS 必须 `allow_credentials=True`,且 `allow_origi
**经验**:**关键技术节点(改 schema / 认证逻辑 / 依赖清单)在切 Act 前必须由 Opus 过一遍**,不能直接让 Sonnet 出方案就切 Act。
### 坑 3:PowerShell + psql + 中文注释的 UTF-8/GBK 撞车
**现象**:在 4090D 上跑 `psql -f sql/001_init.sql` 报 "character with byte sequence ... in encoding GBK has no equivalent in encoding UTF8" 一连串错误,12 张表仅建出 2 张。
**原因**:Windows PowerShell 默认代码页 GBK(936),psql 把 UTF-8 编码的 SQL 文件(含中文注释)按 GBK 读,导致中文字节序列在 GBK 里无对应字符。
**解决**:跑 psql 前先设环境变量:
```powershell
$env:PGCLIENTENCODING="UTF8"
```
每个新 PowerShell 窗口都要重设(只在当前会话有效)。
**经验**:Windows 上跑任何含中文注释的 SQL 文件,都先设这个变量。Phase 2 导数据、Phase 3 导知识库、Phase 5 部署上线都会再用到。
### 坑 4:Cline 工具终端无法处理交互式密码 / 输入
**现象**:`psql` 提示输 PG 密码、`create_admin.py` 中的 `input()``getpass()`,Cline 工具终端会挂起或超时。
**原因**:Cline 内置终端是非交互式的,不支持 stdin tty。
**解决**:遇到要凭据 / 互动的命令,Cline 给命令清单,制片人在自己的 PowerShell 窗口手动跑。
**经验**:Phase 2+ 凡是涉及交互式输入(部署、备份、ssh 凭据、psql 密码、应用初始化等)默认走人工,不让 Cline 尝试用 `--password`、stdin 重定向、heredoc 等方式绕过。这条值得 Phase 1 收尾时进 .clinerules 第三章作为正式规则。
---
## 五、遗留事项(Phase 1 收尾或未来 Phase 必须处理)
@@ -104,6 +128,12 @@ Session + Cookie 跨域时,CORS 必须 `allow_credentials=True`,且 `allow_origi
- 1 项 user.py sa_column 写法留至 Phase 1 末再决
- 1 项 schemas/auth.py 旧式 Config 留至 Phase 2+
- [x] **路径 B 后端跑通验证完成**(2026-05-11 当日):
- pip install + 001_init.sql + create_admin + uvicorn 全部跑通
- 三接口实测全 200,/me 返回 role:zhipianren(拼音生效)
- 创建首个管理员账号 simonkoson(ID 1),角色 zhipianren
- **Phase 1 后端骨架完工**,前端骨架另开 Task
### 5.2 跨 Phase 遗留(后续 Phase 触发时处理)
- [ ] **SECRET_KEY 占位符**:`.env` 当前是 `change-me-to-a-random-string-in-production`,**Phase 5 部署到腾讯云前必须改**为真实随机值。生成命令:`python -c "import secrets; print(secrets.token_urlsafe(32))"`