# 主 project 答复 — 分钟收视回放子板块

> 版本：v1
> 日期：2026-06-11
> 作者：TPS 主 project 顾问 (Claude Opus 4.7) + 制片人 刘通
> 状态：已采纳，待秒级 chat 接收并按本文件推进实现
> 上一版：无
> 对应文档：秒级收视 project《军事科技_分钟收视回放_子板块需求规格.md》v1（2026-06-10）

---

## 一、本文件用途

回复秒级 chat 那份 PRD 第八节的 6 个对接问题，并把主 project 这边的**红线、修订建议、交付物期待**全部白纸黑字写下来。本文件是子板块继续推进的**最终输入**，秒级 chat 这边可基于此开干。

子板块结束前，要按本文件第九节的清单产出**五份交付物**给主 project。主 project 这边的 Cline 拿着五份交付物落代码，完成最终整合。

---

## 二、对 6 个对接问题的最终答复

### 1. TPS 工作台有没有"每期节目详情页"？

**没有。子板块需要附带把详情页骨架建起来。**

现状：仪表盘 (Dashboard) 是聚合视角，责编录入页 (EditorDesk) 是表单 + 列表，**没有"看单期 + 该期所有维度"的页面**。分钟收视回放需要这个容器，整个工作台早晚也需要这个页面，借这次一起做掉。

入口规划：
- 仪表盘柱图每根柱子点进去 → 详情页
- EditorDesk 列表行点进去 → 详情页
- 路由建议：`/episodes/:id`，`:id` 用 `episodes.id`（SERIAL 主键）

详情页骨架要预留位置承载未来其他维度（审片意见、文稿、外拍信息等），分钟收视回放是其中**第一个模块**。

### 2. 数据库技术栈

**PostgreSQL 16 + pgvector（1536 维）**，ORM 是 **SQLModel（同步，非 async）**。

手写 SQL 走 `backend/sql/00X_*.sql`，不用 Alembic。

第五节那两张表的接入方式见第四节"数据模型修改建议"——简短版：**别新建"节目期次表"，复用现有 `episodes` 表**；分钟数据表新建，命名 `episode_minute_ratings`，外键挂到 `episodes.id`。

### 3. 视频和截图存储方案

**最终决策：视频不入工作台。**

- 视频本体由制片人在本地/百度网盘/极空间多渠道自存
- 工作台只接收**截图**（27 张 jpg）
- 不再讨论服务端 ffmpeg、视频压缩、转码删源片等服务端方案

截图处理走**本地切图工具**（子板块产出，详见第五节）：

- 责编本地双击工具 → 拖入源片 → 自动切 27 张 480p 截图 + 命名好
- 责编打开工作台 → 一键多文件上传截图（~5 MB 一次传完）

截图存储：服务器文件系统 `/screenshots/{episode_id}/{分钟序号_两位数}.jpg`，数据库只存 URL。

### 4. 前端技术栈

**React 18 + Vite + Ant Design 5 + Zustand**，JavaScript（不用 TS），项目宪法锁定。

图表库选型：

- **优先 @ant-design/charts**：与现有 AntD 5 视觉血缘最近，配色和圆角自然贴合
- **次选 ECharts**：自定义 tooltip 模板灵活成熟
- **已用过 Recharts**：仪表盘柱图已采用

**不要再引第三方图表库**。三选一即可，最终选哪个由 Cline 在 Plan 阶段定。

### 5. 后台异步任务怎么跑

**在"视频不入工作台 + 本地切图工具"决策下，服务端没有重型异步任务。**

工作台后端只接收截图入库 + 跑数据校验（见第四节建议 E），都是毫秒级同步操作，**FastAPI BackgroundTasks 都用不上**。

如果未来某个新场景确实需要异步任务，再启用 FastAPI BackgroundTasks。**不引 Celery、不引 Redis 队列**——8 人栏目用这些是过度工程。

### 6. 录入身份/权限

**有完整用户系统**：Session + Cookie 认证，三角色拼音枚举锁定（`zhipianren` / `zebian` / `biandao`）。

写权限规则参照 `yearly_targets` 既有口径平移：

- **POST/PATCH/DELETE 录入分钟数据 + 上传截图**：`zhipianren` + `zebian` 可写，`biandao` 返回 403
- **GET 查看分钟回放**：三角色均可读

