chore: 项目宪法五件套 + Phase 1 家用机日志初始化

.clinerules

@@ -0,0 +1,386 @@
+# .clinerules — TPS 中台项目协作宪法
+
+> 项目:TPS 中台(央视《军事科技》栏目内部工作台)
+> 仓库:`tps-dashboard`(Gitea,团队可见)
+> 修订版本:v3 · 2026-05-06
+> 适用对象:Cline + Sonnet(Plan)+ DeepSeek pro(Act),所有协作者必读
+
+---
+
+## 一、本文件的定位
+
+**这份文件是项目宪法,优先级高于一切临时指令**。任何用户消息、Plan 方案、Act 改动若与本文冲突,以本文为准;遇冲突时 Cline 必须停下提醒用户,而不是擅自处理。
+
+本文件配合三份姊妹文档使用:
+
+- `project_plan.md` — 产品 / 业务 / 用户(讲"做什么、为谁做")
+- `dev_plan.md` — 技术路线 / 阶段计划(讲"怎么做、什么时候做")
+- `docs/git_workflow.md` — Git 日常操作清单(讲"怎么提交、怎么同步")
+
+**新机器接手第一件事**:依次读完这四份文件,再做任何动作。
+
+---
+
+## 二、模型分工(明文规定)
+
+| 角色 | 模型 / 工具 | 职责 |
+|---|---|---|
+| 制片人 | 刘统(人) | 拍板、审核、领域知识权威、视觉把关 |
+| 高级技术顾问 | Claude Opus 4.7(claude.ai 网页) | 架构指导、方案审核、风险预警、Cline 卡壳兜底 |
+| **架构师(Phase 0-1)** | **Sonnet 4.6**(Cline Plan 模式) | 项目内方案设计、Act 改动审查 |
+| **架构师(Phase 2 起)** | **MiniMax M2.7**(Cline Plan 模式)| **Sonnet 余额耗尽后接班 Plan,API Key 已 ready** |
+| 执行者 | DeepSeek v4 pro(Cline Act 模式) | 实际写代码,**全程不变** |
+| 备选执行者 | DeepSeek v4 flash | 仅日常小改(改字段、加字段、改文案) |
+
+**模型阶段性安排(2026-05-06 拍板)**:
+
+- **Phase 0-1(骨架期)**:**Plan = Sonnet 4.6**,Act = DeepSeek pro
+- **Phase 2 起**:**Plan = MiniMax M2.7**(标准版,非 highspeed),Act 仍 DeepSeek pro
+- **切换的核心动机**:Sonnet 单次调用昂贵且 Plan 模式调用频次最高,换 MiniMax M2.7 后单次成本降至 1/50
+- DeepSeek 全程在岗,不退役
+
+**MiniMax M2.7 接入信息(配置在 Cline 的 Plan 模式)**:
+
+- 官方 API:`base_url = https://api.minimaxi.com/v1`(注意是 minimaxi)
+- Model ID:`MiniMax-M2.7`(标准版)
+- **不用** highspeed 版(贵一倍,Plan 模式不需要那点速度)
+- API Key 已由制片人申请就绪
+
+**模型切换的判断口诀**(Phase 2 起):
+
+- Plan 出方案、审 Act 改动 → **MiniMax M2.7**
+- Act 写新代码 / 建结构 / 改架构 → **DeepSeek pro**
+- Act 改小 bug / 加字段 / 改文案 → **DeepSeek flash**(可选)
+- Plan 连续两次方案质量明显下降 → **临时切回 Sonnet 顶住**(允许)
+
+---
+
+## 三、协作流程(死规矩)
+
+### 3.1 Plan → Act → 完工三阶段
+
+1. **Plan 阶段**:Sonnet 出方案,**复杂方案先发 Opus 4.7 审一遍**,审过后再切 Act
+2. **Act 阶段**:DeepSeek pro 严格按 Plan 实施,**禁止自作主张扩展范围**
+3. **完工阶段**:Act 必须给出"完工报告",列出所有改动文件、设计决策、潜在风险
+
+### 3.2 哪些事 Act 必须停下让 Plan 审
+
+- 改 schema(数据库表结构、SQL 文件)
+- 改认证 / 鉴权逻辑
+- 改 .env、.gitignore、.clinerules、project_plan.md、dev_plan.md
+- 引入新依赖(requirements.txt / package.json 新增条目)
+- 删除任何文件
+- **连续 2 次调试失败必须停下**,切 Plan 重新规划
+
+### 3.3 每个独立任务必须开 New Task
+
+Phase 内的子任务、修复独立 bug、前端骨架、后端骨架——都各自独立 Task,**避免上下文滚雪球**导致模型遗忘前期约定。
+
+---
+
+## 四、技术栈红线(不可擅改)
+
+| 层级 | 选型 | 理由 |
+|---|---|---|
+| 前端语言 | **JavaScript**(不用 TypeScript) | 1.0 求快,二期再迁 |
+| 前端框架 | React 18 + Vite | — |
+| UI 库 | Ant Design 5 + 中文 locale | — |
+| 状态管理 | **Zustand**(不用 Redux/Context) | 轻量、对小团队够用 |
+| 路由 | React Router v6 | — |
+| 后端框架 | FastAPI | — |
+| ORM | **SQLModel(同步)**,不用 async | 8 人并发同步够用 |
+| 数据库迁移 | **手写 SQL**(`backend/sql/00X_*.sql`),不用 Alembic | schema 稳定后再上 |
+| 关系数据库 | PostgreSQL 16 | — |
+| 向量检索 | **pgvector**(PG 扩展,不用独立向量库) | 省一个服务、省 ~400MB 内存 |
+| 向量维度 | **统一 1536 维**(为 2.0 wiki 兼容) | 不可改 |
+| 认证 | **Session + Cookie**(不用 JWT) | 8 人内部系统 |
+| AI 模型 | DeepSeek(配置写死,UI 二期做) | — |
+| Word 生成 | **docxtpl**(不用裸 python-docx) | — |
+| 甘特图 | **frappe-gantt**(不自己用 D3 画) | — |
+| 定时任务 | APScheduler(Phase 4c 才用) | — |
+| 部署 | Nginx 反向代理(整合 TPS / 蓝皓 TTS / MMIM) | — |
+
+**任何"换成 XXX 更好"的提议**,先在 Plan 模式讨论,绝不直接改。
+
+---
+
+## 五、栏目业务约定(易错点警告——AI 极易写反)
+
+> 这些是栏目特有的反直觉规则,Sonnet / DeepSeek 凭通用习惯做事 100% 会写错,务必死守。
+
+### 5.1 收视颜色判定(色彩规约反直觉)
+
+**只对收视份额(audience_share)上色,收视率(audience_rating)只展示数字不参与判定**:
+
+- 🔴 **红色** = 收视份额 **>** 当年摸高目标 = **优秀**(不是警告!)
+- 🔵 **蓝色** = 基础目标 ≤ 收视份额 ≤ 摸高目标 = 达标
+- 🟢 **绿色** = 收视份额 **<** 当年基础目标 = **待提升**(不是安全!)
+
+**通用习惯是红警绿安,栏目沿用历史传统刚好相反**。前端写颜色逻辑、AI 生成报表评论、Excel 导出色彩——任何涉及颜色的地方都按此规则。
+
+### 5.2 年度目标只增不改(时间不变性)
+
+`yearly_targets` 表每年新增一行,**历史年份的目标行绝不可被覆盖或删除**。
+
+- 前端展示某期数据时,**根据该期播出年份的目标判颜色**,不是"当前年份的目标"
+- 2024 年播的节目永远按 2024 年的 0.6448 / 0.8989 判,2026 年回看也不会变色
+- DeepSeek 容易写"upsert 当前年目标"或"全局取最新目标判色"——**禁止**
+
+SQL 端:`yearly_targets.year` 加 UNIQUE 约束,代码端 INSERT 时用 `ON CONFLICT DO NOTHING`(或干脆不写 ON CONFLICT 让冲突直接报错让人看见)。**永远不要 ON CONFLICT UPDATE**。
+
+### 5.3 编导关联用"软引用 + 快照"双字段
+
+`episodes` 表始终维护 **`editor_id` + `editor_name_snapshot`** 双字段:
+
+- **在职编导**:两字段都填(冗余但稳)
+- **离职编导**:`editor_id` 留空(NULL),只填 `editor_name_snapshot`(如"张颖")
+- **历史导入**:按姓名匹配在职用户,匹配不上只填快照
+- **查询某编导历史作品**:**先按 editor_id,失败回退按 editor_name_snapshot 文本匹配**
+
+DeepSeek 容易写"editor_id 外键非空 + 删人级联"——**禁止**。一旦张颖离职,她做过的几十期节目就全成"无主"了,这是栏目最不能接受的。
+
+### 5.4 报题单内容概要的"双段结构"
+
+栏目报题单的"行话格式":
+
+- **默认格式**:**引子(200-300 字)+ 列举(3-5 条 Markdown 序号)**
+- **列举每条**以 `**加粗关键词**` 开头(核心装备/概念名)
+- **备选格式**:纯叙述式,**仅当编导明确指定时才用**
+
+AI Prompt 模板必须默认走双段、备选纯叙述。docxtpl 模板设计同此。
+
+### 5.5 角色枚举值是拼音(已锁定,不再改)
+
+| 拼音值 | 中文含义 | 权限 |
+|---|---|---|
+| `zhipianren` | 制片人 / 管理员 | 全部权限 |
+| `zebian` | 责编 | 维护仪表盘 / 知识库 / 排期 |
+| `biandao` | 编导 | 使用 TPS / 查看知识库 / 生成报题单 / 个人热点雷达 |
+
+**所有 SQL CHECK、SQLModel Enum、API 鉴权、前端权限判断、菜单显示**——一律使用拼音值,**不得替换为英文**。
+
+---
+
+## 六、AI 设计哲学(贯穿所有 Phase)
+
+**辅助而不替代,AI 给方向不给答案,保护编导创作主权。**
+
+具体落地:
+
+- 模块 B(画像建议)显式标注"仅供参考"
+- 模块 D(审片意见)**改为展示历史相似选题原文,不做 AI 预测**
+- AI Prompt 中明确告知模型"你输出的是参考稿,不是终稿"
+- 任何 AI 输出在 UI 上必须有"我来改写"或"忽略"按钮——给编导否决权
+
+---
+
+## 七、Git 工作流(本版新增)
+
+### 7.1 仓库信息
+
+- **Gitea 地址**:单位 4090D 服务器(具体 URL 用户填)
+- **仓库名**:`tps-dashboard`
+- **可见性**:团队可见
+- **默认分支**:`main`
+- **commit message 规范**:Conventional Commits(英文前缀 + 中文正文)
+
+### 7.2 commit message 格式
+
+```
+<type>: <中文正文>
+
+[可选:更详细的中文说明]
+```
+
+`<type>` 取值(英文小写):
+
+| type | 含义 | 中文正文示例 |
+|---|---|---|
+| `feat` | 新功能 | `feat: 添加用户登录接口` |
+| `fix` | 修 bug | `fix: 修复 created_at 字段 NOT NULL 约束报错` |
+| `docs` | 改文档 | `docs: 更新 phase1_log` |
+| `chore` | 杂项(依赖、配置) | `chore: 升级 bcrypt 到 4.0.1` |
+| `refactor` | 重构 | `refactor: 重构 authStore 状态管理` |
+| `style` | 格式化(空格/缩进) | `style: 统一前端缩进为 2 空格` |
+| `test` | 加测试 | `test: 添加 auth 接口测试` |
+
+### 7.3 提交时机(Cline 必须遵守)
+
+**每个独立动作单独 commit,不要堆一坨大 commit**:
+
+- 装完依赖 → 立刻 commit
+- 建完 SQL 表 → 立刻 commit
+- 写完一个完整接口 → 立刻 commit
+- 修完一个 bug → 立刻 commit
+- **不要写"晚上一起 commit"或"一个 PR 多功能"**
+
+### 7.4 Phase 收尾必须打 tag
+
+每个 Phase 完整收官时,Cline 必须主动建议:
+
+```
+git tag -a phase1-complete -m "Phase 1 后端骨架 + 前端骨架完工"
+git push origin phase1-complete
+```
+
+tag 命名:`phase{N}-{短描述}`,如:
+- `phase0-env-ready`
+- `phase1-complete`
+- `phase2-dashboard-done`
+
+### 7.5 .gitignore 必须包含
+
+- `.env`(永远不上传)
+- `__pycache__/`、`*.pyc`
+- `node_modules/`
+- `dist/`、`build/`
+- `*.log`(运行日志,不进版本库;phase{N}_log.md 例外,要进库)
+- `.DS_Store`、`Thumbs.db`
+- `cookie.txt`(Phase 1 验证后端用的临时文件)
+
+### 7.6 Cline 操作 Git 时的边界
+
+- **Cline 可以自动**:`git add`、`git commit`、`git push`、`git pull`、`git status`、`git log`
+- **Cline 必须停下问用户**:
+  - `git reset --hard`(任何形式的 hard reset)
+  - `git push --force`、`git push -f`
+  - `git rebase`(任何形式)
+  - 删除分支
+  - 删除 tag
+  - 删除远程引用
+- **永远禁止**:删除整个 .git 目录
+
+### 7.7 多设备同步原则
+
+家里 / 单位两台机器都开发时:
+
+- **离开任何一台机器前**:`git push`(把当前进度推上去)
+- **回到另一台机器开干前**:`git pull`(拉最新)
+- **每天开始工作的第一件事**:`git status` + `git pull`,确保不基于旧代码改
+
+Cline 在每次开新 Task 时,**第一个动作建议是 `git status`**,确认工作区干净。
+
+---
+
+## 八、Phase 0 安装纪律(从 Phase 0 重启,头一个 Phase 尤其重要)
+
+### 8.1 已知避坑清单(从家用电脑实战提炼)
+
+> 这些坑在家用电脑上踩过,单位机器**直接绕开**。
+
+**Python 端**:
+
+- ❌ 不要用 Microsoft Store 版 Python → ✅ 用 python.org 官方 64 位安装包
+- ❌ 不要装 Python 3.13 → ✅ 装 **Python 3.12.x**(SQLModel 等库 3.13 兼容性还不稳)
+- 安装时勾选 "Add Python to PATH"
+
+**Node.js 端**:
+
+- ❌ 不要装 Node.js 22+ → ✅ 装 **Node.js 20 LTS**
+- 推荐用 **nvm-windows** 装,方便切换版本
+
+**PostgreSQL 端**:
+
+- ❌ 装 PostgreSQL 17+ → ✅ 装 **PostgreSQL 16**
+- 装完必须执行 `CREATE EXTENSION vector;` 验证 pgvector 装了
+- 本地数据库:`milsci_dev` / 用户 `postgres` / 密码 `liutong65` / 端口 `5432`
+
+**关键 Python 依赖锁版本**(写进 requirements.txt):
+
+```
+bcrypt==4.0.1            # 必须锁旧版,新版与 passlib 1.7.4 不兼容会报红字
+itsdangerous==2.2.0      # SessionMiddleware 必需,不装运行时报错
+python-multipart==0.0.9  # FastAPI 接收表单必需
+pydantic-settings==2.2.1 # 配合 BaseSettings 读 .env
+```
+
+`starlette` **不要单独装**,它是 FastAPI 的传递依赖。
+
+**CORS 配置**(SessionMiddleware + Cookie 必需):
+
+```python
+allow_credentials=True
+allow_origins=["http://localhost:5173"]   # 必须显式列,不能用 ["*"]
+```
+
+### 8.2 安装节奏
+
+**每装完一项停下汇报、等用户确认才能继续**——禁止"一口气装完五项再来汇报"。
+
+### 8.3 严禁创建的文件名(Act 模式禁词)
+
+根目录下严禁创建含以下关键词的脚本(防止 AI 即兴探索污染项目):
+
+- `check_*` / `verify_*` / `test_*`(测试脚本统一进 `tests/` 目录)
+- `tmp_*` / `temp_*` / `debug_*`
+- `untitled*` / `new_*`
+
+**例外**:`backend/scripts/create_admin.py` 是 Phase 1 验收必需文件,不属于即兴脚本。
+
+---
+
+## 九、受保护资产清单
+
+**Act 模式严禁修改 / 删除以下文件 / 目录**:
+
+- `.clinerules`(本文件)
+- `project_plan.md`、`dev_plan.md`、`README.md`
+- `docs/` 目录下所有文件
+- `logs/` 目录下所有文件
+- 所有 `.xlsx` 样本数据文件(在 `samples/` 目录)
+- `.git/` 目录
+- `.env` 文件(只能用户手工编辑)
+
+如需修改这些文件,**必须切 Plan 模式经用户确认**。
+
+---
+
+## 十、家用机已完成进度参考(可参考但不强制)
+
+> 家用电脑(D:\myApp\Topic Planning\V2)上 Phase 0 + Phase 1 后端骨架已跑通。
+> 单位机器**从 Phase 0 重启**,但代码可参考。
+
+家用机已完成:
+
+- Phase 0 环境(Python 3.12 / Node 20 / PG 16 + pgvector)
+- Phase 1 后端骨架(FastAPI + SQLModel + 认证三件套验证通过)
+- 12 张表 SQL 已写完(`backend/sql/001_init.sql`)
+- create_admin.py 已写完
+- 详见 `logs/phase1_log.md`
+
+**单位机器 Phase 1 后端可选路径**:
+
+- **路径 A**:从 0 重写(Sonnet + DeepSeek 重新生成)
+- **路径 B**(推荐):用户把家用机的 backend 目录打包 zip 拷到单位机,解压进新仓库,Cline 跑一遍跑通即可
+
+由制片人在 Phase 1 启动时拍板选 A 或 B。
+
+---
+
+## 十一、Anthropic Opus 4.7 顾问的协同方式
+
+Cline 内的 Sonnet/DeepSeek 不直接与 Opus 通信,流程如下:
+
+1. Sonnet 给出 Plan 方案
+2. **方案涉及"改 schema / 改认证 / 改架构 / 引新依赖"时**,用户复制方案到 claude.ai 的 Opus 对话框
+3. Opus 审完给补充指令,用户复制回 VS Code Cline 的 Plan 模式
+4. Sonnet 吸收补充意见,出最终 Plan,切 Act 实施
+
+**这个回路是为关键决策设计的,不是每个小修改都走**——日常 CRUD 改动不需要让 Opus 过目。
+
+---
+
+## 十二、版本演进
+
+| 版本 | 日期 | 主要变化 |
+|---|---|---|
+| v1 | 2026-04 | 初版,定模型分工与栏目业务约定 |
+| v2 | 2026-05-04 | 加技术栈精简版、Phase 拆分 |
+| **v3** | **2026-05-06** | **加 Git 工作流、已知避坑清单、单位机重启路径;MiniMax M2.7 Phase 2 起接班 Plan 模式(替代 Sonnet),DeepSeek pro 全程在岗** |
+
+**修订原则**:.clinerules 是宪法不是变更日志,改动应慎重。临时执行细节进 phase{N}_log.md,不进本文件。
+
+---
+
+*本文件最高优先级。任何冲突以本文件为准。*
+*下次修订建议时机:Phase 2 末(评估 MiniMax 切换、整理 Phase 2 经验)。*

