fix: 完成 doco src layout 重构,文件移至 src/doco/ 子目录

2026-06-12 17:13:32 +08:00
parent 0508bd8f23
commit 89d59f6f03
29 changed files with 3676 additions and 0 deletions
@@ -0,0 +1,65 @@
+# 寄存条:看板升级已外迁
+
+> 留在主 project,让未来的 Claude 一眼知道:看板分析升级已经拉出去单独立项了。
+> 外迁时间:2026-06-12
+
+---
+
+## 外迁了什么
+
+**TPS 看板分析升级**整体作为子项目,搬到独立 Claude project。
+
+子项目聚焦:三层信息架构、双引擎象限图、AI 打标流水线、编导能力地图、本期诊断小结、看板 UI 设计。
+
+子项目持有的核心资产:主项目签发的 Brief + 三份续接快照 + ground-truth 基准集 + 23 期文稿等。
+
+---
+
+## 主 project 不再讨论的话题
+
+聊到下面这些词,**先问一句"这是子项目的事还是主 project 的事?"**——是子项目的事,提醒制片人切到子项目 chat。
+
+关键词:看板升级 / 双引擎象限图 / 题材热度 / 叙事结构(作为字段)/ AI 打标 / Prompt 1/2/3 / ground-truth / episodes 加字段 / 23 期回填 / 能力地图 / 置信度三档 / 本期诊断小结
+
+---
+
+## 主 project 仍在管什么
+
+- Phase 0-3 已落地的主干代码(episodes、editors、收视诊断基础)
+- backend 全部 schema、API、迁移脚本
+- 前端全部 React 代码实施
+- 主干 Bug、性能优化、新需求(看板升级以外的)
+- Cline 的全部 Plan + Act 操作
+
+---
+
+## 接收子项目交付物的接口
+
+子项目交付物的具体接口约定,见**子项目主 Brief §六**(交付什么)。简要回顾:
+
+- **Schema 变更**:子项目出字段定义文档 → 主 project Cline 切 Plan + Opus 审 + 制片人批准 Act → `pg_dump` 备份 → 跑迁移
+- **前端实施**:子项目出设计 token + HTML mock + 视觉规范 → 主 project Cline 落 React
+- **AI 打标**:沙盒 `ai-labeling/` 由子项目自治,主 project 不碰
+- **回填**:子项目出脚本设计 → 主 project 跑 + 制片人审 staging
+
+**纪律**:
+- 只接稳定版,草稿不实施
+- 实施前 `pg_dump` 备份
+- 实施完成后回访子项目登记状态
+
+---
+
+## 开局口径
+
+进主 project 新 chat:
+> "续接 TPS 主项目。读 `寄存条_看板升级已外迁.md`。当前要做 [具体任务]。"
+
+---
+
+## 万一子项目记录丢了
+
+降级方案:
+1. 主 project 这边还保留资产副本(xlsx + 11 份 docx + 部分 UI 参考图)
+2. 决策史在 Gitea 有 git 历史(关键 commit `38f3728` 等)
+3. 制片人本地应有副本
+4. **主 project 这边不要凭记忆重建子项目内容**——找制片人或重建子项目
@@ -0,0 +1,50 @@
+# 看板升级子项目 — 入口
+
+> 这是 TPS 主 project 拆出来的子项目,聚焦"看板分析升级"。
+> 立项时间:2026-06-12
+> 顾问:Claude Opus 4.7 ｜ 制片人:刘通
+
+---
+
+## 开局必读(顺序)
+
+1. `看板升级子项目_Brief.md` — 主项目签发的"交接宪法"(红线、技术栈、出入口接口)。**不在子项目内修改。**
+2. `续接快照_看板分析升级_设计讨论_v4.md` — 最新决策史(往前可回溯 v3 / v1)
+3. 上面两份读完,就有完整上下文了
+
+---
+
+## 已有资产
+
+**决策史**:
+- 续接快照 v1 / v3 / v4 — 整个看板升级讨论的完整记录
+
+**数据基础**:
+- `军事科技栏目收视诊断分析_v2.xlsx` — 双引擎模型源数据(主项目也留一份)
+- 11 份节目文稿 `.docx` — AI 打标基准集源稿(主项目也留一份)
+
+**UI 参考**:
+- `dashiboard首页原版.jpg` — 首屏改造起点(主项目也留一份)
+- `dashiboard首页_拷贝.jpg` — 制片人批注稿
+- `色调字体倒角.webp` — 整体视觉资产(主项目也留一份)
+- `简洁风_清晰.jpg` — DataEase 风格参考
+
+**协作纪律**:
+- `Claude协作原则.md` — 与主项目同源,沿用
+
+**沙盒**:
+- `ai-labeling/` 工作区(物理上仍在 `E:\tps-dashboard\ai-labeling\`)
+- Prompt 2 v0.2 已锁,MiniMax M3 选定,ground-truth v0.2.1 锁定
+
+---
+
+## 子项目自由度
+
+读完 Brief 你会注意到 §八"未决项"——那是子项目可自由发挥的部分。
+Brief 里没明确禁止、没在续接快照里拍板的事,都是讨论空间。
+
+---
+
+## 新 chat 开局第一句
+
+> "续接 TPS 看板分析升级子项目。先读主 Brief 和续接快照 v4。本 project 是设计+PRD 产出,不动主 project 的 backend 代码。当前推进到 [具体任务]。"
@@ -0,0 +1,143 @@
+# 看板升级子项目 Brief
+
+> 主项目 → 子项目的"交接宪法":红线、技术栈、出入口接口
+> 起草日期:2026-06-12
+> 状态:子项目立项时由主项目顾问(Opus)签发,子项目内部不修改
+
+---
+
+## 一、为什么做
+
+**痛点**:制片人和编导团队拿到的"收视成绩单"只能看到结果(均值、走势、单期高低),
+看不到结构性原因。每次复盘要靠人工拼诊断(21 期那次花了若干周),无法持续。
+
+**升级目标**:把仪表盘从"看成绩"升级为"能分析"——
+让"双引擎模型(题材热度 × 叙事结构)"这个一次性人工产出的分析框架,
+变成一台**持续运转的诊断仪**。
+
+---
+
+## 二、做什么(功能边界,只列名)
+
+| 模块 | 简述 |
+|---|---|
+| 三层信息架构 | 纯算 / 打标后 / AI 起草,分层呈现 |
+| 双引擎象限图 | 招牌视觉,题材热度 × 叙事结构 |
+| AI 打标流水线 | Prompt 1/2/3 + MiniMax M3 + ground-truth |
+| 编导能力地图 | 反排名,正反馈 |
+| 本期诊断小结 | AI 起草 + 制片人审改后发布 |
+| 时间选择器 | 实时脉搏 vs 周期复盘,边界永远可调 |
+
+**具体怎么做,子项目内部讨论,本 Brief 不预设方案。**
+
+---
+
+## 三、怎么用(目标流程)
+
+- **每周**:制片人看"实时脉搏"——核心指标卡 + 近 9 期走势
+- **每月**:制片人看"题材分析"——题材汇总,关注异动
+- **每季**:制片人看"双引擎象限图 + 本期诊断小结"——周期复盘
+- **新节目入库**:AI 打标草稿 → staging 表 → 制片人审 → 落库
+- **编导维度**:制片人查能力地图,把强项做成全组可复用模板
+- **离职编导**:历史保留,面向当下视图可筛掉
+
+---
+
+## 四、不做什么(红线)
+
+子项目设计任何方案,**绝不**触碰以下:
+
+- ❌ **不做深色大屏**(留给 2.0 数据大屏蓝本)
+- ❌ **不做编导排名**(团队视角走能力地图)
+- ❌ **AI 不自动盖章下结论**(永远是"AI 出草稿,人拍板")
+- ❌ **不引入新图表库**(继续 ECharts / @ant-design/charts)
+- ❌ **不引入主 project 没有的技术栈**
+- ❌ **不动主 project 已有的 schema**(改字段必须走 §六交付协议)
+- ❌ **不做"未审字段直接上看板"**(置信度三档必须可辨)
+- ❌ **不写 / 不改 AI 打标 Prompt 由 Cline 完成**(Cline 是执行者不是作者)
+
+---
+
+## 五、技术栈约束(继承主 project)
+
+子项目所有设计必须能落在以下栈上,不引入新依赖:
+
+- **前端**:React 18 + Vite + AntD 5 + Zustand + ECharts / @ant-design/charts
+- **后端**:FastAPI + SQLModel + PG 16 + pgvector
+- **配色**:米色底 `#fbf9f1` + 深绿主色 `#6b8e6b`
+- **三色色板**:红 `#c0584f` / 蓝 `#5b8db8` / 绿 `#7aa874`
+- **基准线**:基础线 0.6448 / 摸高线 0.8989(2026)
+- **AI 打标**:沙盒 `ai-labeling/`,生产模型 MiniMax M3,openai==1.55.0 锁版本
+- **部署**:腾讯云 4 核 8G(性能上限,凡是吃不动的方案直接否决)
+
+---
+
+## 六、交付什么(出口接口)
+
+子项目产出最终要回到主 project 实施,**交付物必须满足以下接口**:
+
+### 6.1 Schema 变更类
+- 子项目出:**字段定义文档**(命名 / 类型 / 枚举 / nullable / 约束 / 回滚方案)
+- 主 project 实施:**Cline 切 Plan → Opus 审 → 制片人批准 Act → `pg_dump` 备份 → 跑迁移**
+- 不接受:子项目自己改主 project schema 或 `backend/` 任何代码
+
+### 6.2 前端实施类
+- 子项目出:**设计 token JSON + HTML mock + 视觉规范文档**
+- 主 project 实施:**Cline 按设计稿落 React 组件**
+- 不接受:子项目自己写主 project 的 React 代码
+
+### 6.3 AI 打标类
+- 子项目在 `ai-labeling/` 沙盒自治,**沙盒内 Cline 可直接 Act**
+- 子项目出:**Prompt 文件 + ground-truth.json + 模型选型结论**
+- 主 project 实施:**episodes_staging 表 schema 落库 + 审稿 UI 落地**
+
+### 6.4 回填类
+- 子项目出:**回填脚本设计文档 + 23 期回填策略**
+- 主 project 实施:**Cline 跑脚本 + 制片人审 staging**
+
+### 6.5 通用约束
+- 子项目**不主动 push** 文件到主 project,**所有交付物由制片人决定时机**
+- 主 project 只接**稳定版**,子项目内部草稿不交付
+
+---
+
+## 七、入口接口(子项目要知道的主 project 现状)
+
+- **Phase 0-3 已落地**:episodes / editors / 收视诊断基础数据,23 期 2026 年数据已入库
+- **现有视觉语言**:米色 + 深绿,卡片圆角 12px,AntD 5 默认行高
+- **现有 backlog**:主 project 这边的 backlog 已标注"看板升级条目已外迁"
+- **现有沙盒**:`ai-labeling/` 工作区已搭建,Prompt 2 v0.2 已锁,MiniMax M3 已选定
+- **现有 git**:Gitea 落库,关键 commit `38f3728`
+
+---
+
+## 八、未决项(归子项目自己拍板)
+
+以下不在本 Brief 内预设,**由子项目和制片人讨论决定**:
+
+- 横轴量化方法的具体公式
+- AI 打标 Prompt 1 / Prompt 3 的具体写法
+- 看板各屏幕的具体布局和交互
+- 双引擎象限图的具体视觉细节
+- 能力地图的具体可视化方案
+- episodes 新字段的最终命名 / 类型 / 是否多对多关联表
+- 置信度是单字段还是分字段
+- 时间窗口取多大 / 小样本怎么兜底等具体口径
+
+---
+
+## 九、决策史指向(不重复内容)
+
+子项目讨论前应该读的:
+- `续接快照_看板分析升级_设计讨论.md`(v1,2026-06-09)
+- `续接快照_看板分析升级_设计讨论_v3.md`(v3,2026-06-11 上午)
+- `续接快照_看板分析升级_设计讨论_v4.md`(v4,2026-06-11 晚)
+- `军事科技栏目收视诊断分析_v2.xlsx`(双引擎模型源数据)
+
+---
+
+## 十、本 Brief 自身的修订规则
+
+- 本 Brief 不在子项目内修改
+- 红线 / 技术栈如有变更,**主 project 这边发新版**,通过寄存条同步
+- 子项目可在自己的 chat 里讨论"建议主 project 调整某条红线",但调整动作只能在主 project 发生
@@ -0,0 +1,95 @@
+# 迁移清单 — 主 project 操作指南
+
+> 用途:看板升级子项目立项时,主 project 这边的文件操作清单
+> 操作完即可丢弃
+> 制定时间:2026-06-12
+
+---
+
+## 资产分两类处理
+
+### 🔵 子项目独有(主 project 这边删)
+
+纯决策记录性质,主 project 不再需要:
+
+1. `续接快照_看板分析升级_设计讨论.md`(v1)
+2. `续接快照_看板分析升级_设计讨论_v3.md`
+3. `续接快照_看板分析升级_设计讨论_v4.md`
+4. `dashiboard首页_拷贝.jpg`(批注稿)
+5. `简洁风_清晰.jpg`(参考图)
+
+### 🟢 两边都留(各保留一份)
+
+资产类性质,主 project 将来也可能用得到:
+
+1. `军事科技栏目收视诊断分析_v2.xlsx` — 数据基础
+2. 11 份节目文稿 `.docx`(硅基大脑、潜艇仿生 等) — 节目原始资料
+3. `dashiboard首页原版.jpg` — 主 project 实施 React 时要看
+4. `色调字体倒角.webp` — 整体视觉资产
+
+---
+
+## 主 project 这边的其他动作
+
+### 新增
+
+- 上传 `寄存条_看板升级已外迁.md`
+
+### 更新
+
+- `backlog_md_TPS_工作台待办池_不丢视野_非排期_.md` 顶部加一段:
+
+```markdown
+> ⚠️ 更新(2026-06-12):看板分析升级相关待办(原 F1-F8)已整体迁移到
+> **TPS 看板分析升级子项目**。主 project 这边不再维护这部分待办。
+> 子项目状态见 `寄存条_看板升级已外迁.md`。
+```
+
+### 保留(不动)
+
+主干文档(README、Claude协作原则、phase 日志、doco 系列、git_workflow、_clinerules、_gitignore、001_init.sql、dev_plan、project_plan、Phase 3 续接快照系列)全部保留。
+
+---
+
+## 操作步骤
+
+**Step 1 ─ 建子项目**
+1. 新建 Claude project,名为 `TPS看板分析升级`
+2. 上传 4 份新文件:`INDEX.md` + `看板升级子项目_Brief.md` + 拷贝一份 `Claude协作原则.md`
+3. 上传 🔵 5 份子项目独有的文件
+4. 上传 🟢 14 份资产文件(主 project 也保留同名副本)
+
+**Step 2 ─ 清主 project + 寄存**
+5. 删除 🔵 5 份文件
+6. 上传 `寄存条_看板升级已外迁.md`
+7. 更新 `backlog` 顶部标注
+
+**Step 3 ─ 验证**
+8. 进主 project 新 chat:"读寄存条" → 看 Claude 是否懂"这部分外迁了,不在我这里讨论"
+9. 进子项目新 chat:按 INDEX 开局口径 → 看 Claude 是否能正确进入顾问角色
+
+---
+
+## 操作后的拓扑
+
+```
+TPS 主 project                              TPS 看板升级子项目
+─────────────────────                       ─────────────────────
+├─ 主干文档(README/协作原则/phase 等)        ├─ INDEX.md                ★
+├─ doco/migration/git/init/dev/plan         ├─ 看板升级子项目_Brief.md  ★
+├─ Phase 3 续接快照系列                     ├─ Claude协作原则.md(拷贝)
+├─ backlog(顶部加标注)                      ├─ 续接快照 v1/v3/v4
+├─ 寄存条_看板升级已外迁.md           ★    ├─ xlsx + 11 份 docx(副本)
+├─ xlsx + 11 份 docx(副本)                 ├─ dashboard 首页原版(副本)
+├─ dashboard 首页原版(副本)                 ├─ 色调字体倒角(副本)
+└─ 色调字体倒角(副本)                       ├─ dashboard 首页_拷贝.jpg
+                                            └─ 简洁风_清晰.jpg
+```
+
+★ = 新增
+
+---
+
+## 拿不准的就先不动
+
+任何一份文件去留拿不准的,**先保留**。文件保留比误删容易处理。
@@ -0,0 +1,151 @@
+# F3 横轴量化方法 PRD v1.0
+
+> 子项目交付物 · 看板分析升级
+> 状态:**v1.0 已锁**(2026-06-12 通哥审过 §2/§3/§4 决策)
+> 起草时间:2026-06-12
+> 顾问:Claude Opus 4.7 ｜ 制片人:刘通
+> 类型:薄 PRD(只解 v2 之后留下的开放点,已锁部分仅引用)
+
+---
+
+## §1 引用已锁结论(不重述)
+
+本 PRD 是对已有结论的**补丁/收敛**,不替换。已锁部分直接参见以下来源:
+
+| 来源 | 已锁内容 |
+|---|---|
+| 续接快照 v2 §3 | 横轴公式 `X = 该题材在分析窗口内的均值份额 − 栏目均值份额`,零点 = 栏目均值,单位 = 收视份额绝对差 |
+| 续接快照 v2 §4 | 双引擎象限图视觉规格:气泡大小 = 收视份额、气泡颜色 = 收视判定三色、气泡边框 = 开篇钩子三档、重叠用 jitter 解 |
+| 主 project Claude 示意图(2026-06-10) | 23 期实际数据 + 模拟纵轴/钩子已可视化,制片人认可"不挤、不堆叠" |
+| 续接快照 v3 §1.1 / v4 §3 | 纵轴从 3 档收为 2 档(主线演进 / 并列结构),Prompt 2 v0.2 + ground-truth v0.2.1 M3 100% 锁定 |
+| 续接快照 v2 §2 字段二 | `equipment_domain` 多选 9 类:陆战装备 / 海军舰船 / 航空航天 / 导弹与反导 / 信息化 / 后勤保障 / 轻武器 / 跨域 / 其他 |
+
+本 PRD 解决 v2 之后留下的三个开放点:**多标签横轴取值规则、小样本兜底、视觉规格刷新到 2 档纵轴**。
+
+---
+
+## §2 决策一:多标签 → 横轴单点取值规则(Path A 全额法)
+
+`equipment_domain` 字段为多选(至少 1 项),但横轴一期只能落一个点。
+
+### 2.1 规则
+
+**每个 `equipment_domain` 标签独立维护自己的累计均值;一期节目标了 N 个标签,就把该期完整 share 直接记进**每一个**沾上的标签的均值池(全额、不瓜分、不加权)。**
+
+### 2.2 数学定义
+
+```
+对每个 equipment_domain 标签 i:
+    base_i = 所有沾标签 i 的节目的 share 的算术平均
+           = Σ(share_j, ∀ j 沾标签 i) / count(j 沾标签 i)
+
+栏目均值:
+    base_全栏目 = 所有节目的 share 的算术平均(单期单算)
+
+每期 ep 的横轴位置:
+    X(ep) = mean(base_i, ∀ i ∈ ep.equipment_domain) − base_全栏目
+```
+
+### 2.3 示例
+
+设当前 `海军舰船` 桶均值 = 0.69,`跨域` 桶均值 = 0.79,栏目均值 = 0.72。
+
+- 一期标 `海军舰船 + 跨域`,share = 0.71
+- 该期 X 位置 = (0.69 + 0.79) / 2 − 0.72 = **+0.02**(略偏热)
+- 这期 share = 0.71 同时记入 `海军舰船` 均值池(下次 base 重算用)和 `跨域` 均值池
+
+**两点说明**:
+
+1. **均值更新方向自洽**:0.71 < 0.72(栏目均值),也低于"跨域 0.79"。记入两个桶后,两个桶的均值都会被这期略往下拉,符合"低于均值的样本拉低均值"的直觉。
+2. **不存在 ×N 放大**:之前讨论过的"按基值加权 × 标签数"方案因方向 bug(低于均值的样本可能反向拉高均值)被否决,详见 2026-06-12 续接讨论。
+
+### 2.4 适用范围
+
+本规则**仅用于横轴 X 值计算**。其他统计(能力地图、编导对比、scene_tags 分布等)的多标签处理另议。
+
+---
+
+## §3 决策二:小样本兜底规则
+
+某 `equipment_domain` 桶若在当前分析窗口内样本量 n 较小,均值统计意义弱。视觉上需可辨。
+
+### 3.1 兜底分档
+
+| 桶样本量 | 视觉处理 |
+|---|---|
+| **n ≥ 3** | 正常显示,base 值直接入横轴坐标 |
+| **n = 1 或 2** | 桶名右侧显示 `(n=X)` 灰色小字;桶内气泡描边改为虚线浅灰;tooltip 警示"样本不足,横轴位置参考价值有限" |
+| **n = 0** | 桶不出现在横轴坐标系上(如 `陆战装备` 在 21 期场景下属此类,预留枚举值但暂不画) |
+
+### 3.2 阈值出处
+
+n = 3 阈值的取法:统计上方差估计起码需 2 自由度,记录方便取 3。**这是初值,后续看实际分布可调**。
+
+### 3.3 当前 21 期场景的小样本桶预测
+
+按 v2 §2 九类 + 我对 21 期的初步映射(见配套回填提案表):
+
+- `导弹与反导` n=1(ep15 一期),**小样本桶**
+- `信息化` n=1 或 2(取决于 ep03 是否归这里 vs 跨域),**可能小样本**
+- `陆战装备` n=0,**不出现在坐标系**
+- `后勤保障` n=0,**不出现在坐标系**
+- `其他` n=0,**不出现在坐标系**
+
+其余 4 个桶(`海军舰船` / `航空航天` / `轻武器` / `跨域`)预计 n ≥ 3,正常显示。
+
+---
+
+## §4 决策三:视觉规格刷新(纵轴 3 档 → 2 档)
+
+v2 §4 视觉规格除以下差异外,**全部沿用**:
+
+| 元素 | v2 §4(3 档,旧) | 本版(2 档,新) |
+|---|---|---|
+| 纵轴档位 | 强主线悬念 / 主线演进 / 并列结构 | **主线演进 / 并列结构**(v3 §1.1 收为 2 档) |
+| 纵轴坐标 | 三个水平基线 | 两个水平基线 |
+| 同档内 jitter | ±0.3 | ±0.4(档少了,jitter 可适当加大避免聚拢) |
+| 中线视觉 | 两条次级分隔 | **一条主分隔线显著加粗**,强调"主线 vs 并列"对照 |
+| 上下区视觉重点 | 三层等权 | **两区中性等权**——纵轴不暗示偏好方向,呈现客观对照(2026-06-12 通哥拍板) |
+
+横轴部分全部沿用 v2 §4,无变化。
+
+---
+
+## §5 配套交付清单(子项目本轮其余产出)
+
+- [✅ 本文件] `F3_横轴量化方法_PRD_v1.0草稿.md`
+- [⏳ 下批] `双引擎象限图_HTML_mock_v1.0.html`——基于本 PRD 的纵轴 2 档版可视化,可浏览器直开看交互
+- [⏳ 下批] `F3_算法验证脚本.py`——在子项目沙盒里跑通完整计算流程,输入 23 期 equipment_domain 多选 + share,输出各桶 base + 23 期 X 值表 + 数据校验报告
+- [⏳ 下批] `equipment_domain_字段定义文档.md`——按 Brief §6.1 格式,主 project Cline 拿去做 schema 迁移
+- [⏳ 下批] `23期_equipment_domain_回填提案表.md`——给制片人审,或转 Prompt 1a 的 ground-truth 输入
+
+---
+
+## §6 落地依赖(主 project Cline 工作清单)
+
+子项目这边的 5 份交付物全部锁定后,主 project Cline 可接手以下工作(均需切 Plan + Opus 审):
+
+1. **Schema 迁移**:`backend/sql/00X_add_equipment_domain.sql`(基于字段定义文档)
+2. **23 期回填**:Prompt 1a 跑批结果落库 + 制片人审过的 8 期标题推断低置信度样本
+3. **后端 API endpoint**:横轴聚合数据接口 `GET /api/v1/episodes/quadrant-data`(或类似)
+4. **前端 React/ECharts 组件**:基于本 PRD 的 HTML mock 1:1 翻译
+
+---
+
+## §7 后续可能调整项(本版不解,留入 backlog)
+
+- **时间窗口选择**:滚动窗口 vs 全部历史 vs 季度,默认设"全部历史",后续 UI 加切换器
+- **n ≥ 3 阈值的实际验证**:用 23 期 + 新片陆续入库 6 个月后看分布,必要时调阈值
+- **多标签规则是否升级**:本版用全额路 A,运行半年若发现不妥(如某桶均值长期被高频跨域期数刷高)再议升级到带权或 1/N 守恒版
+- **n=1/2 视觉表达细节**:虚线浅灰 vs 描边淡化 vs 加图例,等 HTML mock 出来后定
+
+---
+
+## §8 修订规则
+
+本 PRD 锁定 v1.0 后:
+
+- v1.x 微调(视觉细节、阈值小动)在本子项目内修改
+- v2.0 重大变更(规则换路 B、取消纵轴 2 档等)需主 project 同步审,通过新一版续接快照固化
+
+修订必留 changelog,谁、何时、改了什么、为什么改。
@@ -0,0 +1,151 @@
+# F3 横轴量化方法 PRD v1.0(草稿)
+
+> 子项目交付物 · 看板分析升级
+> 状态:**草稿**,等制片人审 + 锁定后转正式 v1.0
+> 起草时间:2026-06-12
+> 顾问:Claude Opus 4.7 ｜ 制片人:刘通
+> 类型:薄 PRD(只解 v2 之后留下的开放点,已锁部分仅引用)
+
+---
+
+## §1 引用已锁结论(不重述)
+
+本 PRD 是对已有结论的**补丁/收敛**,不替换。已锁部分直接参见以下来源:
+
+| 来源 | 已锁内容 |
+|---|---|
+| 续接快照 v2 §3 | 横轴公式 `X = 该题材在分析窗口内的均值份额 − 栏目均值份额`,零点 = 栏目均值,单位 = 收视份额绝对差 |
+| 续接快照 v2 §4 | 双引擎象限图视觉规格:气泡大小 = 收视份额、气泡颜色 = 收视判定三色、气泡边框 = 开篇钩子三档、重叠用 jitter 解 |
+| 主 project Claude 示意图(2026-06-10) | 23 期实际数据 + 模拟纵轴/钩子已可视化,制片人认可"不挤、不堆叠" |
+| 续接快照 v3 §1.1 / v4 §3 | 纵轴从 3 档收为 2 档(主线演进 / 并列结构),Prompt 2 v0.2 + ground-truth v0.2.1 M3 100% 锁定 |
+| 续接快照 v2 §2 字段二 | `equipment_domain` 多选 9 类:陆战装备 / 海军舰船 / 航空航天 / 导弹与反导 / 信息化 / 后勤保障 / 轻武器 / 跨域 / 其他 |
+
+本 PRD 解决 v2 之后留下的三个开放点:**多标签横轴取值规则、小样本兜底、视觉规格刷新到 2 档纵轴**。
+
+---
+
+## §2 决策一:多标签 → 横轴单点取值规则(Path A 全额法)
+
+`equipment_domain` 字段为多选(至少 1 项),但横轴一期只能落一个点。
+
+### 2.1 规则
+
+**每个 `equipment_domain` 标签独立维护自己的累计均值;一期节目标了 N 个标签,就把该期完整 share 直接记进**每一个**沾上的标签的均值池(全额、不瓜分、不加权)。**
+
+### 2.2 数学定义
+
+```
+对每个 equipment_domain 标签 i:
+    base_i = 所有沾标签 i 的节目的 share 的算术平均
+           = Σ(share_j, ∀ j 沾标签 i) / count(j 沾标签 i)
+
+栏目均值:
+    base_全栏目 = 所有节目的 share 的算术平均(单期单算)
+
+每期 ep 的横轴位置:
+    X(ep) = mean(base_i, ∀ i ∈ ep.equipment_domain) − base_全栏目
+```
+
+### 2.3 示例
+
+设当前 `海军舰船` 桶均值 = 0.69,`跨域` 桶均值 = 0.79,栏目均值 = 0.72。
+
+- 一期标 `海军舰船 + 跨域`,share = 0.71
+- 该期 X 位置 = (0.69 + 0.79) / 2 − 0.72 = **+0.02**(略偏热)
+- 这期 share = 0.71 同时记入 `海军舰船` 均值池(下次 base 重算用)和 `跨域` 均值池
+
+**两点说明**:
+
+1. **均值更新方向自洽**:0.71 < 0.72(栏目均值),也低于"跨域 0.79"。记入两个桶后,两个桶的均值都会被这期略往下拉,符合"低于均值的样本拉低均值"的直觉。
+2. **不存在 ×N 放大**:之前讨论过的"按基值加权 × 标签数"方案因方向 bug(低于均值的样本可能反向拉高均值)被否决,详见 2026-06-12 续接讨论。
+
+### 2.4 适用范围
+
+本规则**仅用于横轴 X 值计算**。其他统计(能力地图、编导对比、scene_tags 分布等)的多标签处理另议。
+
+---
+
+## §3 决策二:小样本兜底规则
+
+某 `equipment_domain` 桶若在当前分析窗口内样本量 n 较小,均值统计意义弱。视觉上需可辨。
+
+### 3.1 兜底分档
+
+| 桶样本量 | 视觉处理 |
+|---|---|
+| **n ≥ 3** | 正常显示,base 值直接入横轴坐标 |
+| **n = 1 或 2** | 桶名右侧显示 `(n=X)` 灰色小字;桶内气泡描边改为虚线浅灰;tooltip 警示"样本不足,横轴位置参考价值有限" |
+| **n = 0** | 桶不出现在横轴坐标系上(如 `陆战装备` 在 21 期场景下属此类,预留枚举值但暂不画) |
+
+### 3.2 阈值出处
+
+n = 3 阈值的取法:统计上方差估计起码需 2 自由度,记录方便取 3。**这是初值,后续看实际分布可调**。
+
+### 3.3 当前 21 期场景的小样本桶预测
+
+按 v2 §2 九类 + 我对 21 期的初步映射(见配套回填提案表):
+
+- `导弹与反导` n=1(ep15 一期),**小样本桶**
+- `信息化` n=1 或 2(取决于 ep03 是否归这里 vs 跨域),**可能小样本**
+- `陆战装备` n=0,**不出现在坐标系**
+- `后勤保障` n=0,**不出现在坐标系**
+- `其他` n=0,**不出现在坐标系**
+
+其余 4 个桶(`海军舰船` / `航空航天` / `轻武器` / `跨域`)预计 n ≥ 3,正常显示。
+
+---
+
+## §4 决策三:视觉规格刷新(纵轴 3 档 → 2 档)
+
+v2 §4 视觉规格除以下差异外,**全部沿用**:
+
+| 元素 | v2 §4(3 档,旧) | 本版(2 档,新) |
+|---|---|---|
+| 纵轴档位 | 强主线悬念 / 主线演进 / 并列结构 | **主线演进 / 并列结构**(v3 §1.1 收为 2 档) |
+| 纵轴坐标 | 三个水平基线 | 两个水平基线 |
+| 同档内 jitter | ±0.3 | ±0.4(档少了,jitter 可适当加大避免聚拢) |
+| 中线视觉 | 两条次级分隔 | **一条主分隔线显著加粗**,强调"主线 vs 并列"对照 |
+| 上下区视觉重点 | 三层等权 | 上区(主线演进)略亮、下区(并列结构)略灰,**视觉上暗示偏好方向**(可选,等通哥决) |
+
+横轴部分全部沿用 v2 §4,无变化。
+
+---
+
+## §5 配套交付清单(子项目本轮其余产出)
+
+- [✅ 本文件] `F3_横轴量化方法_PRD_v1.0草稿.md`
+- [⏳ 下批] `双引擎象限图_HTML_mock_v1.0.html`——基于本 PRD 的纵轴 2 档版可视化,可浏览器直开看交互
+- [⏳ 下批] `F3_算法验证脚本.py`——在子项目沙盒里跑通完整计算流程,输入 23 期 equipment_domain 多选 + share,输出各桶 base + 23 期 X 值表 + 数据校验报告
+- [⏳ 下批] `equipment_domain_字段定义文档.md`——按 Brief §6.1 格式,主 project Cline 拿去做 schema 迁移
+- [⏳ 下批] `23期_equipment_domain_回填提案表.md`——给制片人审,或转 Prompt 1a 的 ground-truth 输入
+
+---
+
+## §6 落地依赖(主 project Cline 工作清单)
+
+子项目这边的 5 份交付物全部锁定后,主 project Cline 可接手以下工作(均需切 Plan + Opus 审):
+
+1. **Schema 迁移**:`backend/sql/00X_add_equipment_domain.sql`(基于字段定义文档)
+2. **23 期回填**:Prompt 1a 跑批结果落库 + 制片人审过的 8 期标题推断低置信度样本
+3. **后端 API endpoint**:横轴聚合数据接口 `GET /api/v1/episodes/quadrant-data`(或类似)
+4. **前端 React/ECharts 组件**:基于本 PRD 的 HTML mock 1:1 翻译
+
+---
+
+## §7 后续可能调整项(本版不解,留入 backlog)
+
+- **时间窗口选择**:滚动窗口 vs 全部历史 vs 季度,默认设"全部历史",后续 UI 加切换器
+- **n ≥ 3 阈值的实际验证**:用 23 期 + 新片陆续入库 6 个月后看分布,必要时调阈值
+- **多标签规则是否升级**:本版用全额路 A,运行半年若发现不妥(如某桶均值长期被高频跨域期数刷高)再议升级到带权或 1/N 守恒版
+- **n=1/2 视觉表达细节**:虚线浅灰 vs 描边淡化 vs 加图例,等 HTML mock 出来后定
+
+---
+
+## §8 修订规则
+
+本 PRD 锁定 v1.0 后:
+
+- v1.x 微调(视觉细节、阈值小动)在本子项目内修改
+- v2.0 重大变更(规则换路 B、取消纵轴 2 档等)需主 project 同步审,通过新一版续接快照固化
+
+修订必留 changelog,谁、何时、改了什么、为什么改。