**实现细节**：FastAPI 后端直接从 session 拿 user_id 写入 `created_by` 字段，**前端不要把"录入人"作为字段提交**。

字段命名用 `created_by INTEGER REFERENCES users(id)`，**不要用 string 类型的"录入人姓名"**——主 project backlog 里有一条 "操作留痕 schema"（待办池 B2），分钟收视这张新表作为落地先例。

---

## 三、视频/截图最终方案（决策落地）

### 责编一周一期的标准流程（最终版）

```
周二 21:20-21:47   节目播出
       ↓
周二 22:00 后      责编到总编室账号抄 27 个份额数字（保留原方案）
       ↓
次日              责编打开本地切图工具
       ↓
                  拖入当期源片 mp4 → 工具自动切 27 张 480p jpg
                  + 自动命名为 01.jpg ~ 27.jpg
       ↓
                  责编登录工作台 → 进入"节目期次"管理
                  → 选择当期 episode（基于已录入的 episodes 记录）
                  → 进入分钟收视模块
       ↓
                  上传 27 张截图（多文件选择 / 拖拽）
                  → 服务器存到 /screenshots/{episode_id}/
                  → 数据库写入 27 条 episode_minute_ratings 记录
       ↓
                  录入 27 个份额数字
                  （推荐："批量粘贴一列数字"输入框，
                  从 Excel 复制 27 个数字粘贴后系统按行切分）
                  → 系统软校验（数据齐全？范围合理？均值与已录全期均值吻合？）
                  → 保存
       ↓
                  该期详情页里"分钟收视回放"模块即刻可看
```

### 主 project 这边不做的事

- 服务端 ffmpeg（不需要）
- 视频上传接口（不需要）
- 视频压缩转码（不需要）
- 异步任务队列（不需要）
- 视频删除/清理脚本（不需要）

---

## 四、数据模型修改建议（主 project 在此明确给出）

> 任何 schema 改动**必须经主 project 顾问 (Opus) 审、配回补方案，Cline 不得自行动手**。这是项目红线。下面是建议方案，最终落地前还会过一遍审查。

### 建议 A：复用现有 `episodes` 表，**不新建"节目期次表"**

现有 episodes 表已涵盖你需要的全部"节目期次"信息：

| 你的字段 | 对应现有 episodes 字段 |
|---|---|
| 期次主键 | `id`（SERIAL） |
| 期数显示 | 前端从 `air_date` + `episode_number` 拼，不入库 |
| 节目名称 | `program_name` |
| 播出日期 | `air_date` |
| 播出时段 | 不入库，前端常量 "21:20-21:47" |
| 备注 | `notes` |

理由：新建一张冗余表会割裂 episodes 与其他模块（收视成绩、外拍、未来选题、审片意见）的关联，破坏单一事实源。

### 建议 B：用 `episodes.id`（INTEGER）做外键，**不用"播出日期 string"做主键**

秒级 chat v1 文档建议"期次主键用 `2026-06-09` 字符串"。这与 `episodes.id SERIAL` 体系冲突。

最终方案：分钟数据表用 `episode_id INTEGER REFERENCES episodes(id)` 外键，所有展示字符串（"2026 年第 23 期 · 2026-06-09"）由前端从 episodes 数据拼出，不入库。

### 建议 C：`收视份额` 用 `NUMERIC(6,4)`，**不用 float**

与现有 `episodes.audience_share NUMERIC(6,4)` 类型对齐，避免浮点比较的怪事。

### 建议 D：新表 `episode_minute_ratings` 建议 schema

```sql
CREATE TABLE IF NOT EXISTS episode_minute_ratings (
    id              SERIAL PRIMARY KEY,
    episode_id      INTEGER NOT NULL REFERENCES episodes(id) ON DELETE CASCADE,
    minute_index    INTEGER NOT NULL CHECK (minute_index BETWEEN 1 AND 27),
    audience_share  NUMERIC(6,4) NOT NULL,
    screenshot_url  VARCHAR(500),
    created_by      INTEGER NOT NULL REFERENCES users(id),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE(episode_id, minute_index)
);

CREATE INDEX idx_minute_ratings_episode ON episode_minute_ratings (episode_id);
```

P1+ 扩展（多期对比、批注/标签）：1.0 不建表，到 P1 触发时再说。当前 UNIQUE 复合键和外键设计已留好扩展空间。

