CLAUDE.md

- # 项目协作主控文件 (CLAUDE.md)

  <!--
    Claude Code 每次开 session 自动读取。两个角色：
      1) 项目说明书（稳定：是什么、用什么、怎么跑、什么不能碰）
      2) 跨工具活快照交接区（动态：现在到哪、下一步、刚定的决定）
    维护原则：增量更新，改对应小节，不整篇重写、不删历史。
    本文件与项目宪法（.clinerules / project_plan.md / dev_plan.md / docs/git_workflow.md）并列，
    不复制宪法内容，只指向 + 抽取仍生效的关键决策。新对话接手时连同宪法一并阅读。
  -->

  ---

  ## 🔖 状态栏（每次结束 session 前必须更新这三行）

  - **最后更新**：Claude（顾问）｜ 2026-07-03
  - **当前状态一句话**：远程仓库已迁至腾讯云 Gitea（101.42.29.217:3000），双机开发就绪；git 历史已清理大文件（769MB→5MB）。Phase 3 知识库已完成，主干暂停。
  - **下一个动手的人从这里开始**：见下方「⏩ 交接备注」

  ---

  ## 🤖 给 AI 的工作约定（READ FIRST）

  - 开工前先读完：本文件「状态栏 / 交接备注 / 关键决策」三节 + 四份宪法 + 两份外迁寄存条（`寄存条_看板升级已外迁.md`、`寄存条_doco子项目已外迁.md`）。
  - **角色定位**：Claude Code 默认是**顾问**——出方案、审 Plan、卡壳兜底、写交接文档。**写代码（Plan + Act）交给 Cline，不要架空 Cline**。顾问位是为**省 token**：日常 CRUD、常规实现不该 Claude Code 亲自写。**仅两种情况下场动手**：① Cline 连续几次改都过不去的坎；② 制片人明确点名让 Claude Code 操刀。
  - 给 Cline 的指令一律用**代码块**封装，方便复制；不要让制片人手动粘贴整份文件内容。
  - 完成一段工作 → **增量更新**：在「已完成」追加一条、「待办」勾掉/新增、必要时补「关键决策」，最后改「状态栏」三行。只追加/勾选，不重写、不删历史。
  - 涉及**发送、发布、删除、改权限、付款、跑 schema 迁移**等不可逆操作前，先在对话里跟制片人确认。
  - Git 红线：`git reset --hard` / `push --force` / `rebase` / 删分支删 tag —— **必须停下问制片人**，永不自动执行；删整个 `.git` 永远禁止。
  - **沟通**：全程简体中文；制片人不懂代码，解释说人话、最小化技术语言；给明确推荐而非反复抛选项；复杂决策配可视化产物（HTML 原型 / 气泡图）辅助。回复简明，不堆中间过程。

  ---

  ## 🧩 子项目关系 / 话题边界（外迁禁区）

  主干保持稳定，复杂功能拆成独立子项目（独立 chat / 独立 PRD）。**以下话题已外迁，主项目里聊到要先反问「这是子项目的事还是主干的事」，是子项目的就提醒制片人切到对应 chat，不在主干默默施工。**

  - **看板分析升级**（`寄存条_看板升级已外迁.md`）：关键词——看板升级 / 双引擎象限图 / 题材热度 / AI 打标 / Prompt 1·2·3 / ground-truth / episodes 加字段 / 23 期回填 / 能力地图 / 置信度三档 / 本期诊断小结。
  - **Doco 文稿整理**（`寄存条_doco子项目已外迁.md`）：关键词——doco / 文稿整理 / 三方融合 / 视频双路拆分 / A·B 稿 / ASR / 讯飞 / DeepSeek Vision / 终版文稿 / 差异报告 / 段落对齐。**⚡ 2026-06-26 已交付：22 期融合A稿成品在 `doco/deliverables/`（按播出顺序命名），缺第01期（无A稿）。下一步：批量导入知识库（走 Phase 3 上传/embedding 链路）。**

  **主干仍管**：Phase 0–3 主干代码、全部 backend schema/API/迁移、全部前端 React 实施、主干 bug/性能/新需求、Cline 的全部 Plan+Act。

  **接收子项目交付物的纪律**：只接稳定版（草稿不实施）→ 跑迁移前先 `pg_dump` 备份 → 实施完回访子项目登记状态。Schema 变更走「Cline Plan + Opus 审 + 制片人批准 Act」。

  **跨子项目通用规则**见 `跨子项目协作规则.md`（现有规则 1：PRD 版本管理——主项目只留最新版 PRD+回复，翻新先删再传）。`docs/api_credentials_inventory.md` 登记各子模块外部 API 元信息（不存真 key）。

  ---

  ## 1. 项目概览（稳定）

  - **项目名**：TPS 工作台（Topic Planning System）— 央视《军事科技》栏目 8 人团队（制片人/责编/6 编导）内部工作台。
  - **目标**：把散在 Excel/Word/微信/个人电脑里的工作流收拢成一个系统——仪表盘（收视+排期）、知识库（往期文稿/军报/检索）、对话式选题策划+报题单生成、编导个人首页+热点雷达。
  - **设计哲学红线（贯穿所有功能/Prompt/UI）**：**辅助而不替代，AI 给方向不给答案，保护编导创作主权。** 任何让 AI 替编导拍板、或把编导逼向「按 AI 建议改」的设计，不做或重做。AI 输出永远是草稿，制片人审核后才发布，**绝不自动发布**；未审核内容对编导显示「待审核」，绝不展示 AI 草稿值。
  - **范围边界（1.0 不做，别自由发挥）**：TypeScript、Alembic、async SQLAlchemy、AI 模型配置 UI、文稿写作辅助系统、Karpathy LLM Wiki 形态（仅预埋接口）、移动端、多栏目复用。

  ---

  ## 2. 技术栈与运行方式（稳定，红线，禁止擅改）

  - **前端**：React 18 + Vite + Ant Design 5（中文 locale）+ Zustand + React Router v6，**JavaScript（不用 TS）**。
  - **后端**：FastAPI + **SQLModel（同步，不用 async）**；**手写 SQL `backend/sql/00X_*.sql`（不用 Alembic）**。
  - **库**：PostgreSQL 16 + **pgvector**；向量**统一 1536 维（不可改）**。
  - **认证**：**Session + Cookie（不用 JWT）**；CORS 必须 `allow_credentials=True` + 显式列 `allow_origins`（不能 `["*"]`）。
  - **其他锁定**：Word 用 docxtpl；甘特图用 frappe-gantt；定时任务 APScheduler。任何「换成 XX 更好」先在 Plan 讨论，绝不直接改。
  - **关键目录**：`backend/app/{api,core,services,models,db}`、`backend/sql/`、`frontend/src/{pages,components,services,stores}`、`logs/`、`docs/`。
  - **远程仓库**：`http://101.42.29.217:3000/simonkoson/tps-dashboard.git`（腾讯云 Gitea，用户 simonkoson）。**双机开发**：单位 4090D + 家里电脑，开工先 `git pull`，收工必 `git push`，详见 `docs/git_workflow.md` 第 7 章。
  - **本地启动**（开发模式，两个 PowerShell 窗口都别关；仓库根 `E:\tps-dashboard`）：
    - 后端：`cd backend` → 激活虚拟环境 → `uvicorn app.main:app --reload --port 8000`（文档 `/docs`）
    - 前端：`cd frontend` → `npm run dev`（端口 5173 或 5174）
  - **环境变量/密钥**：放 `backend/.env`，**永不进 git、永不写进本文件**。需要：数据库连接、SECRET_KEY、MiniMax API Key + GroupId。
  - **依赖锁版本**（勿乱升）：`bcrypt==4.0.1`（新版与 passlib 不兼容）、`itsdangerous==2.2.0`、`python-multipart==0.0.9`；`starlette` 不单独装。

  ---

  ## 3. 当前进度（动态，核心交接区 — 以最新快照为准）

  - **已完成至**：Phase 3 / Task 3（知识库树形视图·按来源两层分组，路线 B），含 Task 3.1、3.2，验收通过，最终 commit `3409d48`。
  - **正在做**：无。主干暂停，资源投入外迁子项目。
  - **卡点/待解**：下一刀方向未定（见「待办」）；其中 PDF 大文件存储架构需先与 Opus 讨论定方案再立项。
  - **Schema 状态**：知识库两表 schema 已就绪，**Phase 3 不再改表**。

  ---

  ## 4. 已完成（只追加，最新在上）

  - [2026-05-27] Phase 3 Task 3/3.1/3.2：知识库树形视图（按来源大类→二级维度分组、左右布局、节点联动、展开收起；修出处筛选/宽度跳动/排版）。commit `3409d48`。
  - [2026-05-27] Phase 3 Task 2：知识库管理后台最小版（上传/列表/删除）。
  - [2026-05-27] Phase 3 Task 1：embedding 链路（入库即调 MiniMax embo-01 算 1536 维向量存 pgvector）。
  - [—] Phase 2：仪表盘 + 批量导入 + 写权限收紧（yearly_targets 写权限）。
  - [—] Phase 1：后端骨架（认证三件套）+ 前端骨架（登录/主布局/路由守卫）。
  - [—] Phase 0：环境 + Git。

  ---

  ## 5. 待办（下一刀候选，开局前定先做哪件）

  - [ ] **下一刀三选一**：① 语义搜索界面（不依赖任何材料，随时能开，是 Phase 4a 硬门槛）；② PDF 原文关联 + 大文件存储架构（需 Opus 审方案，优先级较高）；③ 导入真实收视 Excel + 清测试数据（Phase 4a 另一前置）。
  - [ ] PDF 大文件存储：**大文件不入库，单独文件仓库，DB 只存地址指针**（md 正文+向量留库参与检索；pdf 仅按需调阅）。地基一次定对，避免上云返工。
  - [ ] 200+ Obsidian md 批量录入（**建议在 PDF 存储方案定后做**；先试 10 篇验证解析/落位再全量，每篇都真调 MiniMax 耗额度）。
  - [ ] 「按编导看稿」独立筛选视图（路线 A 重构时一并处理，从来源树里迁出来）。
  - [ ] 操作留痕 schema（episodes 等加 created_by/updated_by/updated_at；涉 schema 须 Opus 审）。
  - [ ] 界面像素级打磨（连同全栏目视觉规范统一弄，参考「色调字体倒角」图）。

  ---

  ## 6. 关键决策（跨 session 最易丢，先看这节再动手）

  ### 栏目业务红线（AI 凭通用习惯 100% 写反，死守）

  - **收视颜色反直觉**：只对 `audience_share` 上色（`audience_rating` 只显示不判定）。🔴红=份额**>**当年摸高目标=**优秀**；🔵蓝=基础≤份额≤摸高=达标；🟢绿=份额**<**基础=**待提升**。（与通用红警绿安相反）
  - **yearly_targets 只增不改**：按节目**播出年份**的目标判色（非当前年）；`year` 加 UNIQUE，INSERT 用 `ON CONFLICT DO NOTHING`，**永不 ON CONFLICT UPDATE**。
  - **编导关联用软引用+快照双字段**：`editor_id` + `editor_name_snapshot`。离职编导 `editor_id` 留 NULL、保留快照；查历史作品先按 id、回退按 name 文本匹配。**禁止外键非空 + 级联删**（否则离职者历史节目全成无主）。
  - **报题单内容概要双段结构**：默认 引子（200–300 字）+ 列举（3–5 条，每条以 `**加粗关键词**` 起头）；纯叙述式仅编导明确指定时用。Prompt 与 docxtpl 模板同此。
  - **角色枚举是拼音**：`zhipianren` / `zebian` / `biandao`，不增枚举、不换英文。yearly_targets：POST/PATCH 限 zhipianren+zebian（biandao 403），DELETE 仅 zhipianren，GET 三角色均可。

  ### 架构决策

  - 知识库树**交互层 vs 数据分组层必须解耦**：分组逻辑在 `useKnowledgeGrouping.js` + 后端 `get_grouped_items()`；树组件只管展开/高亮/联动，不感知按什么字段分组。
  - 二级分组维度做成**可配置映射表** `SECONDARY_GROUP_FIELD`（manuscript→author，military_report→source_detail，其余 None），前后端同名对齐。将来转主题树（路线 A）只改这一处映射，原料已在库（tags/related_entities JSONB），大概率无需补字段重传。
  - 向量 1536 维、Session 认证、不用 Alembic/TS/async —— 见技术栈节，宪法锁定。
  - embedding 用 **MiniMax embo-01**：请求用 `texts` 数组 + `type`（db/query），返回在 `vectors` 字段，需 API Key + GroupId；花 MiniMax 账号额度（与 Claude token 两笔账，一篇几厘钱）。
  - **PDF 等大文件不入数据库**，单独文件仓库 + DB 存指针（详见待办，待立项）。

  ---

  ## 7. ⏩ 交接备注（换人/换账号 0 摩擦续上）

  - **下一刀未定**，开工第一件事：与制片人确认三选一（语义搜索 / PDF 存储 / 真实收视导入）。PDF 存储须先和 Opus 讨论方案才立项。
  - **schema 红线**：Phase 3 不改知识库两表；`topics` / `topic_embeddings` 属 Phase 4a，**勿碰**；五类 `source_type` 枚举固定不增减，细分杂志/军报=改表=须 Opus 审。
  - **`logs/` 是受保护资产**：Act 模式严禁 Cline 改；phase 日志由顾问协助生成。Task 3 三轮内容待并入 `phase3_log`（Task 3 段）。
  - **避雷（Phase 3 实战教训）**：
    1. **不信 Cline 自检**——它多次虚标 ✅，一律由制片人真实点页面逐条验。
    2. 改树节点 **key 格式属高风险**，生成端与过滤端必须同步，改后必实测点击联动。
    3. **已验证好用的布局别为对齐整体重构**（flex 改 Grid 连坏两轮）；样式微调优先。
    4. Cline 报告自相矛盾时，**把源码发给 Opus 一眼定位**胜过让 Cline 反复试错。
    5. 像素级打磨边际收益递减，**见好就收**，记 backlog 改天连视觉规范统一弄。

  ---

  ## 8. 受保护资产 / 改前必经制片人确认

  **严禁 Act 自动修改/删除**：`.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`、`docs/**`、`logs/**`、`samples/*.xlsx`、`.git/`、`.env`。如需改，切 Plan 经制片人确认。

  ---

  ## 9. 待确认 / 开放问题（需制片人拍板，AI 别自行假设）

  - [ ] 下一刀选谁（三选一）。
  - [ ] PDF 文件存哪、笔记如何关联中台内文件位置（Backlog #2 的前提）。
  - [ ] 视觉风格参考图、6 名编导初始画像（各 200 字）、甘特图样本 —— 后续 Phase 需要。