.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+venv/
+env/
+
+# Node
+node_modules/
+dist/
+build/
+.vite/
+
+# 环境配置(永远不上传)
+.env
+.env.local
+
+# 编辑器
+.vscode/
+.idea/
+*.swp
+
+# 操作系统
+.DS_Store
+Thumbs.db
+
+# 日志运行产物
+*.log
+cookie.txt
+
+# 临时文件
+*.tmp
+*.bak

README.md

@@ -0,0 +1,172 @@
+# TPS 中台
+
+> 央视《军事科技》栏目内部工作台
+> 仓库:`tps-dashboard` · 内部团队可见
+
+---
+
+## 这是什么
+
+一个面向《军事科技》栏目 8 人团队的内部工作台,核心模块包括:
+
+- **TPS**(选题策划系统):查重 + 知识库参考 + 报题单一键生成
+- **仪表盘**:近 4 期收视成绩 + 未来 6 期排期一目了然
+- **知识库**:往期文稿、军报材料、专家库、外拍线索一站式检索
+- **个人首页**:每位编导有自己的工作台 + 今日热点雷达
+- **拍摄资源库**:外拍联系人 / 单位 / 线索来源结构化沉淀
+
+详细模块说明见 `project_plan.md`。
+
+---
+
+## 设计哲学
+
+**辅助而不替代,AI 给方向不给答案,保护编导创作主权。**
+
+任何让 AI 替编导拍板的功能都不要做;任何把编导逼向"按 AI 建议改"的设计都要重做。
+
+---
+
+## 项目宪法(必读,优先级从高到低)
+
+| 文档 | 讲什么 | 受众 |
+|---|---|---|
+| `.clinerules` | Cline 协作规则 + 业务约定 + 已知避坑 | **AI 必读**,人类一并看 |
+| `project_plan.md` | 产品 / 业务 / 用户(做什么、为谁做)| 全员 |
+| `dev_plan.md` | 技术路线 / 阶段计划(怎么做、何时做)| 制片人 + AI |
+| `docs/git_workflow.md` | Git 操作手册 | 制片人 + AI |
+| `logs/phase{N}_log.md` | 各 Phase 进度档案 | 接力者 |
+
+**新人 / 失忆接手时的标准动作**:依次读完上面五类文档,再做任何改动。
+
+---
+
+## 当前进度
+
+> 详见 `logs/` 下最新一份日志。
+
+| Phase | 状态 |
+|---|---|
+| Phase 0 环境 + Git | 单位机进行中 |
+| Phase 1 后端骨架 | 家用机已完成,单位机走"路径 B 迁移" |
+| Phase 1 前端骨架 | 未开始 |
+| Phase 2-5 | 未开始 |
+
+---
+
+## 协作团队
+
+| 角色 | 谁 / 什么 | 做什么 |
+|---|---|---|
+| 制片人 | 刘统(人) | 拍板、产品决策、领域知识 |
+| 高级技术顾问 | Claude Opus 4.7(claude.ai 网页) | 架构指导、关键决策审核 |
+| 架构师 | Sonnet 4.6 → MiniMax M2.7(Phase 2 起) | Cline Plan 模式,出方案 |
+| 执行者 | DeepSeek v4 pro | Cline Act 模式,写代码 |
+
+详见 `.clinerules` 第二章。
+
+---
+
+## 技术栈速览
+
+- 前端:React 18 + Vite + Ant Design 5 + Zustand(JavaScript,不用 TS)
+- 后端:FastAPI + SQLModel(同步)
+- 数据库:PostgreSQL 16 + pgvector(1536 维)
+- 认证:Session + Cookie
+- AI 嵌入:DeepSeek 或 OpenAI 兼容 embedding API
+- Word 生成:docxtpl
+- 部署:Nginx 反向代理 + 腾讯云 4核8G(待租)
+
+详见 `dev_plan.md` 第五章。
+
+---
+
+## 服务整合架构
+
+```
+                  ┌────────────────────┐
+   主域名访问 →   │  腾讯云 4核8G 新机  │  ← TPS 中台主体
+                  │  (Nginx + FastAPI │
+                  │   + PostgreSQL +  │
+                  │   React 前端)     │
+                  └─────────┬──────────┘
+                            │
+                       Nginx 反代
+                            │
+                            ▼
+                  ┌────────────────────┐
+                  │  老服务器 2核2G    │  ← 蓝皓 TTS 2.0 + MMIM
+                  │  101.42.29.217     │
+                  └────────────────────┘
+```
+
+详见 `project_plan.md` 第八章。
+
+---
+
+## 快速开始(Phase 1 后端验证)
+
+> 假设你已完成 Phase 0(Python / Node / PG / Git 都装好,仓库已 clone)。
+
+```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. 验证
+#    GET  http://localhost:8000/docs        ← FastAPI 自动文档
+#    POST http://localhost:8000/api/auth/login
+#    GET  http://localhost:8000/api/auth/me
+```
+
+前端启动详见 `dev_plan.md` Phase 1 Day 5-7。
+
+---
+
+## 不在 1.0 范围内
+
+明确不做、留到 2.0 或更远的:
+
+- TypeScript 改造、Alembic、async SQLAlchemy
+- AI 模型配置 UI(写死 .env)
+- 模块 D 的 AI 预测(只展示原文)
+- 文稿写作辅助系统
+- Karpathy LLM Wiki 知识库形态(仅预埋接口)
+- 移动端 App
+- 多栏目复用
+
+详见 `project_plan.md` 第十二章 + `dev_plan.md` 第八章。
+
+---
+
+## 联系与求助
+
+| 状况 | 找谁 |
+|---|---|
+| 项目方向 / 产品决策 | 刘统(制片人) |
+| 关键架构 / 风险 / 卡壳兜底 | Claude Opus 4.7(claude.ai 网页) |
+| 日常方案 / 改动审查 | Sonnet 4.6(VS Code Cline Plan) |
+| 写代码 | DeepSeek v4 pro(VS Code Cline Act) |
+| Git 历史搞乱了 / 不小心 commit 了 .env | **立刻找 Claude Opus 4.7,不要自己瞎搞** |
+
+---
+
+## 版本演进
+
+| 版本 | 日期 | 变化 |
+|---|---|---|
+| v1 | 2026-05-06 | 初版,作为单位机仓库门牌 |
+
+---
+
+*这是项目门牌号。详细内容请翻 `project_plan.md` / `dev_plan.md` / `.clinerules` / `docs/git_workflow.md`。*