### 建议 E：工作流补一个"软校验"环节

录入 27 个分钟份额时，系统应做**非阻塞**的合理性提示：

- 27 个数字是否齐？
- 最大值/最小值是否在合理区间（如 0-3）？
- 27 个数字的平均值是否与已录的 `episodes.audience_share`（该期全期均值）大致吻合？误差 > 30% 给"数据可能录错"提示

不阻塞保存，只是温柔提醒。理由：分钟数据是栏目考核依据，权重最高，录错一个小数点不发现就一直错。

### 建议 F：批量导入接口复用现有 ExcelService

23 期历史数据一次性导入：复用主 project 已有的 ExcelService 框架（Phase 2 Task 2 跑通），但单开一个 endpoint：

- 上传一份"期次 × 27 列分钟份额"的 Excel
- 按行展开成 23 × 27 = 621 条 `episode_minute_ratings` 入库
- 截图 URL 字段第一次导入时留空，后续走本地工具补传

### 建议 G：episodes 表是否要加视频 URL 字段？

**不加。**

因为视频不入工作台。如果未来某天想记录"这一期视频存在哪个网盘 / 哪个本地路径"，可以走 `episodes.notes` 字段写自由文本，不需要专门字段。

---

## 五、本地切图工具规格（子板块产出物之一）

子板块的 Claude 负责设计与实现这个工具。

### 5.1 形态

- 一个 Windows 上能跑的可执行文件（py 源码 + pyinstaller 打包成 exe）
- 双击即用，无安装步骤
- 不依赖网络，不依赖工作台，完全离线
- 不需要责编装 Python 环境

### 5.2 用户界面

简洁到极致：

- 一个窗口，拖文件进去即可（或"选择文件"按钮）
- 接收 mp4 / mov / mkv 等常见格式
- 进度条显示切图进度
- 完成后弹"已生成 27 张截图于 [输出文件夹]"
- 自动打开输出文件夹

### 5.3 切图规则（与秒级 chat v1 文档保持一致）

```bash
# 27 张截图，每分钟第 30 秒位置，480p (854 × 480)
for i in $(seq 0 26); do
  sec=$((i*60+30))    # 0:30, 1:30, 2:30, ..., 26:30
  ffmpeg -i 源片.mp4 -ss $sec -vframes 1 -vf scale=854:480 \
         "$(printf "%02d" $((i+1))).jpg" -y
done
```

输出文件名规则：**`01.jpg` ~ `27.jpg`**（两位数，零填充，便于排序）。

### 5.4 输出文件夹组织

工具自动新建一个文件夹，命名建议：`截图_{源片文件名去后缀}_{日期}/`，里面 27 张 jpg。

### 5.5 ffmpeg 依赖

打包时把 ffmpeg.exe 一并塞进 exe，或者用 `imageio-ffmpeg` 包自动下载。**绝对不要让责编手动装 ffmpeg**。

### 5.6 错误处理

- 源片读不到 → 弹窗"文件无法读取，请检查格式"
- 源片时长 < 26 分 30 秒 → 弹窗"视频时长不足 27 分钟，是否继续？"（允许跳过缺失分钟）
- 输出文件夹已存在 → 自动加时间戳后缀

### 5.7 给责编的使用说明

子板块产出一份 `使用说明.md`，傻瓜级，要有截图。预期长度 200-400 字 + 3-5 张截图。

---

## 六、主 project 红线（不可越）

子板块设计与实现过程中，下面这几条是**主 project 宪法**，任何方案不得违反：

1. **改 schema 须主 project 顾问 (Opus) 审**：包括新建表、改字段、加字段。Cline / 子板块 Claude 不得自行动手。
2. **角色枚举锁定拼音值**：`zhipianren` / `zebian` / `biandao`，不许新增枚举，不许用英文别名。
3. **AI 给方向不给答案**：分钟收视回放的 P1+ 功能（多期对比找规律、批注 AI 建议等）若涉及 AI，必须保持"建议草稿 + 制片人审核"的三档置信度，不得 AI 直接拍板。
4. **编导关联用"软引用 + 快照"**：本子板块如需展示编导信息，沿用 `episodes.editor_id` + `episodes.editor_name_snapshot` 双字段，不许新增编导关联字段。
5. **收视颜色判定**：红=优秀（>摸高目标）/ 蓝=达标 / 绿=待提升（<基础目标）。反直觉规约，分钟收视回放折线图如果上色，按此规则。
6. **AI 输出必须有"忽略 / 我来改写"否决权**：任何 AI 建议（如本子板块 P1+ 的 AI 找规律功能）必须给编导否决入口。
7. **不引新依赖**：图表库三选一（@ant-design/charts / ECharts / Recharts），不引第四个；后端不引 Celery / Redis 队列。