-											看板升级: GT v0.5.0(20期叙事结构全覆盖) + schema加字段方案 + git清理
										
										
											2026-06-26 09:14:29 +08:00
+								- # 项目协作主控文件 (CLAUDE.md)
 								  <!--
 								    Claude Code 每次开 session 自动读取。两个角色：
 ) 项目说明书（稳定：是什么、用什么、怎么跑、什么不能碰）
 ) 跨工具活快照交接区（动态：现在到哪、下一步、刚定的决定）
 								    维护原则：增量更新，改对应小节，不整篇重写、不删历史。
 								    本文件与项目宪法（.clinerules / project_plan.md / dev_plan.md / docs/git_workflow.md）并列，
 								    不复制宪法内容，只指向 + 抽取仍生效的关键决策。新对话接手时连同宪法一并阅读。
 								  -->
 								  ---
 								  ## 🔖 状态栏（每次结束 session 前必须更新这三行）
-											docs: 仓库迁移腾讯云Gitea + 双机开发流程文档更新
										
										
											2026-07-03 09:11:56 +08:00
+								  - **最后更新**：Claude（顾问）｜ 2026-07-03
 								  - **当前状态一句话**：远程仓库已迁至腾讯云 Gitea（101.42.29.217:3000），双机开发就绪；git 历史已清理大文件（769MB→5MB）。Phase 3 知识库已完成，主干暂停。