dev_plan.md

@@ -0,0 +1,494 @@
+# dev_plan.md — TPS 中台开发计划
+
+> 项目:TPS(Topic Planning System)中台
+> 仓库:`tps-dashboard`(Gitea)
+> 修订版本:v3 · 2026-05-06
+> 配套文档:`project_plan.md`(产品宪法)+ `.clinerules`(协作规则)+ `docs/git_workflow.md`(Git 操作手册)
+
+---
+
+## 一、文档定位
+
+本文是**技术与阶段宪法**——讲"怎么做、什么时候做、用什么做"。
+
+产品 / 业务问题归 `project_plan.md`;协作流程归 `.clinerules`;Git 操作细则归 `docs/git_workflow.md`。
+
+---
+
+## 二、首要目标(再申明一次)
+
+**2-3 个月内交付可用版本,让 8 人团队真的开始用。**
+
+**Week 6 末必须有 MVP 上线**(登录 + 仪表盘 + 报题单生成 + 知识库基础设施)——这条比"功能齐全"重要。
+
+---
+
+## 三、当前进度状态(2026-05-06)
+
+### 3.1 家用机已完成
+
+> 家用电脑路径:`D:\myApp\Topic Planning\V2`
+
+- ✅ Phase 0 环境(Python 3.12 / Node 20 / PG 16 + pgvector / VS Code + Cline)
+- ✅ Phase 1 后端骨架(FastAPI + SQLModel + Session 认证三件套验证通过)
+- ✅ 12 张表 SQL 已写完(`backend/sql/001_init.sql`)
+- ✅ create_admin.py 已写完
+- ❌ Phase 1 前端骨架未做
+
+详见 `logs/phase1_log.md`。
+
+### 3.2 单位机器(本仓库主战场)
+
+- ❌ 一切从零开始
+- ✅ Gitea 已配置(单位 4090D,与爱德华项目共用同一台 Gitea)
+- ✅ 本仓库 `tps-dashboard` 已规划(待创建)
+
+---
+
+## 四、单位机器接手策略
+
+### 4.1 Phase 0 必须重做,但有避坑捷径
+
+环境从 0 装,但**家用机踩过的坑全部记入 `.clinerules` 第八章避坑清单**——单位机直接绕过。
+
+### 4.2 Phase 1 后端代码:推荐"路径 B"(代码迁移)
+
+**两条路可选,制片人在 Phase 1 启动时拍板**:
+
+**路径 A — 重写**:Sonnet + DeepSeek 在单位机重新生成所有后端文件
+- 优点:全新干净
+- 缺点:浪费一天
+
+**路径 B — 迁移(推荐)**:
+1. 制片人在家用机把 `backend/` 整个目录打包 zip
+2. 拷到单位机,解压进 `tps-dashboard/backend/`
+3. Cline 跑一遍 Plan,Sonnet 审一遍代码确认与新版宪法一致
+4. 修任何不一致(目前看应无重大不一致)
+5. 跑一遍 `pip install + psql + create_admin + uvicorn` 验证
+
+**推荐 B 的核心理由**:家用机后端代码已通过认证三件套实测,质量已验证;重写无新增价值,纯浪费 token 与时间。
+
+### 4.3 Phase 1 前端代码
+
+无家用机参考,**单位机正式启动前端骨架开发**——这是 Phase 1 的真正起点。
+
+---
+
+## 五、技术选型(锁定不变,与 v2 一致)
+
+| 层级 | 选型 | 备注 |
+|---|---|---|
+| 前端框架 | React 18 + Vite | — |
+| 前端语言 | **JavaScript**(不用 TS) | 1.0 求快,二期再迁 |
+| UI 库 | Ant Design 5 + 中文 locale | — |
+| 状态管理 | Zustand | 轻,够用 |
+| 路由 | React Router v6 | — |
+| 后端框架 | FastAPI | — |
+| ORM | **SQLModel(同步)** | 不用 async |
+| 数据库迁移 | **手写 SQL**(`backend/sql/00X_*.sql`) | 不用 Alembic |
+| 关系数据库 | PostgreSQL 16 | — |
+| 向量检索 | **pgvector**(PG 扩展) | 不用独立向量库 |
+| 向量维度 | **1536**(为 2.0 wiki 兼容) | 不可改 |
+| AI 嵌入模型 | DeepSeek 或 OpenAI 兼容 embedding API | — |
+| AI 编程模型 | Phase 0-1: Sonnet Plan + DeepSeek pro Act | 详见 `.clinerules` 第二章 |
+| AI 编程模型 | Phase 2 起: MiniMax M2.7 Plan + DeepSeek pro Act | — |
+| 认证 | **Session + Cookie** | 不用 JWT |
+| Word 生成 | docxtpl | — |
+| 甘特图前端库 | frappe-gantt | 不自己用 D3 画 |
+| 定时任务 | APScheduler | Phase 4c 才用 |
+| 部署 | Nginx 反向代理 | — |
+| 版本控制 | **Git + Gitea**(单位 4090D)| 本版新增 |
+
+---
+
+## 六、开发策略
+
+**骨架先行 + 早期上线 + 渐进迭代**:
+
+- Week 1 把骨架搭好(登录走通)
+- Week 6 末必须上线 MVP
+- 后续每 2 周补一个模块,持续上线
+
+**每个 Phase 收尾必做三件事**:
+
+1. **写 phase{N}_log.md**(Claude Opus 4.7 协助生成)
+2. **打 Git tag**:`git tag -a phaseN-complete -m "..." && git push origin phaseN-complete`
+3. **关掉 Cline 当前 Task,新 Phase 起新 Task**
+
+---
+
+## 七、Phase 计划(2-3 个月版)
+
+### Phase 0:环境 + Git(Day 1-2)
+
+**Day 1 上午:核心运行时**
+
+- 装 Python 3.12.x(从 python.org 官方,**不要 Microsoft Store 版**)
+- 装 Node.js 20 LTS(用 nvm-windows)
+- 装 PostgreSQL 16,安装后执行 `CREATE EXTENSION vector;` 验证 pgvector
+
+**Day 1 下午:版本控制(本版新增)**
+
+> 单位 4090D 已装 Git for Windows、已配置全局用户名+邮箱(爱德华项目时弄好的),本节从创建新仓库开始。
+
+- 在 Gitea 创建 `tps-dashboard` 仓库(团队可见,不勾选自动初始化 README)
+- 在本地 clone 仓库到 `D:\TPS-中台\` 或类似路径(避免中文路径)
+- 把五件套(`.clinerules` / `project_plan.md` / `dev_plan.md` / `docs/git_workflow.md` / `README.md`)+ `logs/phase1_log.md` 拷进仓库目录
+- 配置 `.gitignore`(详见 `.clinerules` 第 7.5 节)
+- 首次提交并推送到 Gitea
+
+具体操作步骤详见 `docs/git_workflow.md` 第 2 章"首次仓库初始化"。
+
+**Day 2:开发工具**
+
+- VS Code + Cline 扩展
+- Cline 配置 Plan 模式(Sonnet)+ Act 模式(DeepSeek pro)
+- VS Code 终端打开测试:能跑 `python --version` / `node --version` / `git --version` / `psql --version`
+
+**Phase 0 收尾**:
+
+```bash
+git add -A
+git commit -m "chore: Phase 0 环境与 Git 初始化完成"
+git tag -a phase0-env-ready -m "Phase 0 完成,环境就绪"
+git push origin main
+git push origin phase0-env-ready
+```
+
+写 `logs/phase0_log.md`(可参考 phase1_log.md 格式)。
+
+---
+
+### Phase 1:后端骨架 + 前端骨架(Week 1)
+
+**Day 3-4:后端骨架**
+
+- **路径 B 推荐**:从家用机迁移 backend 整目录,Sonnet 审一遍,跑通验证
+- **路径 A 备选**:从零开始重写
+- 验收:`uvicorn app.main:app --reload` 能起,`/docs` 页面能开,`/api/auth/login` + `/api/auth/me` + `/api/auth/logout` 三接口验证通过
+
+**Day 5-7:前端骨架**
+
+- `npm create vite@latest frontend -- --template react`
+- 装核心依赖:`antd`、`@ant-design/icons`、`zustand`、`react-router-dom`、`axios`
+- 配 Vite 代理(`/api` → `localhost:8000`)
+- `authStore`(Zustand,存当前用户信息)
+- `authService.js`(封装 login / logout / me)
+- 登录页(Ant Design Form)
+- 主布局(侧边栏 + 顶栏 + 内容区)
+- 路由守卫 AuthGuard(未登录跳登录页)
+
+**Week 1 里程碑(Phase 1 完整收官)**:
+
+- 打开浏览器 `http://localhost:5173`
+- 输入 admin / 密码 → 登录成功
+- 看到主框架(侧边栏 + 顶栏 + 占位仪表盘)
+- 刷新页面登录态保持
+- 点登出 → 回到登录页
+
+**Phase 1 收尾动作**:
+
+- 写 `logs/phase1_log.md`(可基于家用机版本扩充)
+- `git tag phase1-complete`,push
+- 关 Cline 当前 Task
+
+---
+
+### Phase 2:仪表盘 + 用户管理 + 历史数据导入(Week 2-3)
+
+**后端**:
+- 收视数据 / 排期 CRUD API
+- 管理员创建账号 API
+- 编辑 episodes / yearly_targets / users 的 SQLModel 模型
+
+**前端**:
+- 仪表盘页面(近 4 期收视 + 未来 6 期排期)
+- 责编录入界面
+- 管理员用户管理界面
+
+**🔧 批量导入工具 v1**:Excel 收视数据一键导入(300 期约 5 分钟)
+- 支持 .xlsx / .csv 上传
+- 提供模板下载
+- 字段映射 + 错误提示
+- 后端用 pandas 解析,批量 INSERT
+- **死规矩**:导入时检测 yearly_targets 是否对应年份齐全,缺则报错让责编先填(防止颜色判定时找不到目标)
+
+**Phase 2 起 Plan 模式切换为 MiniMax M2.7**:Sonnet 余额耗尽前最后一个由 Sonnet 出方案的 Phase,Phase 2 末做切换的复盘评估。
+
+**Phase 2 里程碑**:
+- 责编可以开始录入(或导入)历史收视数据
+- 制片人可以一次性导入已有 300 期 Excel 数据
+- 仪表盘真实数据展示,颜色判定正确(红蓝绿见 `.clinerules` 5.1)
+
+**收尾**:写 `logs/phase2_log.md`,打 `phase2-dashboard-done` tag。
+
+---
+
+### Phase 3:知识库基础设施 + 历史报题单 / 文稿导入(Week 4)
+
+**后端**:
+- 文档上传 + 解析(PDF / docx)
+- embedding 调用(DeepSeek 或 OpenAI 兼容 embedding API)
+- pgvector 存储 + 语义检索 API
+
+**前端**:
+- 知识库管理后台(批量上传、列表、删除)
+
+**🔧 批量导入工具 v2**:
+
+- **报题单批量导入**:支持文件夹整批上传,自动解析字段(选题名/内容概要/编导等)
+  - 制片人 200 期 docx,上传 5-10 分钟,后台 embed 10-30 分钟
+  - 解析失败的文件单独列出,提示制片人修正后重传
+- **文稿单篇审核入库**:
+  - 单文件上传 → 系统解析 + 自动摘要 + 关键词建议
+  - 屏幕展示给制片人审核,确认后入库 + embed
+  - 文稿质量制片人完全可控
+
+**Phase 3 里程碑**:批量导入往期报题单和军报跑通,系统能跑语义检索;制片人审核后逐篇入库文稿。
+
+**收尾**:写 `logs/phase3_log.md`,打 `phase3-knowledge-base` tag。
+
+---
+
+### Phase 4a:核心 MVP(Week 5-6)
+
+**模块 G**:报题单生成与下载(docxtpl 模板)
+- 模板严格遵守"双段结构"(`.clinerules` 5.4)
+
+**模块 A**:选题查重(语义检索 + 历史收视展示)
+- 联动模块 E 展示外拍资源
+
+**模块 C**:知识库参考(检索往期文稿 / 军报)
+
+**前端**:选题提交表单 + AI 反馈页面布局
+
+**🎯 Week 6 末上线 MVP**——团队真的可以用了:登录、看仪表盘、提交选题、看到查重和知识库结果、生成报题单 docx 下载。
+
+**收尾**:写 `logs/phase4a_log.md`,打 `phase4a-mvp-launch` tag。**这是项目第一次"对内发布",务必郑重打 tag**。
+
+---
+
+### Phase 4b:画像 + 甘特图 + 资源(Week 7-9)
+
+- **模块 B**:编导画像建议(AI 反馈中的一段文字,粗框架)
+- **模块 F**:时间可行性 + 甘特图(frappe-gantt)
+- **模块 E**:拍摄资源关联(基础 CRUD + 关联展示)
+- **模块 D**:历史审片意见展示(非预测,仅相似选题原文)
+
+**Phase 4b 里程碑**:TPS 核心功能闭环,编导提交选题后能拿到完整 AI 反馈。
+
+**收尾**:写 `logs/phase4b_log.md`,打 `phase4b-tps-complete` tag。
+
+---
+
+### Phase 4c:热点雷达(Week 10-11)
+
+- 模块 H:今日热点雷达(每位编导个人首页)
+- RSS 订阅源接入 + APScheduler 定时抓取
+- AI 摘要 + 风格化改写(few-shot 用 Phase 3 已积累的往期文稿)
+- 个人首页热点列表 UI(深入 / 收藏 / 忽略)
+- 与 TPS 联动:点[深入了解]预填选题简介
+
+**为什么排在最后**:需要 Phase 3 积累的稿子作为风格学习样本,数据量越大模仿越像。
+
+**收尾**:写 `logs/phase4c_log.md`,打 `phase4c-radar` tag。
+
+---
+
+### Phase 5:部署上线 + Buffer(Week 11-12)
+
+- **新服务器准备**:腾讯云 4核8G 轻量服务器(待租)
+  - Ubuntu 22.04 LTS / Nginx / Python 3.12 / PostgreSQL 16 + pgvector / Node 20
+- **Nginx 反向代理整合**(`project_plan.md` 第八章规划):
+  ```
+  主域名/        → 工作台前端
+  主域名/api     → 工作台后端
+  主域名/tts     → 反代到 101.42.29.217 蓝皓 TTS
+  主域名/mmim    → 反代到 101.42.29.217 MMIM
+  ```
+- **正式上线前必做**:
+  - 把 .env 中 `SECRET_KEY` 改为真实随机值(`python -c "import secrets; print(secrets.token_urlsafe(32))"`)
+  - SessionMiddleware 改 `same_site="strict"` + `https_only=True`
+  - 配 SSL 证书(Let's Encrypt)
+  - 关闭 FastAPI 自动文档 `/docs` 在生产环境的访问(或加密)
+- 简单文档 + bug 修复
+- 留 1 周 buffer
+
+**收尾**:写 `logs/phase5_log.md`,打 `phase5-production` tag,**这是项目正式上线 tag**。
+
+---
+
+## 八、明确推迟到二期 / 砍掉的
+
+- ❌ TypeScript:JS 先行
+- ❌ Alembic:头 3 个月手动管理 schema
+- ❌ async SQLAlchemy:8 人并发同步够用
+- ❌ AI 模型配置 UI:配置文件写死,UI 二期做
+- ❌ 模块 D 的 AI 预测能力:数据足够后再做
+- ❌ 文稿写作辅助系统:二期
+- ❌ Karpathy LLM Wiki 知识库形态:**2.0 重点,1.0 仅预埋接口**
+
+---
+
+## 九、1.0 预埋的 2.0 兼容接口
+
+- 知识库存储格式向 **Markdown + frontmatter** 靠拢(未来可导出 Obsidian)
+- 每条知识库条目预留 `tags`、`related_entities`、`related_concepts` JSONB 字段
+- embedding 维度统一 **1536**(主流,未来通用)
+- 知识库后台支持 .md 格式批量导入导出
+
+---
+
+## 十、项目目录结构
+
+```
+tps-dashboard/                  ← Git 仓库根
+├── .clinerules                 # Cline 协作规则
+├── .gitignore                  # Git 忽略清单
+├── README.md                   # 项目入口说明
+├── project_plan.md             # 产品宪法
+├── dev_plan.md                 # 开发计划(本文档)
+│
+├── docs/                       # 项目文档目录
+│   └── git_workflow.md         # Git 操作手册
+│
+├── logs/                       # 进度日志(只增不删)
+│   ├── phase0_log.md
+│   ├── phase1_log.md
+│   ├── phase2_log.md
+│   └── ...
+│
+├── samples/                    # 样本数据(收视 Excel 等,不进 .gitignore)
+│   └── *.xlsx
+│
+├── frontend/                   # React 前端
+│   ├── src/
+│   │   ├── components/         # 通用组件
+│   │   │   ├── Layout/
+│   │   │   └── AuthGuard/
+│   │   ├── pages/
+│   │   │   ├── Login/
+│   │   │   ├── Dashboard/      # 公共仪表盘
+│   │   │   ├── EditorHome/     # 编导个人首页(含热点雷达)
+│   │   │   ├── TPS/            # 选题策划
+│   │   │   ├── KnowledgeBase/
+│   │   │   └── UserManage/
+│   │   ├── services/           # API 客户端
+│   │   ├── stores/             # Zustand
+│   │   ├── router/
+│   │   ├── utils/
+│   │   ├── App.jsx
+│   │   └── main.jsx
+│   ├── package.json
+│   └── vite.config.js
+│
+├── backend/                    # FastAPI
+│   ├── app/
+│   │   ├── api/
+│   │   │   ├── auth.py
+│   │   │   ├── dashboard.py
+│   │   │   ├── tps.py
+│   │   │   ├── knowledge.py
+│   │   │   ├── radar.py        # 热点雷达
+│   │   │   └── users.py
+│   │   ├── core/
+│   │   │   ├── config.py
+│   │   │   ├── security.py     # session 工具
+│   │   │   └── deps.py
+│   │   ├── models/             # SQLModel 模型(分 Phase 增量加)
+│   │   ├── schemas/            # Pydantic
+│   │   ├── services/
+│   │   │   ├── ai_service.py   # AI 调用
+│   │   │   ├── rag_service.py  # pgvector 检索
+│   │   │   ├── docx_gen.py     # docxtpl 报题单
+│   │   │   └── radar_service.py # 热点抓取 + 风格化
+│   │   ├── db/
+│   │   │   └── session.py
+│   │   └── main.py
+│   ├── sql/                    # 手写 SQL(替代 Alembic)
+│   │   └── 001_init.sql        # 12 张表一次到位
+│   ├── scripts/                # 运维脚本
+│   │   └── create_admin.py     # 交互式创建管理员
+│   ├── templates/              # docxtpl 模板
+│   │   └── baoti_template.docx
+│   ├── requirements.txt
+│   └── .env                    # ⚠️ 不进 Git
+│
+└── nginx/                      # 部署配置(Phase 5 启用)
+    └── nginx.conf
+```
+
+---
+
+## 十一、数据库核心表(12 张,Phase 1 SQL 已建完)
+
+| 表名 | 说明 | 启用 Phase |
+|---|---|---|
+| `users` | 用户/认证 | Phase 1 |
+| `episodes` | 节目期次 + 收视数据 | Phase 2 |
+| `yearly_targets` | 年度收视目标(只增不改) | Phase 2 |
+| `topics` | 选题/报题单 | Phase 4a |
+| `topic_embeddings` | 选题语义向量(1536 维)| Phase 4a |
+| `schedules` | 节目排期 | Phase 4b |
+| `knowledge_items` | 知识库条目(含 tags/related_entities/related_concepts JSONB) | Phase 3 |
+| `knowledge_embeddings` | 知识库向量(1536 维)| Phase 3 |
+| `review_comments` | 审片意见 | Phase 4b |
+| `shooting_resources` | 拍摄资源/人脉 | Phase 4b |
+| `radar_items` | 热点雷达条目 | Phase 4c |
+| `radar_user_actions` | 编导操作记录 | Phase 4c |
+
+> **重要**:`episodes` 表整合了"收视成绩"+"节目元数据"+"外拍信息",作为节目的全生命周期记录。
+> **重要**:`yearly_targets` 表**只增不改**,详见 `.clinerules` 第 5.2 节。
+> **重要**:编导关联用"软引用 + 快照"双字段,详见 `.clinerules` 第 5.3 节。
+
+字段细节见 `backend/sql/001_init.sql`。
+
+---
+
+## 十二、用户与权限
+
+| 角色拼音值 | 中文 | 主要权限 |
+|---|---|---|
+| `zhipianren` | 制片人/管理员 | 全部权限 |
+| `zebian` | 责编 | 维护仪表盘 / 知识库 / 排期 |
+| `biandao` | 编导 | 使用 TPS / 查看知识库 / 生成报题单 / 个人热点雷达 |
+
+不开放公开注册。详见 `.clinerules` 第 5.5 节。
+
+---
+
+## 十三、待确认事项
+
+- [x] 服务器配置:已确认旧机 2核2G,**新租 4核8G 轻量服务器**部署本系统
+- [x] 技术栈(已落定 v2)
+- [x] Phase 计划(已落定 v2)
+- [x] 2.0 路线:Karpathy LLM Wiki 形态,1.0 预埋兼容接口
+- [x] **Git + Gitea 工作流**(本版新增)
+- [x] **Phase 2 起 Plan 切 MiniMax M2.7**(本版新增)
+- [ ] 视觉风格(制片人提供参考图)
+- [ ] 6 名编导初始画像描述(每位 200 字)
+- [ ] 甘特图样本(可用通用电视节目模板起步)
+- [ ] 腾讯云新服务器开租时机(Phase 4c 中段)
+
+---
+
+## 十四、会话恢复说明
+
+**下次跟新对话框的 Claude 接力时,告诉它**:
+
+> "请阅读 `project_plan.md`、`dev_plan.md`、`.clinerules`、`docs/git_workflow.md` 这是我们的项目宪法。`logs/` 下的 phase{N}_log.md 是已完成 Phase 的进度档案。从最新一份 log 的下一步继续。"
+
+---
+
+## 十五、版本演进
+
+| 版本 | 日期 | 主要变化 |
+|---|---|---|
+| v1 | 2026-04 | 初版 |
+| v2 | 2026-05-04 | 精简技术栈、Phase 拆分(避免 Phase 4 大爆炸)、明确每周里程碑 |
+| **v3** | **2026-05-06** | **加 Git + Gitea 工作流;Phase 0 重排(纳入 Git);Phase 2 起 Plan 切 MiniMax M2.7;明确单位机重启路径(路径 B 推荐);新增 docs/ 目录与 phase{N} tag 收尾仪式** |
+
+---
+
+*本文件最高优先级中的"技术宪法"。任何阶段安排冲突以本文为准。*
+*下次修订建议时机:Phase 4a MVP 上线后(根据使用反馈调整 Phase 4b/4c 优先级)。*

docs/git_workflow.md

@@ -0,0 +1,438 @@
+# docs/git_workflow.md — Git 操作手册
+
+> 项目:TPS 中台
+> 仓库:`tps-dashboard`(单位 Gitea)
+> 文档版本:v1 · 2026-05-06
+> 受众:**制片人(不会 Git)** + Cline(自动遵守此规则)
+
+---
+
+## 阅读说明
+
+本手册分两部分:
+
+- **第 1-3 章**:**给制片人看的**——每一步具体到敲哪条命令、看到什么算成功
+- **第 4-5 章**:**给 Cline 看的规则**——commit 规范、提交时机、Cline 的边界
+
+不会 Git 没关系——**照本宣科,你只需要会复制粘贴**。
+
+---
+
+## 第 1 章:基础概念(只讲能用上的)
+
+### 1.1 三个核心概念,一分钟搞定
+
+**Git 仓库**:就是一个"被 Git 管起来的文件夹"。打开本地 `D:\TPS-中台\` 这个文件夹,里面有所有项目文件 + 一个隐藏的 `.git` 子目录。**不要删 `.git`**,删了等于把保险撕了。
+
+**commit(提交)**:相当于"存档"。每一次 commit 是一个时间点的快照,以后可以回到这个时间点。
+
+**push(推送)**:把本地的 commit 同步到 Gitea 服务器。**push 之后才算"上传"了**,不 push 同事看不到。
+
+**pull(拉取)**:把 Gitea 上的最新代码拉到本地。多设备开发时,**每天开工第一件事就是 pull**。
+
+### 1.2 用菜场买菜类比
+
+- 在家做饭(写代码)= 本地修改
+- 用保鲜盒装好放冰箱(commit) = 本地存档
+- 把保鲜盒带去单位食堂大冰柜(push) = 推到 Gitea
+- 同事来食堂找出你的盒子带回家(pull) = 拉到他自己电脑
+
+只要保鲜盒进了食堂大冰柜,谁来都能拿。
+
+---
+
+## 第 2 章:首次仓库初始化(Phase 0 Day 1 下午做)
+
+> 单位 4090D 已装 Git、已配 用户名+邮箱(爱德华项目时弄好)。本章从创建新仓库开始。
+
+### 2.1 在 Gitea 创建新仓库
+
+**操作位置**:浏览器打开单位 Gitea 网址(就是你登爱德华项目的那个 Gitea)
+
+1. 右上角点 `+` → 选 `新建仓库`(或英文 `New Repository`)
+2. 填写表单:
+   - **仓库名称**:`tps-dashboard`
+   - **描述**:`TPS 中台 — 央视《军事科技》栏目内部工作台`
+   - **可见性**:勾选 **"私有"** 或 **"团队可见"**(注意:跟爱德华那个公开仓库**不一样**,这个不公开)
+   - **勾选项一定不要勾**:**不要勾** "Initialize Repository(With selected files and template)" —— 我们要的是空仓库
+3. 点底部 `创建仓库`
+
+**成功标志**:页面跳到一个新页面,显示 `tps-dashboard` 是空的,中间有一段灰底的命令提示,大概长这样(具体地址你以你那台 Gitea 的 URL 为准):
+
+```
+git clone http://你的Gitea地址/你的用户名/tps-dashboard.git
+```
+
+**把这一行复制下来,下一步要用**。
+
+### 2.2 在本地 clone 仓库
+
+**操作位置**:VS Code 打开任何窗口都行,在终端面板里执行(快捷键 `Ctrl + ` `)
+
+```powershell
+# 切换到你想放项目的位置(避免中文路径,推荐 D:\)
+cd D:\
+
+# 把刚才复制的 clone 命令粘贴运行
+git clone http://你的Gitea地址/你的用户名/tps-dashboard.git
+```
+
+**期间可能要求输入 Gitea 账号密码**——输入即可,Git 会记住。
+
+**成功标志**:终端显示类似:
+```
+Cloning into 'tps-dashboard'...
+warning: You appear to have cloned an empty repository.
+done.
+```
+
+`warning: empty repository` 是**正常的**——本来就是空仓库,不是错误。
+
+完成后 `D:\` 下多了一个 `tps-dashboard` 文件夹。
+
+### 2.3 进仓库目录
+
+```powershell
+cd D:\tps-dashboard
+```
+
+之后所有 git 命令都在这个目录里跑。
+
+### 2.4 把五件套 + log 拷进来
+
+> 你应该已经从 Claude.ai 下载了这五份文件:`.clinerules`、`project_plan.md`、`dev_plan.md`、`docs/git_workflow.md`、`README.md`,加上 `logs/phase1_log.md`。
+
+**手动操作**(用 Windows 资源管理器):
+
+1. 在 `D:\tps-dashboard\` 下:
+   - 直接拷入 `.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`(平铺四份)
+   
+2. 在 `D:\tps-dashboard\` 下**新建文件夹** `docs`,把 `git_workflow.md` 拷进去
+
+3. 在 `D:\tps-dashboard\` 下**新建文件夹** `logs`,把 `phase1_log.md` 拷进去
+
+**最终结构应该是**:
+
+```
+D:\tps-dashboard\
+├── .clinerules
+├── project_plan.md
+├── dev_plan.md
+├── README.md
+├── docs\
+│   └── git_workflow.md
+└── logs\
+    └── phase1_log.md
+```
+
+### 2.5 创建 .gitignore
+
+`.gitignore` 是"告诉 Git 哪些文件不要管"的清单。
+
+**操作**:在 VS Code 终端里执行:
+
+```powershell
+cd D:\tps-dashboard
+notepad .gitignore
+```
+
+记事本会弹出来(可能问你"找不到文件,要创建吗?"——选 **是**)。
+
+把下面这些粘贴进去,**保存**:
+
+```
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+venv/
+env/
+
+# Node
+node_modules/
+dist/
+build/
+.vite/
+
+# 环境配置(永远不上传)
+.env
+.env.local
+
+# 编辑器
+.vscode/
+.idea/
+*.swp
+
+# 操作系统
+.DS_Store
+Thumbs.db
+
+# 日志运行产物
+*.log
+cookie.txt
+
+# 临时文件
+*.tmp
+*.bak
+```
+
+### 2.6 第一次 commit 和 push
+
+**操作**:VS Code 终端里依次执行:
+
+**第 1 条:看看 Git 看到了哪些文件**
+
+```powershell
+git status
+```
+
+**成功标志**:终端会列出一堆文件(.clinerules、project_plan.md 等),颜色应该是**红色**(表示"未跟踪")。
+
+**第 2 条:把所有文件加进暂存区**
+
+```powershell
+git add -A
+```
+
+**成功标志**:命令执行无任何输出(Git 的传统是"没消息就是好消息")。再跑一次 `git status`,文件应该变成**绿色**了。
+
+**第 3 条:第一次 commit**
+
+```powershell
+git commit -m "chore: 项目宪法五件套 + Phase 1 家用机日志初始化"
+```
+
+**成功标志**:终端显示类似:
+```
+[main (root-commit) abc1234] chore: 项目宪法五件套 + Phase 1 家用机日志初始化
+ 6 files changed, 1234 insertions(+)
+ create mode 100644 .clinerules
+ ...
+```
+
+**第 4 条:推送到 Gitea**
+
+```powershell
+git push -u origin main
+```
+
+> 如果你的 Gitea 默认分支不叫 main 而叫 master,把命令里的 `main` 换成 `master`。
+
+**期间可能要求输入 Gitea 账号密码**,输入即可。
+
+**成功标志**:终端显示类似:
+```
+Enumerating objects: ...
+Writing objects: 100% (...)
+To http://你的Gitea地址/你的用户名/tps-dashboard.git
+ * [new branch]      main -> main
+branch 'main' set up to track 'origin/main'.
+```
+
+### 2.7 验证:浏览器看 Gitea
+
+刷新一下 Gitea 那个 `tps-dashboard` 页面——**应该能看到所有文件出现了**,不再是空仓库。
+
+**到此 Phase 0 Day 1 下午的 Git 部分完成**。继续 Day 2 装 VS Code + Cline。
+
+---
+
+## 第 3 章:日常使用(每天会用到的命令)
+
+### 3.1 每天开工第一件事
+
+```powershell
+cd D:\tps-dashboard
+git status                # 看看本地有没有未提交的改动
+git pull                  # 拉 Gitea 最新(如果别的机器推过)
+```
+
+### 3.2 每次离开机器前
+
+```powershell
+git status                # 看看有没有未提交的
+# 如果有改动,让 Cline 自己 commit + push;
+# 或者你手工(下面)
+```
+
+### 3.3 让 Cline 帮你提交
+
+最方便的方式——**让 Sonnet 在 Plan 里下命令**:
+
+> "现在改完了,请帮我 commit + push,commit message 写: feat: 添加 XXX 功能"
+
+Cline(Sonnet → DeepSeek)会自动跑 git add / git commit / git push。**这是默认推荐方式**。
+
+### 3.4 你自己手工提交(备选)
+
+```powershell
+cd D:\tps-dashboard
+git add -A
+git commit -m "fix: 修复登录页跳转问题"
+git push
+```
+
+### 3.5 Phase 收尾仪式(打 tag)
+
+每完成一个 Phase,**让 Cline 替你做这一套动作**:
+
+```powershell
+git tag -a phase1-complete -m "Phase 1 后端 + 前端骨架完工"
+git push origin phase1-complete
+```
+
+**tag 命名规则**(`.clinerules` 第 7.4 节锁定):
+
+- `phase0-env-ready`
+- `phase1-complete`
+- `phase2-dashboard-done`
+- `phase3-knowledge-base`
+- `phase4a-mvp-launch` ← **这是项目第一次对内发布,郑重一点**
+- `phase4b-tps-complete`
+- `phase4c-radar`
+- `phase5-production` ← **这是项目正式上线**
+
+---
+
+## 第 4 章:commit message 规范(给 Cline 守的规矩)
+
+### 4.1 格式
+
+```
+<type>: <中文正文>
+
+[可选:更详细的中文说明]
+```
+
+### 4.2 type 取值表
+
+| type | 中文 | 示例 |
+|---|---|---|
+| `feat` | 新功能 | `feat: 添加用户登录接口` |
+| `fix` | 修 bug | `fix: 修复 created_at 字段 NOT NULL 报错` |
+| `docs` | 改文档 | `docs: 更新 phase1_log` |
+| `chore` | 杂项(依赖、配置)| `chore: 升级 bcrypt 到 4.0.1` |
+| `refactor` | 重构 | `refactor: 重构 authStore 状态管理` |
+| `style` | 格式化(空格/缩进)| `style: 统一前端缩进为 2 空格` |
+| `test` | 加测试 | `test: 添加 auth 接口测试` |
+
+**前缀英文小写,正文中文**——前缀方便工具分类,正文方便人阅读。
+
+### 4.3 提交时机
+
+每个独立动作单独 commit,**不要堆一坨大 commit**:
+
+- 装完依赖 → 立刻 commit
+- 建完 SQL 表 → 立刻 commit
+- 写完一个完整接口 → 立刻 commit
+- 修完一个 bug → 立刻 commit
+
+**禁止**:"晚上一起 commit"或"一个 commit 多功能"。
+
+---
+
+## 第 5 章:Cline 的 Git 边界(给 AI 守的规矩)
+
+### 5.1 Cline 可以自动执行(无需问用户)
+
+- `git add`
+- `git commit`
+- `git push`(限当前分支)
+- `git pull`
+- `git status`
+- `git log`(查看历史)
+- `git tag -a` + `git push origin <tag>`
+
+### 5.2 Cline 必须停下问用户
+
+- `git reset --hard`(任何形式的 hard reset)
+- `git push --force` / `git push -f`
+- `git rebase`(任何形式)
+- 删除分支:`git branch -d` / `git branch -D`
+- 删除 tag:`git tag -d` / `git push origin --delete <tag>`
+- 删除远程引用
+
+### 5.3 永远禁止
+
+- 删除整个 `.git/` 目录
+- 修改 `.git/` 目录内任何文件
+
+---
+
+## 第 6 章:常见问题速查
+
+### Q1:我推不上去,提示"Permission denied"
+
+**原因**:Gitea 账号密码错或没权限
+**解决**:确认你登录 Gitea 网页版能正常访问 `tps-dashboard` 仓库;如果能,重新输入账号密码即可。
+
+### Q2:`git push` 时提示"rejected,请先 pull"
+
+**原因**:Gitea 上有别的设备推过新内容,本地落后了
+**解决**:先 `git pull`,再 `git push`。如果 pull 时报 conflict(冲突),停下问 Cline 或我。
+
+### Q3:`git status` 看到一堆 .pyc 或 node_modules
+
+**原因**:`.gitignore` 没生效
+**解决**:确认 `.gitignore` 文件就在仓库根目录(`D:\tps-dashboard\.gitignore`),内容跟第 2.5 节一致。
+
+### Q4:不小心 commit 了 .env 文件怎么办
+
+**严重**:`.env` 含密码,绝不能进 Gitea。
+**解决**:**立刻停下找 Claude Opus 4.7 处理**——这事儿要小心做,不要自己瞎搞,容易把历史搞乱。
+
+### Q5:换了一台机器,怎么把代码搞过来
+
+```powershell
+cd D:\
+git clone http://你的Gitea地址/你的用户名/tps-dashboard.git
+cd tps-dashboard
+# 然后跟原来一样开工就行
+```
+
+### Q6:某次 commit 写错了想撤回
+
+**只在最近一次 commit 还没 push 时可撤回**:
+
+```powershell
+git reset HEAD~1     # 撤回最近一次 commit,文件改动保留
+```
+
+**已经 push 的 commit**:不要自行处理,找 Claude Opus 4.7。
+
+---
+
+## 第 7 章:多设备同步(家用机 ↔ 单位机)
+
+### 离开 A 机器前
+
+```powershell
+git status         # 看有没有未提交的
+git add -A         # 加进暂存
+git commit -m "..."
+git push
+```
+
+### 到 B 机器开工
+
+```powershell
+git pull           # 拉最新
+git status         # 确认干净
+# 开始干活
+```
+
+**铁律**:**永远在 push 之前 pull**,永远在开工前 pull。这两条做到,99% 不会冲突。
+
+---
+
+## 第 8 章:版本演进
+
+| 版本 | 日期 | 变化 |
+|---|---|---|
+| v1 | 2026-05-06 | 初版 |
+
+---
+
+*本文件与 `.clinerules` 第七章互为补充。Cline 必须遵守第 4-5 章规则。*

logs/phase1_log.md

@@ -0,0 +1,168 @@
+# 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。
+
+---
+
+## 五、遗留事项(Phase 1 收尾或未来 Phase 必须处理)
+
+### 5.1 Phase 1 内部待完成
+
+- [ ] **前端骨架开发**:Vite + React + AntD + Zustand 初始化,登录页 + 主布局 + 路由鉴权
+- [ ] **前后端联调验收**:浏览器登录 → 看到主框架 → 刷新登录态保持 → 登出回到登录页
+- [ ] **本地后端首次启动验证**:psql 跑 001_init.sql、create_admin.py 创管理员、uvicorn 启动后端、curl 或浏览器测三个接口
+
+### 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/**
+
+---
+
+## 六、本 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。*

project_plan.md

@@ -0,0 +1,341 @@
+# project_plan.md — TPS 中台项目策划书
+
+> 项目:TPS(Topic Planning System)中台 — 央视《军事科技》栏目内部工作台
+> 仓库:`tps-dashboard`
+> 修订版本:v3 · 2026-05-06
+> 制片人:刘统
+> 协作大模型:Claude Opus 4.7(顾问)+ Sonnet 4.6(Plan,Phase 2 起切 MiniMax M2.7)+ DeepSeek pro(Act,全程)
+
+---
+
+## 一、文档定位
+
+本文是**项目产品宪法**——讲"做什么、为谁做、为什么这么做"。
+
+技术实施细节、阶段时间线在姊妹文档 `dev_plan.md`;协作规则在 `.clinerules`。
+
+**这三份文件长期不变**;每周执行细节进 `logs/phase{N}_log.md`,不进本文。
+
+---
+
+## 二、项目背景
+
+### 2.1 谁在用
+
+央视《军事科技》栏目核心团队,共 8 人:
+
+- **制片人**(刘统):管理员,产品决策
+- **责编**(1 人):维护排期、收视、知识库
+- **编导**(6 人):核心生产者,选题策划与节目执行
+
+### 2.2 现存痛点
+
+栏目目前的工作流散落在多个工具里——Excel(收视数据 + 排期)、Word(报题单 + 文稿)、微信群(线索沟通)、个人电脑(往期节目素材)、师傅徒弟口口相传(选题判断经验)。具体痛点:
+
+1. **历史选题查重靠脑子**:编导提一个选题,没人能快速回答"这个我们做过没有、做的几次什么收视、有没有踩过坑"。新编导尤其吃力。
+2. **报题单格式与质量参差**:每个编导写的报题单结构、详略、专业度都不一样,制片人审起来费劲。
+3. **知识库碎片化**:往期文稿、军报材料、专家库、外拍线索都在各自电脑/微信里,新编导接手等于从零开始。
+4. **AI 时代焦虑**:看到同行开始用 AI,但栏目缺一个**懂栏目业务、又不替代编导主权**的工具。
+5. **数据没有沉淀**:每年都做 100+ 期节目,但**收视成绩、审片意见、外拍资源都没结构化沉淀**,经验靠人不靠系统。
+
+### 2.3 项目核心价值主张
+
+**辅助而不替代,AI 给方向不给答案,保护编导创作主权。**
+
+这一条贯穿所有模块设计、所有 AI Prompt、所有 UI 决策。任何让 AI 替编导拍板的功能都不要做;任何把编导逼向"按 AI 建议改"的设计都要重做。
+
+---
+
+## 三、项目目标
+
+### 3.1 短期目标(2-3 个月,Phase 5 末)
+
+交付一个 **8 人团队真的会用起来的** MVP,涵盖:
+
+- 登录与权限
+- 公共仪表盘(收视成绩 + 排期一目了然)
+- 历史数据导入(责编可一次性导入 300+ 期 Excel)
+- 知识库(往期报题单 / 文稿 / 军报)
+- TPS 选题策划(查重 + 知识库参考 + 报题单生成)
+- 编导个人首页 + 热点雷达
+
+**Week 6 末必须有团队可用版本上线**——这条比"功能齐全"更重要。
+
+### 3.2 中期目标(2.0,半年至一年)
+
+向 **Karpathy LLM Wiki 形态**演进:从"原始资料堆 + 检索"升级到"概念卡片 + 关联网络 + 自动综述"。
+
+1.0 不做,但 1.0 设计时**预埋兼容接口**(知识库存储格式、tags / related_entities / related_concepts 字段、embedding 维度 1536 等)。
+
+### 3.3 远期目标(2-3 年)
+
+文稿写作辅助系统、AI 配音深度联动(借用蓝皓 TTS 2.0)、多栏目复用工作台底座。
+
+---
+
+## 四、用户与权限
+
+| 角色 | 中文 | 拼音值(代码) | 主要权限 |
+|---|---|---|---|
+| 管理员 | 制片人 | `zhipianren` | 全部权限,可创建账号、修改全局设置 |
+| 责编 | 责编 | `zebian` | 维护仪表盘 / 知识库 / 排期,不能改全局设置 |
+| 编导 | 编导 | `biandao` | 使用 TPS / 查看知识库 / 生成报题单 / 个人热点雷达,不能改他人内容 |
+
+**关键约束**:
+
+- **不开放公开注册**——账号一律由管理员创建
+- **离职编导不删除**——保留其历史作品的姓名快照,见 `.clinerules` 第 5.3 节
+- 角色英文枚举值**不再改**(已锁定为拼音)
+
+---
+
+## 五、产品功能模块(8 个)
+
+### 模块 A — 选题查重(TPS 核心入口)
+
+**痛点**:编导提一个选题,担心做过、想知道历史成绩。
+
+**功能**:
+- 编导输入选题简介 → 系统语义检索往期 `topics` + `episodes`
+- 列出 5 条相似度最高的历史节目,**展示原文 + 当年收视成绩 + 颜色标识(红蓝绿)**
+- 点开任一相似节目 → 联动模块 E,展示**外拍联系人 / 联系方式 / 线索来源**
+- 编导自行判断:"这选题做过但收视很高可以重做"或"这个角度我们没碰过"
+
+**AI 哲学**:**不告诉编导"建议放弃 / 建议做"**,只展示事实让其自决。
+
+### 模块 B — 编导画像建议
+
+**痛点**:新编导不知道自己擅长什么、容易在哪类选题上栽跟头。
+
+**功能**:
+- 在 AI 反馈中插入一段画像建议(如:"小张过去 12 期偏向装备评测,这次涉及历史人物可能需要更多顾问支持")
+- 画像数据来源:`users.profile_text` 字段 + 该编导历史选题/收视统计
+- **永远显式标注"仅供参考"**,且有"忽略"按钮
+
+**1.0 形态**:粗框架,文字一段。
+**2.0 形态**:动态画像,根据每期作品自动迭代。
+
+### 模块 C — 知识库参考
+
+**痛点**:写选题时缺背景资料,需要去翻往期文稿、军报、专家观点。
+
+**功能**:
+- 提交选题时,系统语义检索 `knowledge_items`(往期文稿 + 军报 + 内部资料)
+- 列出 3-5 条最相关条目,展示摘要 + 关键词,可点开查看原文
+- 编导可选择性引用,**引用关系入库**(为未来"知识溯源"打基础)
+
+**关键技术**:pgvector + DeepSeek embedding(或 OpenAI 兼容 embedding API)+ 1536 维向量。
+
+### 模块 D — 历史审片意见展示
+
+**痛点**:制片人审过的稿子有些反复出现的意见(比如"开头节奏太慢"),编导写新稿时不知道要避开。
+
+**功能**:
+- **不做 AI 预测**,只展示事实
+- 当编导在 TPS 中提交相似选题时,系统检索往期 `review_comments`,展示 2-3 条相似选题的原始审片意见原文
+- 编导自己读、自己消化
+
+**为什么不做 AI 预测**:数据量太小,预测容易胡说;原文展示让编导自己判断,符合"AI 不替决策"哲学。**等数据累积充分后再考虑 2.0 加预测能力**。
+
+### 模块 E — 拍摄资源关联
+
+**痛点**:外拍找谁问、找哪个单位、上次怎么联系上的——栏目没有结构化记录。
+
+**功能**:
+- 独立的拍摄资源库(`shooting_resources` 表,存联系人 / 单位 / 专长 / 上次合作期次)
+- 与 `episodes` 表的 `outdoor_contact_person` / `outdoor_contact_info` / `lead_source` 联动
+- 模块 A 查重命中相似节目时,自动展开"找谁能问到"提示
+
+### 模块 F — 时间可行性 + 甘特图
+
+**痛点**:选题提了不知道排期能不能赶上;制片人不知道哪几期已经塞满了。
+
+**功能**:
+- 编导提选题时显示"距离最近一个空档还有几天"
+- 制片人页面有甘特图视图(frappe-gantt),拖拽调整排期
+
+### 模块 G — 报题单生成与下载
+
+**痛点**:报题单格式各编导各异,审核耗时。
+
+**功能**:
+- 编导填好选题信息 + 选好相似参考 + 选好知识库引用 → 一键生成 `.docx` 报题单
+- 模板由 docxtpl 渲染,**严格遵守"双段结构"**(引子 + 列举,见 `.clinerules` 第 5.4 节)
+- 编导可下载、修改、打印
+
+### 模块 H — 编导个人首页 + 热点雷达
+
+**痛点**:编导想知道"今天有什么军事新闻可能值得做",目前靠各自刷微博/微信。
+
+**功能**:
+- 个人首页(每位编导自己一份)
+- **今日热点雷达**:RSS 抓取 + AI 摘要 + 风格化改写(用栏目历史文稿 few-shot)
+- 每条热点有"深入了解 / 收藏 / 忽略"三个按钮
+- 点"深入了解"自动跳转 TPS,预填选题简介
+
+**为什么放最后做(Phase 4c)**:需要 Phase 3 积累的稿子作为风格学习样本,数据量越大,模仿越像。
+
+---
+
+## 六、关键业务规则(死规矩,务必死守)
+
+> 这一节内容跟 `.clinerules` 第五章重复——双份保险,任一文件被改都不会丢。
+
+### 6.1 收视颜色判定(色彩规约反直觉)
+
+只对收视份额(`audience_share`)上色:
+
+- 🔴 红色 = 超过当年摸高目标 = **优秀**(不是警告)
+- 🔵 蓝色 = 在基础与摸高之间 = 达标
+- 🟢 绿色 = 低于当年基础目标 = **待提升**(不是安全)
+
+**通用习惯红警绿安,栏目反过来。**
+
+### 6.2 年度目标只增不改(时间不变性)
+
+`yearly_targets` 每年新增一行,**绝不覆盖历史年份**。每期节目按其播出年份的目标判颜色,2024 年的节目永远按 2024 年的目标判,2026 年回看也不会变色。
+
+### 6.3 编导关联用"软引用 + 快照"
+
+`episodes.editor_id`(可空)+ `episodes.editor_name_snapshot`(必填)。离职编导不删档,只置空 editor_id、保留快照。
+
+### 6.4 报题单内容概要的双段结构
+
+默认:**引子(200-300 字)+ 列举(3-5 条 Markdown 序号,每条以 `**加粗关键词**` 开头)**。
+备选:纯叙述,**仅当编导明确指定才用**。
+
+---
+
+## 七、技术栈与红线(精简版)
+
+> 详细请见 `dev_plan.md`,本节给非技术读者一个全貌。
+
+| 层级 | 选型 |
+|---|---|
+| 前端 | React 18 + Vite + Ant Design 5(JavaScript,不用 TypeScript) |
+| 状态 | Zustand |
+| 后端 | FastAPI + SQLModel(同步,不用 async) |
+| 数据库 | PostgreSQL 16 + pgvector(1536 维,统一) |
+| 认证 | Session + Cookie(不用 JWT) |
+| AI | MiniMax M2.7 编程主力 + DeepSeek embedding |
+| Word 生成 | docxtpl |
+| 部署 | Nginx 反向代理(整合 TPS / 蓝皓 TTS / MMIM) |
+
+---
+
+## 八、双服务器整合架构
+
+```
+                  ┌────────────────────┐
+   主域名访问 →   │  腾讯云 4核8G 新机  │  ← TPS 中台主体
+                  │  (Nginx + FastAPI │
+                  │   + PostgreSQL +  │
+                  │   React 前端)     │
+                  └─────────┬──────────┘
+                            │
+                       Nginx 反代
+                            │
+                            ▼
+                  ┌────────────────────┐
+                  │  老服务器 2核2G    │  ← 蓝皓 TTS 2.0 + MMIM
+                  │  101.42.29.217     │     (已上线运行中)
+                  └────────────────────┘
+```
+
+**用户体验**:从主域名进,在 TPS 工作台菜单里能跳转到 TTS,无感知是另一台服务器。
+
+**反代路径规划**(Phase 5 部署时实施):
+
+```
+主域名/        → TPS 前端 (本机)
+主域名/api     → TPS 后端 API (本机)
+主域名/tts     → 反代到 101.42.29.217 (蓝皓 TTS)
+主域名/mmim    → 反代到 101.42.29.217 (MMIM)
+```
+
+---
+
+## 九、项目阶段总览
+
+> 详细每周里程碑见 `dev_plan.md`,本节给一个全局视图。
+
+| Phase | 时间 | 核心交付 | 完成度 |
+|---|---|---|---|
+| Phase 0 | Day 1-2 | 环境搭建(Python/Node/PG/Git) | 家用机已完成,单位机重启 |
+| Phase 1 | Week 1 | 后端 + 前端骨架 + 登录跑通 | 家用机后端已完成,前端待 |
+| Phase 2 | Week 2-3 | 仪表盘 + 用户管理 + Excel 导入 | 未开始 |
+| Phase 3 | Week 4 | 知识库基础设施 + 报题单导入 | 未开始 |
+| Phase 4a | Week 5-6 | **MVP 上线**(报题单生成 + 查重 + 知识库参考) | 未开始 |
+| Phase 4b | Week 7-9 | 画像 + 甘特图 + 资源 | 未开始 |
+| Phase 4c | Week 10-11 | 热点雷达 | 未开始 |
+| Phase 5 | Week 11-12 | 部署上线 + 反向代理整合 + Buffer | 未开始 |
+
+---
+
+## 十、AI 模型分工(2026-05-06 拍板)
+
+| 阶段 | Plan 模式 | Act 模式 | 备注 |
+|---|---|---|---|
+| Phase 0-1(骨架期) | **Sonnet 4.6** | DeepSeek v4 pro | 骨架期 Plan 用 Sonnet 保质量 |
+| Phase 2 起 | **MiniMax M2.7**(标准版)| DeepSeek v4 pro | **Sonnet 余额耗尽后切换** |
+| 顾问层 | Claude Opus 4.7(claude.ai 网页) | — | 关键决策、架构审核、卡壳兜底 |
+
+**为什么换的是 Plan 不是 Act**:
+
+Plan 模式(出方案 / 审改动)的调用频次远高于 Act 模式,Sonnet 单次调用又比 DeepSeek 贵 50 倍——**钱主要花在 Plan 上**。把 Plan 从 Sonnet 换成 MiniMax M2.7,单次成本降至原来的 1/50,Act 不动。
+
+DeepSeek pro 在家用机 Phase 1 后端骨架阶段已验证可用,搭配稳定,**没必要换**。
+
+**MiniMax M2.7 选型理由**:
+
+- 性能对标 Claude Opus(SWE-bench 78%、Agent 工具调用稳定)——胜任 Plan 出方案的复杂推理
+- 价格仅 Claude Opus 的 1/50
+- 中文原生,理解栏目术语优势明显
+- OpenAI 兼容接口,Cline 切换成本几乎为零
+- 制片人此前用 MiniMax 做过蓝皓 TTS 2.0,有合作经验
+
+**接入信息**:`base_url = https://api.minimaxi.com/v1`,Model ID = `MiniMax-M2.7`(标准版,非 highspeed)。
+
+---
+
+## 十一、风险与应对
+
+| 风险 | 概率 | 应对 |
+|---|---|---|
+| Phase 1 前端骨架延期 | 中 | 单位机有家用机的代码 zip 可参考,降低重写成本 |
+| MiniMax M2.7 切入 Plan 后方案质量下降 | 中 | 临时切回 Sonnet 顶住,Phase 2 末复盘是否回切 |
+| 历史 Excel / docx 导入解析失败 | 高 | 解析失败的文件单独列出,提示责编手工修正后重传 |
+| 编导抗拒使用新工具 | 中 | "辅助不替代"的产品哲学贯穿,绝不强制;先让最积极的 1-2 位编导先用,产生口碑 |
+| 收视目标变化导致颜色判定混乱 | 低 | 时间不变性原则保护历史(yearly_targets 只增不改) |
+| 单位 4090D Gitea 故障 | 低 | 制片人本地 Git 仓库 + 远程备份,不全部押在 Gitea 上 |
+
+---
+
+## 十二、不在 1.0 范围内的事
+
+明确不做、留到 2.0 或更远的:
+
+- TypeScript 改造
+- Alembic 数据库迁移
+- async SQLAlchemy
+- AI 模型配置 UI(模型 / API Key 配置写在 .env)
+- 模块 D 的 AI 预测(只展示原文)
+- 文稿写作辅助系统
+- Karpathy LLM Wiki 知识形态(仅预埋接口)
+- 移动端 App
+- 多栏目复用(架构上预留可能,1.0 不实现)
+
+---
+
+## 十三、版本演进
+
+| 版本 | 日期 | 主要变化 |
+|---|---|---|
+| v1 | 2026-04 | 初版,定模块 A-G(7 个) |
+| v2 | 2026-05-04 | 加模块 H 热点雷达,增 2.0 兼容预埋说明 |
+| **v3** | **2026-05-06** | **加 MiniMax M2.7 接班 Plan 模式分工(第十章)、Git 仓库信息、单位机重启路径、风险表中 Gitea 项;DeepSeek pro 全程在岗 Act** |
+
+---
+
+*本文件最高优先级中的"产品宪法"。技术与协作详见姊妹文档。*
+*下次修订建议时机:Phase 5 末(MVP 上线后,根据真实使用反馈修订 2.0 路线图)。*