simonkoson
143 lines
10 KiB
Markdown
143 lines
10 KiB
Markdown
# PRD：期次一条龙录入（收视分析可持续化）v1.0
|
||
|
||
> 立项：2026-07-07 ｜ 需求方：制片人 ｜ 起草：Claude（顾问）
|
||
> 目标页面：责编录入（`frontend/src/pages/EditorDesk/EditorDesk.jsx`）
|
||
> 实施方式：Cline Plan + Opus 审 + 制片人批准 Act（含一次 schema 迁移，走既定纪律：迁移前 pg_dump 备份）
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
看板升级的终极目标是"每做完一期节目，系统自动消化文稿和收视成绩，持续输出诊断"。但现在 25 期数据是一次性脚本导入的，往后每周新一期没有入口——收视数据、文稿入库、AI 打标、制片人审核、摘要卡生成五件事散在各处。
|
||
|
||
**本功能把这五件事收进责编录入页面，做成一条龙：责编录数据传文稿 → 系统自动 AI 处理 → 制片人审核标签 → 该期自动进入收视分析看板全部模块。**
|
||
|
||
不做成强制向导（收视数据播出次日才有、文稿可能更早就有），做成**每期一张任务清单**：五个环节各自独立完成、随时可补，页面上一眼看出"这期还差什么"。
|
||
|
||
---
|
||
|
||
## 2. 每期五个环节（流水线定义）
|
||
|
||
| # | 环节 | 谁操作 | 做什么 | 完成判定（从现有字段推导，不加状态列） |
|
||
|---|------|--------|--------|--------------------------------------|
|
||
| ① | 基础信息+收视 | 责编 | 现有新增/编辑期次表单，收视份额可后补 | `audience_share` 非空 |
|
||
| ② | 文稿上传 | 责编 | 上传该期 **doco 融合A稿**（docx/md）→ 自动入知识库+算向量+关联期次 | `transcript_item_id` 非空（新列，见 §5） |
|
||
| ③ | AI 处理 | 责编或制片人 | 一键触发：打标（Prompt 1/2/3 → 6 个标签字段）+ 摘要卡（Prompt 4 → content_digest），后台串行跑 | `program_format` 非空 且 `content_digest` 非空 |
|
||
| ④ | 制片人审核 | **仅制片人** | 看 AI 草稿标签，逐项可改（下拉枚举），点「审核通过」 | `ai_label_confidence == 'reviewed'` |
|
||
| ⑤ | 完成 | — | 无操作，①-④全勾即完成，该期在看板全模块生效 | 前四项全满足 |
|
||
|
||
**环节依赖**：③ 依赖 ②（没文稿没法打标）；④ 依赖 ③；①与②③无顺序要求。
|
||
|
||
---
|
||
|
||
## 3. 页面设计（责编录入页改造）
|
||
|
||
### 3.1 「节目期次」Tab 升级为流水线视图
|
||
|
||
现有表格增加一列「流水线」，每行显示 4 个状态点（收视 / 文稿 / AI处理 / 已审核），完成=实心绿点，未完成=空心灰点。鼠标悬停显示环节名。
|
||
|
||
表格行新增「处理」按钮 → 打开该期的**流水线抽屉（Drawer）**。
|
||
|
||
### 3.2 流水线抽屉（核心新界面）
|
||
|
||
抽屉从右侧滑出（宽约 560px），从上到下四个区块，对应环节 ①-④：
|
||
|
||
**区块一：基础信息+收视**
|
||
- 只读展示期次号/节目名/播出日期/编导/收视份额，带「编辑」按钮打开现有编辑弹窗。收视份额为空时黄色提示"收视数据待补录"。
|
||
|
||
**区块二：文稿**
|
||
- 未上传：拖拽上传框（接受 .docx / .md，单文件，≤10MB）。上传后后端自动：解析文本 → 写入知识库（source_type=manuscript，author=该期编导快照）→ 调 MiniMax 算 1536 维向量 → 回写 `episodes.transcript_item_id`。
|
||
- 已上传：显示文件名+入库时间+「重新上传」按钮（重传=删旧知识库条目+走一遍新流程，需二次确认弹窗）。
|
||
|
||
**区块三：AI 处理**
|
||
- 前提未满足（无文稿）：按钮置灰，提示"请先上传文稿"。
|
||
- 就绪：「开始 AI 处理」按钮。点击后后台任务串行跑 4 个 Prompt（分类/叙事/钩子/摘要卡），前端每 3 秒轮询进度，显示"打标中 2/4…"。全程预计 1-3 分钟，期间可关抽屉，不阻塞。
|
||
- 完成：展示 6 个标签结果 + 摘要卡生成时间；标签区显著标注 **「AI 草稿·待制片人审核」**（黄色 Tag）。
|
||
- 失败：显示错误信息 + 「重试」按钮（按 Prompt 粒度断点续跑，已成功的不重跑）。
|
||
|
||
**区块四：制片人审核**
|
||
- 仅制片人可见可操作（责编看到的是"待制片人审核"或"已审核"状态文字）。
|
||
- 6 个标签渲染为可编辑表单：program_format（单选下拉 6 值）、equipment_domain（多选 9 值）、scene_tags（多选 4 值）、tech_tags（多选 3 值）、narrative_structure（单选 2 值）、opening_hook（单选 3 值）。枚举值以 `ai-labeling/CLAUDE.md` §1.4 为准，前后端各存一份常量并对齐。
|
||
- 「审核通过」按钮：保存表单值 + 置 `ai_label_confidence='reviewed'`。
|
||
- 已审核后再次打开可继续修改并重新保存（保持 reviewed）。
|
||
- 已审核的期次若重跑 AI 处理，需二次确认："该期标签已审核，重跑将覆盖为草稿状态，确定？"
|
||
|
||
---
|
||
|
||
## 4. 后端设计
|
||
|
||
### 4.1 新增 API（`backend/app/api/pipeline.py`，前缀 `/api/pipeline`）
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/episodes/{id}/status` | 三角色可读 | 返回该期四环节完成状态（从字段推导） |
|
||
| POST | `/episodes/{id}/transcript` | 责编+制片人 | 上传文稿：解析→知识库入库→embedding→回写关联 |
|
||
| DELETE | `/episodes/{id}/transcript` | 责编+制片人 | 删除关联文稿（重传前置步骤） |
|
||
| POST | `/episodes/{id}/ai-process` | 责编+制片人 | 启动后台 AI 处理任务，返回 task_id |
|
||
| GET | `/episodes/{id}/ai-process/status` | 三角色可读 | 轮询任务进度（pending/running 2/4/done/failed+错误信息） |
|
||
| POST | `/episodes/{id}/labels/review` | **仅制片人** | 保存审核后标签 + 置 reviewed |
|
||
|
||
### 4.2 AI 处理服务（`backend/app/services/labeling_service.py`，新建）
|
||
|
||
- 把 `ai-labeling/scripts/run_labeling.py` 和 `gen_content_digest.py` 的调用逻辑移植为后端服务函数（脚本本身保留不动，作为批量工具）。
|
||
- Prompt 文件继续从 `ai-labeling/prompts/` 读取（与 analytics.py 读 prompt5 的做法一致）——**Prompt 是活资产，继续在子项目里迭代，后端只读不复制**。
|
||
- 模型：打标+摘要卡用 **mimo-v2.5-pro**（生产模型，与子项目选型一致）；`MIMO_API_KEY` 加入 `backend/.env`。
|
||
- 沿用子项目已验证的技术约束：剥 `<think>` 前缀正则、不用 `response_format=json_object`、打标关 thinking。
|
||
- 后台任务用 FastAPI `BackgroundTasks` + 内存任务表（与诊断报告内存缓存同款做法，1.0 不引入 celery/redis）。
|
||
- 打标结果落库时 `ai_label_confidence='draft'`。
|
||
|
||
### 4.3 文稿入库复用
|
||
|
||
- 复用 Phase 3 知识库上传/embedding 链路（`knowledge.py` 的入库+向量逻辑抽成可复用函数供 pipeline 调用）。
|
||
- docx→文本解析参考 `ai-labeling/scripts/import_transcripts.py`（python-docx，后端需确认依赖已装）。
|
||
|
||
---
|
||
|
||
## 5. Schema 变更（005 迁移，需 Opus 审 + 制片人批准 + 迁移前 pg_dump）
|
||
|
||
```
|
||
005_add_transcript_link.sql
|
||
episodes 表 + 1 列：
|
||
transcript_item_id INTEGER NULL REFERENCES 知识库条目表(id) ON DELETE SET NULL
|
||
```
|
||
|
||
- 可空软引用：文稿被从知识库删除时自动断开关联（SET NULL），期次不受影响——与"软引用+快照"既有哲学一致，**禁止级联删期次**。
|
||
- 同步更新 `backend/app/models/episode.py` 和 `schemas/episode.py`。
|
||
- **不加流水线状态列**——四环节状态全部从现有字段推导（见 §2 表），避免状态与事实不同步。
|
||
- 迁移同时做一次**存量数据回填**：现有 25 期中已导入 AI 标签的，`ai_label_confidence` 统一置 `'reviewed'`（这批标签源自制片人逐期审定的 ground-truth v0.6.0，视为已审）。
|
||
|
||
---
|
||
|
||
## 6. 与看板的联动规则（设计哲学红线落地）
|
||
|
||
- **看板象限图/题材对比等依赖 AI 标签的模块，只使用 `ai_label_confidence='reviewed'` 的期次**。草稿标签绝不进入编导可见的任何图表（红线："未审核内容对编导显示待审核，绝不展示 AI 草稿值"）。
|
||
- 走势图、指标卡等不依赖标签的模块照常显示全部期次（不受审核状态影响）。
|
||
- L4 诊断报告的数据组装同样只取 reviewed 期次的标签 + 摘要卡。
|
||
- v1 简化处理：未审核期次直接不出现在标签类图表中（不做按角色区分渲染），审核通过后自然出现。
|
||
|
||
---
|
||
|
||
## 7. 验收标准（制片人真实点页面逐条验，不信自检）
|
||
|
||
1. 责编新增一期 + 填收视 → 流水线列显示 1/4 完成。
|
||
2. 上传一份真实融合A稿 docx → 知识库管理页能看到该文稿、语义可检索（向量已算）、流水线 2/4。
|
||
3. 点「开始 AI 处理」→ 3 分钟内 6 个标签+摘要卡就位，标签带"AI 草稿"黄标，流水线 3/4。
|
||
4. 用责编账号看抽屉 → 审核区不可操作；用制片人账号 → 可改标签、点审核通过 → 流水线 4/4。
|
||
5. 审核通过后刷新收视分析看板 → 该期出现在双引擎象限图和题材对比中；审核前不出现。
|
||
6. AI 处理中途断网/API 失败 → 状态显示失败+可重试，已成功的 Prompt 不重跑。
|
||
7. 重跑已审核期次 → 有二次确认，确认后标签回到草稿态、看板中该期从标签类图表消失。
|
||
|
||
## 8. 分期实施建议（给 Cline 排刀）
|
||
|
||
- **第一刀（纯前端+已有API）**：流水线状态列 + 抽屉骨架 + 区块一（复用现有表单）。
|
||
- **第二刀（后端）**：005 迁移 + 文稿上传入库关联（区块二）。**doco 22 期成品批量导入知识库+回联期次（§9.2）也挂这一刀**——迁移落地后立即有真实数据可验。
|
||
- **第三刀（后端+前端）**：AI 处理服务 + 后台任务 + 进度轮询（区块三）。
|
||
- **第四刀**：审核表单 + 权限 + 看板 reviewed 过滤（区块四 + §6）。
|
||
- 每刀独立可验收，任何一刀卡住不影响已上线部分。
|
||
|
||
## 9. 已拍板决定（制片人 2026-07-07）
|
||
|
||
1. **文稿口径 = doco 融合A稿**。理由（制片人）：doco 以播出后唱词字幕 OCR 为最标准依据；CCA 是播出前生产唱词的工具，审片和播出后编导/责编还可能改，不是最终文稿。**由此确认 doco 转入常态运行：每期播出后跑一遍 doco 全流程产出融合A稿，作为环节②的固定上游。**
|
||
2. **旧期次文稿要回联期次**。doco 22 期批量导入知识库时，导入脚本一并回写 `transcript_item_id`。期次号与播出日期已在融合A稿文件名中注明（格式 `第XX期_YYYYMMDD_节目名_编导_融合A稿.docx`），可直接解析匹配。
|
||
3. **责编可触发「开始 AI 处理」**。系统日常维护以责编为主，权限按"责编+制片人"实施（即 §4.1 现设计，不改）。
|