-											看板升级: GT v0.5.0(20期叙事结构全覆盖) + schema加字段方案 + git清理
										
										
											2026-06-26 09:14:29 +08:00
+								  - **下一个动手的人从这里开始**：见下方「⏩ 交接备注」
 								  ---
 								  ## 🤖 给 AI 的工作约定（READ FIRST）
 								  - 开工前先读完：本文件「状态栏 / 交接备注 / 关键决策」三节 + 四份宪法 + 两份外迁寄存条（`寄存条_看板升级已外迁.md`、`寄存条_doco子项目已外迁.md`）。
 								  - **角色定位**：Claude Code 默认是**顾问**——出方案、审 Plan、卡壳兜底、写交接文档。**写代码（Plan + Act）交给 Cline，不要架空 Cline**。顾问位是为**省 token**：日常 CRUD、常规实现不该 Claude Code 亲自写。**仅两种情况下场动手**：① Cline 连续几次改都过不去的坎；② 制片人明确点名让 Claude Code 操刀。
 								  - 给 Cline 的指令一律用**代码块**封装，方便复制；不要让制片人手动粘贴整份文件内容。
 								  - 完成一段工作 → **增量更新**：在「已完成」追加一条、「待办」勾掉/新增、必要时补「关键决策」，最后改「状态栏」三行。只追加/勾选，不重写、不删历史。
 								  - 涉及**发送、发布、删除、改权限、付款、跑 schema 迁移**等不可逆操作前，先在对话里跟制片人确认。
 								  - Git 红线：`git reset --hard` / `push --force` / `rebase` / 删分支删 tag —— **必须停下问制片人**，永不自动执行；删整个 `.git` 永远禁止。
 								  - **沟通**：全程简体中文；制片人不懂代码，解释说人话、最小化技术语言；给明确推荐而非反复抛选项；复杂决策配可视化产物（HTML 原型 / 气泡图）辅助。回复简明，不堆中间过程。
 								  ---
 								  ## 🧩 子项目关系 / 话题边界（外迁禁区）
 								  主干保持稳定，复杂功能拆成独立子项目（独立 chat / 独立 PRD）。**以下话题已外迁，主项目里聊到要先反问「这是子项目的事还是主干的事」，是子项目的就提醒制片人切到对应 chat，不在主干默默施工。**
 								  - **看板分析升级**（`寄存条_看板升级已外迁.md`）：关键词——看板升级 / 双引擎象限图 / 题材热度 / AI 打标 / Prompt 1·2·3 / ground-truth / episodes 加字段 / 23 期回填 / 能力地图 / 置信度三档 / 本期诊断小结。
