# Phase 1 开发日志 — 后端骨架 + 前端骨架

> 《军事科技》栏目内部工作台 · Phase 1
> 撰写日期:2026-05-05
> 状态:**后端骨架完成,前端骨架待开发**

---

## 一、本 Phase 完成时间

- **开始日期**:2026-05-05(Phase 0 环境安装完成后接入)
- **后端骨架完成日期**:2026-05-05
- **前端骨架开发**:进行中
- **预计 Phase 1 整体收官**:Week 1 末

---

## 二、本 Phase 做了什么

1. **搭起后端项目骨架**(FastAPI + SQLModel + PostgreSQL),从零到可启动状态。目录结构遵循 dev_plan.md 第七章规划,共 16 个 Python 文件 + 1 个 SQL 脚本 + 1 个 .env。

2. **一次性建完所有数据库表**(共 12 张):users / episodes / yearly_targets / topics / topic_embeddings / schedules / knowledge_items / knowledge_embeddings / review_comments / shooting_resources / radar_items / radar_user_actions。Phase 1 只用 users 表,但其他表的 SQL 一次到位,后续 Phase 直接用,不再分批加表。

3. **实现登录认证体系**:Session + Cookie 方案(不上 JWT),三个核心接口齐备 —— `POST /api/auth/login`、`POST /api/auth/logout`、`GET /api/auth/me`。密码用 passlib + bcrypt 加密存储。

4. **预埋 2.0 兼容字段**:knowledge_items 表已包含 tags / related_entities / related_concepts 三个 JSONB 字段,embedding 维度统一 1536(为未来 Karpathy LLM Wiki 形态做准备)。

5. **创建管理员引导脚本**:backend/scripts/create_admin.py,交互式输入用户名 / 显示名 / 密码,生成首个 zhipianren 角色账号 —— 这是 Phase 1 验收的必需前置。

---

## 三、关键决策记录(以后会忘但很重要)

### 3.1 角色英文枚举值最终命名:**拼音方案**

经过取舍,栏目三种角色的数据库 / 代码层枚举值定为:

| 拼音值 | 中文含义 | 权限 |
|---|---|---|
| `zhipianren` | 制片人 / 管理员 | 全部权限 |
| `zebian` | 责编 | 维护仪表盘 / 知识库 / 排期 |
| `biandao` | 编导 | 使用 TPS / 查看知识库 / 生成报题单 / 个人热点雷达 |

**为什么选拼音不选英文**:栏目内部系统、几年内无外部协作者、无歧义压倒美观。英文版的 chief_editor(责编)和 editor(编导)极易被 AI 写错,拼音绝对不会混。

**这个决策已写入**:001_init.sql 的 CHECK 约束、UserRole Enum、create_admin.py 默认角色。后续所有权限判断、前端菜单、API 鉴权一律使用这套值,**不再改**。

### 3.2 数据库一次建完不分批

原本 Sonnet 方案是 Phase 1 只建 users 表。后修订为**一次建 12 张表**,理由:dev_plan 字段定义已很明确,分批建反而每次要写新 SQL + 改 SQLModel,不如一次到位。SQLModel 模型仍按 Phase 分批写。

### 3.3 依赖锁定关键版本

- `bcrypt==4.0.1`(显式锁旧版,避免新版 bcrypt 与 passlib 1.7.4 的兼容警告——不锁会一直报红字误以为出错)
- `itsdangerous==2.2.0`(SessionMiddleware 必需,不装会运行时报错)
- `python-multipart==0.0.9`(FastAPI 接收表单必需)
- starlette **不单独装**(它是 FastAPI 的传递依赖)

### 3.4 CORS 配置必须 allow_credentials=True

Session + Cookie 跨域时,CORS 必须 `allow_credentials=True`,且 `allow_origins` 不能用 `["*"]` —— 用 `*` 时浏览器会拒绝携带 cookie。所以必须显式写 `["http://localhost:5173"]`。

### 3.5 SQL 默认值与 SQLModel 协作策略

`created_at / updated_at` 字段用 `Field(default=None)` 配合数据库 `DEFAULT NOW()`,而非 `sa_column`,这样 SQLModel 不覆盖数据库默认值,时间戳由 PostgreSQL 兜底。

---

## 四、踩过的坑 + 怎么解决的

### 坑 1:DeepSeek v4-flash 调用工具漏参数

**现象**:Phase 1 一开始切到 Act 模式,Cline 弹红字 "execute_command without value for required parameter 'requires_approval'",连续重试 3 次都失败。

**原因**:DeepSeek v4-flash 是便宜快速款,工具调用(尤其参数多的工具)经常漏字段。Cline 的复杂任务(建项目结构、跑命令)刚好踩在它能力边界上。

**解决**:Start New Task,把 Act 模式的 Model 从 `deepseek-v4-flash` 临时切换到 `deepseek-v4-pro`,问题消失。**.clinerules 第 9 行已写明"复杂任务时临时切换 v4-pro"** —— 这就是那种情况。

**经验提炼成口诀**:
- 写新代码 / 建项目结构 / 改架构 → 用 v4-pro
- 改一两行小 bug / 加字段 / 改文案 → v4-flash 够用