---

## 七、子板块产出物清单（最终交付包）

子板块结束前，请凝结成以下**五份交付物**，作为整体交付给主 project：

### 产物 1：决策摘要 md

记录子板块全程的关键决策。每条决策三句话：

```
决策 X：[一句话决策内容]
  - 背景：为什么需要这个决策
  - 拍板理由：选这条不选那条的理由
  - 拍板人：[制片人 / 主 project 顾问 / 子 project Claude 建议+制片人采纳]
```

10-20 条决策足以讲清整个子板块"为什么这么做"。

### 产物 2：接口约定 md（最技术、最精确）

把子板块与主 project 接驳的所有"接口"白纸黑字写出来：

- **数据接口**：新建表 / 字段 / 类型 / 约束（细化到 SQL DDL 级别）
- **API 接口**：新增 endpoint URL / 方法 / 请求体 / 响应体 / 错误码
- **UI 接口**：在主 project 哪个页面挂载、入口、路由
- **权限接口**：哪些角色可以做什么操作
- **存储接口**：截图存到哪个目录、命名规则、URL 拼接规则

要具体到"主 project 的 Cline 拿着这份就能写代码"的程度。**这是子 project 给主 project 的"合同"**。

### 产物 3：本地切图工具完整包

- `screenshot_tool.py`：源码，注释齐全
- `screenshot_tool.exe`：打包好的可执行文件，责编双击即用
- `使用说明.md`：傻瓜级文档 + 截图

工具规格见本文件第五节。

### 产物 4：未尽事项 backlog

诚实写出"子板块讨论中提到但没做的事"。每条三行：

- 是什么
- 为什么没做（暂缓 / P1+ / 等条件成熟）
- 触发时机（什么时候应该捡起来）

放进主 project 的 backlog 池子里。

### 产物 5：给主 project Claude 的"接手提示词"

一两段话，告诉主 project 顾问"如果你是接手这件事的 Claude，最重要的三件事是 X、Y、Z"。

这次至少要包含：
- 复用 episodes 表，不新建节目期次表
- 权限沿用 yearly_targets 口径
- 本地切图工具与工作台零耦合，不在工作台 UI 里给它留接口

---

## 八、跨 project 协作规矩（子板块这边也要遵守）

1. **不动主 project 代码**：子板块产出文档 + 独立工具，不写主 project 的实际代码。代码合入由主 project 的 Cline 完成。
2. **遇到吃不准的事回主 project 问**：本次 v1 文档第八节就是好榜样，继续保持。
3. **每份跨 project 文档顶部带元信息块**：版本、日期、作者、状态、上一版、主要变化（v2 以上必填）。
4. **一份文档只谈一件事**：不要在分钟收视回放交付包里夹带其他议题。

---

## 九、给秒级 chat Claude 的明确动作清单

收到本文件后，请按下面顺序推进：

1. **吸收本文件所有决策与红线**，回到秒级 chat 的 PRD v1，把不一致处标注出来（如果有）
2. **如有需要修订的地方，出 PRD v2**，顶部元信息块写明跟 v1 的变化点
3. **设计本地切图工具**：与制片人讨论用户体验细节，定稿后凭工具规格让秒级 chat 的 Cline 实现（如果有）或制片人自己找 v0/Lovable 等工具生成 demo
4. **凝结成最终五份交付物**（第七节清单）
5. **交付给制片人**，由制片人带回主 project，主 project 顾问 (Opus) 审一遍，无冲突后主 project 的 Cline 落实施

---

## 十、附：版本演进规约

本文件未来如修订（v2+），顶部元信息块"主要变化"必须写清楚改了什么。

历史版本不覆盖，旧文件保留在 `docs/cross_project/` 目录（主 project 这边）以便回看决策史。

---

*本文件由主 project 顾问 (Claude Opus 4.7) 于 2026-06-11 基于与制片人刘通的两轮对话整理生成，供秒级收视项目接收使用。*