-											doco收尾: 22期融合A稿成品归拢 + ep021/022补稿 + cli路径修复
										
										
											2026-06-26 17:55:09 +08:00
+								  - **Doco 文稿整理**（`寄存条_doco子项目已外迁.md`）：关键词——doco / 文稿整理 / 三方融合 / 视频双路拆分 / A·B 稿 / ASR / 讯飞 / DeepSeek Vision / 终版文稿 / 差异报告 / 段落对齐。**⚡ 2026-06-26 已交付：22 期融合A稿成品在 `doco/deliverables/`（按播出顺序命名），缺第01期（无A稿）。下一步：批量导入知识库（走 Phase 3 上传/embedding 链路）。**
-											看板升级: GT v0.5.0(20期叙事结构全覆盖) + schema加字段方案 + git清理
										
										
											2026-06-26 09:14:29 +08:00
 								  **主干仍管**：Phase 0–3 主干代码、全部 backend schema/API/迁移、全部前端 React 实施、主干 bug/性能/新需求、Cline 的全部 Plan+Act。
 								  **接收子项目交付物的纪律**：只接稳定版（草稿不实施）→ 跑迁移前先 `pg_dump` 备份 → 实施完回访子项目登记状态。Schema 变更走「Cline Plan + Opus 审 + 制片人批准 Act」。
 								  **跨子项目通用规则**见 `跨子项目协作规则.md`（现有规则 1：PRD 版本管理——主项目只留最新版 PRD+回复，翻新先删再传）。`docs/api_credentials_inventory.md` 登记各子模块外部 API 元信息（不存真 key）。
 								  ---
 								  ## 1. 项目概览（稳定）
 								  - **项目名**：TPS 工作台（Topic Planning System）— 央视《军事科技》栏目 8 人团队（制片人/责编/6 编导）内部工作台。
 								  - **目标**：把散在 Excel/Word/微信/个人电脑里的工作流收拢成一个系统——仪表盘（收视+排期）、知识库（往期文稿/军报/检索）、对话式选题策划+报题单生成、编导个人首页+热点雷达。
 								  - **设计哲学红线（贯穿所有功能/Prompt/UI）**：**辅助而不替代，AI 给方向不给答案，保护编导创作主权。** 任何让 AI 替编导拍板、或把编导逼向「按 AI 建议改」的设计，不做或重做。AI 输出永远是草稿，制片人审核后才发布，**绝不自动发布**；未审核内容对编导显示「待审核」，绝不展示 AI 草稿值。
 								  - **范围边界（1.0 不做，别自由发挥）**：TypeScript、Alembic、async SQLAlchemy、AI 模型配置 UI、文稿写作辅助系统、Karpathy LLM Wiki 形态（仅预埋接口）、移动端、多栏目复用。
 								  ---
 								  ## 2. 技术栈与运行方式（稳定，红线，禁止擅改）
 								  - **前端**：React 18 + Vite + Ant Design 5（中文 locale）+ Zustand + React Router v6，**JavaScript（不用 TS）**。
 								  - **后端**：FastAPI + **SQLModel（同步，不用 async）**；**手写 SQL `backend/sql/00X_*.sql`（不用 Alembic）**。
 								  - **库**：PostgreSQL 16 + **pgvector**；向量**统一 1536 维（不可改）**。
 								  - **认证**：**Session + Cookie（不用 JWT）**；CORS 必须 `allow_credentials=True` + 显式列 `allow_origins`（不能 `["*"]`）。
 								  - **其他锁定**：Word 用 docxtpl；甘特图用 frappe-gantt；定时任务 APScheduler。任何「换成 XX 更好」先在 Plan 讨论，绝不直接改。
 								  - **关键目录**：`backend/app/{api,core,services,models,db}`、`backend/sql/`、`frontend/src/{pages,components,services,stores}`、`logs/`、`docs/`。