### 坑 2:Sonnet 初始方案漏了几个隐性必备依赖

**现象**:Sonnet 第一版 requirements.txt 只列了 starlette(其实不需要单独装),漏了 itsdangerous、python-multipart、pydantic-settings,bcrypt 也没锁版本。

**解决**:在切 Act 之前的 Plan 阶段,Opus 4.7 一次性给出 5 条补充指令,Sonnet 全部消化落地。

**经验**:**关键技术节点(改 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 必须处理)

### 5.1 Phase 1 内部待完成

- [ ] **前端骨架开发**:Vite + React + AntD + Zustand 初始化,登录页 + 主布局 + 路由鉴权
- [ ] **前后端联调验收**:浏览器登录 → 看到主框架 → 刷新登录态保持 → 登出回到登录页
- [ ] **本地后端首次启动验证**:psql 跑 001_init.sql、create_admin.py 创管理员、uvicorn 启动后端、curl 或浏览器测三个接口

- [x] **路径 B 启动前一致性审查完成**(2026-05-11):
    - 1 项必改(.env 密码)、2 项建议改(create_admin.py 注释 + editor_name_snapshot NOT NULL)、
      4 项漏点已落实(.env 全审、cookie.txt 删除、__pycache__ 清理、.env.example 立项)
    - 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))"`

- [ ] **`.gitignore` 确认 .env 已忽略**:首次 git init 时检查,绝不能把 .env 上传

- [ ] **Pydantic v2 写法统一**:schemas/auth.py 当前用旧式 `class Config: from_attributes = True`,后续新建 schemas 文件统一用 `model_config = ConfigDict(from_attributes=True)`,旧文件随手改

- [ ] **pgvector 索引启用时机**:001_init.sql 中索引被注释掉,**待数据量到 ~1000 行**(大约 Phase 4a 中后期)再取消注释启用,前期低维度 + 少数据下顺序扫描更快

- [ ] **session 跨域 cookie 部署配置**:目前 `same_site="lax"` + `https_only=False` 是本地开发配置,**部署上线时改为 `same_site="strict"` + `https_only=True`**

- [ ] **其他 Phase 的 SQLModel 模型文件**:001_init.sql 已建齐 12 张表,但模型文件目前只有 user.py。各 Phase 启动时再建对应的 episode.py / topic.py / knowledge_item.py 等

- [ ] **scripts 目录用途**:专门放运维脚本(create_admin.py 已就位,未来可能加 seed_data.py、reset_password.py),**不要混进 app/**
- [ ] **`.env.example` 文件待创建**:供其他开发机 / Phase 5 部署参考。结构应与 .env 一致,但所有真实秘密替换为占位符。Phase 2 或 Phase 5 触发时补建。

---

## 六、本 Phase 用到的工具 / 模型回顾

| 角色 | 工具 / 模型 | 用途 |
|---|---|---|
| 制片人(刘通) | 人脑 + 浏览器 | 拍板、审核、卡壳兜底咨询 |
| 高级技术顾问 | Claude Opus 4.7(Claude.ai 网页) | 架构指导、方案审核、风险预警 |
| 架构师 | Sonnet 4.6(VS Code Cline Plan 模式) | 项目内方案设计、Act 改动审查 |
| 执行者 | DeepSeek v4-flash → v4-pro(VS Code Cline Act 模式) | 实际写代码 |

**模型切换教训**:Phase 1 初始用 v4-flash 卡壳,切 v4-pro 后顺畅完成。后续骨架级任务直接 v4-pro 起步,日常小改用 v4-flash。

---

## 七、当前可启动命令(供下次接手参考)

```bash
# 第一次启动后端的完整流程:
cd backend

# 1. 装依赖
pip install -r requirements.txt

# 2. 建库 + 建表
psql -U postgres -d milsci_dev -f sql/001_init.sql

# 3. 创建管理员账号(交互式)
python scripts/create_admin.py

# 4. 启动 FastAPI
uvicorn app.main:app --reload

# 5. 验证(浏览器或 curl):
#    GET  http://localhost:8000/docs        ← FastAPI 自动文档
#    POST http://localhost:8000/api/auth/login
#    GET  http://localhost:8000/api/auth/me
```

---

## 八、下一步(Phase 1 剩余 / Phase 2 准备)

1. **当下立刻做**:在本机执行上面"七、可启动命令"全套,验证后端骨架能否真跑起来
2. **后端跑通后**:开 Cline 新 Task,Plan 模式让 Sonnet 出前端骨架方案,Act 模式 v4-pro 实施
3. **Phase 1 完整收官标志**:浏览器打开 → 登录 → 看到主框架 → 刷新还在 → 登出
4. **进入 Phase 2 前**:写 phase2_log.md 之前的"本 Phase 完成时间"部分起头,然后开始仪表盘 + 用户管理 + 历史数据导入工作

---

*本日志由 Claude Opus 4.7 基于 Sonnet 4.6 完工报告 + chat 关键决策整理生成。*
*下一次 Phase 收尾时,沿用本格式继续写 phase2_log.md。*