-											docs: 云端Gitea用户名 lanhao → simonkoson，更新全部文档引用
										
										
											2026-07-03 09:16:48 +08:00
+								  - **远程仓库**：`http://101.42.29.217:3000/simonkoson/tps-dashboard.git`（腾讯云 Gitea，用户 simonkoson）。**双机开发**：单位 4090D + 家里电脑，开工先 `git pull`，收工必 `git push`，详见 `docs/git_workflow.md` 第 7 章。
-											看板升级: GT v0.5.0(20期叙事结构全覆盖) + schema加字段方案 + git清理
										
										
											2026-06-26 09:14:29 +08:00
+								  - **本地启动**（开发模式，两个 PowerShell 窗口都别关；仓库根 `E:\tps-dashboard`）：
 								    - 后端：`cd backend` → 激活虚拟环境 → `uvicorn app.main:app --reload --port 8000`（文档 `/docs`）
 								    - 前端：`cd frontend` → `npm run dev`（端口 5173 或 5174）
 								  - **环境变量/密钥**：放 `backend/.env`，**永不进 git、永不写进本文件**。需要：数据库连接、SECRET_KEY、MiniMax API Key + GroupId。
 								  - **依赖锁版本**（勿乱升）：`bcrypt==4.0.1`（新版与 passlib 不兼容）、`itsdangerous==2.2.0`、`python-multipart==0.0.9`；`starlette` 不单独装。
 								  ---
 								  ## 3. 当前进度（动态，核心交接区 — 以最新快照为准）
 								  - **已完成至**：Phase 3 / Task 3（知识库树形视图·按来源两层分组，路线 B），含 Task 3.1、3.2，验收通过，最终 commit `3409d48`。
 								  - **正在做**：无。主干暂停，资源投入外迁子项目。
 								  - **卡点/待解**：下一刀方向未定（见「待办」）；其中 PDF 大文件存储架构需先与 Opus 讨论定方案再立项。
 								  - **Schema 状态**：知识库两表 schema 已就绪，**Phase 3 不再改表**。
 								  ---
 								  ## 4. 已完成（只追加，最新在上）
 								  - [2026-05-27] Phase 3 Task 3/3.1/3.2：知识库树形视图（按来源大类→二级维度分组、左右布局、节点联动、展开收起；修出处筛选/宽度跳动/排版）。commit `3409d48`。
 								  - [2026-05-27] Phase 3 Task 2：知识库管理后台最小版（上传/列表/删除）。
 								  - [2026-05-27] Phase 3 Task 1：embedding 链路（入库即调 MiniMax embo-01 算 1536 维向量存 pgvector）。
 								  - [—] Phase 2：仪表盘 + 批量导入 + 写权限收紧（yearly_targets 写权限）。
 								  - [—] Phase 1：后端骨架（认证三件套）+ 前端骨架（登录/主布局/路由守卫）。
 								  - [—] Phase 0：环境 + Git。
 								  ---
 								  ## 5. 待办（下一刀候选，开局前定先做哪件）
 								  - [ ] **下一刀三选一**：① 语义搜索界面（不依赖任何材料，随时能开，是 Phase 4a 硬门槛）；② PDF 原文关联 + 大文件存储架构（需 Opus 审方案，优先级较高）；③ 导入真实收视 Excel + 清测试数据（Phase 4a 另一前置）。
 								  - [ ] PDF 大文件存储：**大文件不入库，单独文件仓库，DB 只存地址指针**（md 正文+向量留库参与检索；pdf 仅按需调阅）。地基一次定对，避免上云返工。
 								  - [ ] 200+ Obsidian md 批量录入（**建议在 PDF 存储方案定后做**；先试 10 篇验证解析/落位再全量，每篇都真调 MiniMax 耗额度）。
 								  - [ ] 「按编导看稿」独立筛选视图（路线 A 重构时一并处理，从来源树里迁出来）。
 								  - [ ] 操作留痕 schema（episodes 等加 created_by/updated_by/updated_at；涉 schema 须 Opus 审）。
 								  - [ ] 界面像素级打磨（连同全栏目视觉规范统一弄，参考「色调字体倒角」图）。
 								  ---
 								  ## 6. 关键决策（跨 session 最易丢，先看这节再动手）
 								  ### 栏目业务红线（AI 凭通用习惯 100% 写反，死守）
 								  - **收视颜色反直觉**：只对 `audience_share` 上色（`audience_rating` 只显示不判定）。🔴红=份额**>**当年摸高目标=**优秀**；🔵蓝=基础≤份额≤摸高=达标；🟢绿=份额**<**基础=**待提升**。（与通用红警绿安相反）
 								  - **yearly_targets 只增不改**：按节目**播出年份**的目标判色（非当前年）；`year` 加 UNIQUE，INSERT 用 `ON CONFLICT DO NOTHING`，**永不 ON CONFLICT UPDATE**。
 								  - **编导关联用软引用+快照双字段**：`editor_id` + `editor_name_snapshot`。离职编导 `editor_id` 留 NULL、保留快照；查历史作品先按 id、回退按 name 文本匹配。**禁止外键非空 + 级联删**（否则离职者历史节目全成无主）。
 								  - **报题单内容概要双段结构**：默认 引子（200–300 字）+ 列举（3–5 条，每条以 `**加粗关键词**` 起头）；纯叙述式仅编导明确指定时用。Prompt 与 docxtpl 模板同此。
 								  - **角色枚举是拼音**：`zhipianren` / `zebian` / `biandao`，不增枚举、不换英文。yearly_targets：POST/PATCH 限 zhipianren+zebian（biandao 403），DELETE 仅 zhipianren，GET 三角色均可。
 								  ### 架构决策
 								  - 知识库树**交互层 vs 数据分组层必须解耦**：分组逻辑在 `useKnowledgeGrouping.js` + 后端 `get_grouped_items()`；树组件只管展开/高亮/联动，不感知按什么字段分组。
 								  - 二级分组维度做成**可配置映射表** `SECONDARY_GROUP_FIELD`（manuscript→author，military_report→source_detail，其余 None），前后端同名对齐。将来转主题树（路线 A）只改这一处映射，原料已在库（tags/related_entities JSONB），大概率无需补字段重传。
 								  - 向量 1536 维、Session 认证、不用 Alembic/TS/async —— 见技术栈节，宪法锁定。
 								  - embedding 用 **MiniMax embo-01**：请求用 `texts` 数组 + `type`（db/query），返回在 `vectors` 字段，需 API Key + GroupId；花 MiniMax 账号额度（与 Claude token 两笔账，一篇几厘钱）。
 								  - **PDF 等大文件不入数据库**，单独文件仓库 + DB 存指针（详见待办，待立项）。
 								  ---
 								  ## 7. ⏩ 交接备注（换人/换账号 0 摩擦续上）
 								  - **下一刀未定**，开工第一件事：与制片人确认三选一（语义搜索 / PDF 存储 / 真实收视导入）。PDF 存储须先和 Opus 讨论方案才立项。
 								  - **schema 红线**：Phase 3 不改知识库两表；`topics` / `topic_embeddings` 属 Phase 4a，**勿碰**；五类 `source_type` 枚举固定不增减，细分杂志/军报=改表=须 Opus 审。
 								  - **`logs/` 是受保护资产**：Act 模式严禁 Cline 改；phase 日志由顾问协助生成。Task 3 三轮内容待并入 `phase3_log`（Task 3 段）。
 								  - **避雷（Phase 3 实战教训）**：
 . **不信 Cline 自检**——它多次虚标 ✅，一律由制片人真实点页面逐条验。
 . 改树节点 **key 格式属高风险**，生成端与过滤端必须同步，改后必实测点击联动。
 . **已验证好用的布局别为对齐整体重构**（flex 改 Grid 连坏两轮）；样式微调优先。
 . Cline 报告自相矛盾时，**把源码发给 Opus 一眼定位**胜过让 Cline 反复试错。
 . 像素级打磨边际收益递减，**见好就收**，记 backlog 改天连视觉规范统一弄。
 								  ---
 								  ## 8. 受保护资产 / 改前必经制片人确认
 								  **严禁 Act 自动修改/删除**：`.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`、`docs/**`、`logs/**`、`samples/*.xlsx`、`.git/`、`.env`。如需改，切 Plan 经制片人确认。
 								  ---
 								  ## 9. 待确认 / 开放问题（需制片人拍板，AI 别自行假设）
 								  - [ ] 下一刀选谁（三选一）。
 								  - [ ] PDF 文件存哪、笔记如何关联中台内文件位置（Backlog #2 的前提）。
 								  - [ ] 视觉风格参考图、6 名编导初始画像（各 200 字）、甘特图样本 —— 后续 Phase 需要。