# 02 · 产品需求文档（PRD）

> 综合 `prd_md.md` / `需求点清单.md` / `project-summary.html` / `app.py` 还原
> 版本基线：v3.0（localhost:5199）｜ 当前状态：可演示，鉴权/回放授权未闭环

---

## 1. 产品概述

**君弘研究·直播控台** 是一个面向期货投教场景的直播管理中台，整合保利威直播能力，提供预告管理、直播间运营、团队/研究员管理、前端节目单/直播大厅/回放中心，并以**适当性 C1–C5 + VIP 分级**作为观看合规闸门。

## 2. 目标与范围

**In Scope**
- 预告 / 直播间 / 回放 全链路 CRUD 与状态流转
- 预告信息自动注入直播间（开播前30min）/ 恢复（结束后30min）
- 命中检测（±20min）与开播通知
- 适当性 + VIP 观看准入（自定义授权回调）
- 前端展示页（节目单 / 直播大厅 / 回放中心 / 观看验证）
- 保利威频道创建与字段回填（标题/封面/场景/模板/密码）

**Out of Scope（当前未实现 / 需补）**
- 回放（VOD）的 PolyV 授权闸门（仅直播自定义授权）
- 真实用户体系（当前为 `userid` 模拟登录）
- 内容分发到第三方平台
- 聊天/打赏/马拉松等直播中互动运营（草图有，工程未做）

## 3. 用户角色与权限矩阵

| 角色 | 预告 | 直播间 | 观看闸门 | 前端展示 |
|---|---|---|---|---|
| 运营 | 增删改查 | 增删改查/批量/开关 | 配置条件 | 管理后台 |
| 研究员 | — | 被关联为主播 | — | 出现在卡片 |
| 观众 | — | — | 过适当性/VIP | 节目单/大厅/回放/观看页 |
| 管理员 | 全部 | 启用/禁用/WEB开关/审计 | — | — |

## 4. 功能需求

### 4.1 预告管理
- 创建预告：标题、封面、简介、富文本、关联直播间（必填）、板块、品种、适当性、VIP、计划开播时间
- 列表：按状态/时间筛选、编辑、删除、复制分享链接
- 状态自动计算：pending（未到）/ live（开播后2h内）/ ended（超2h）
- 命中状态：pending / hit / missed

### 4.2 直播间管理
- 字段见 `需求点清单.md` 第二节（三层结构：保利威原生 / 管理台默认 / 当前生效）
- 筛选：状态、标签、开播时间排序、适当性、启用、WEB 启用
- 批量：全选、批量启用/禁用/删除；分页每页10
- 开关：启用状态、机构 WEB 启用（即时切换）
- 新建/编辑弹窗：标题、标签、封面(≤10MB)、GIF(≤10MB)、主播多选(按团队)、时间、适当性/VIP/最低要求、观看限制(无/白名单/密码/等级)

### 4.3 团队与研究员
- 团队 CRUD；研究员 CRUD（选团队）
- 直播间主播选择支持"选团队自动全选该团队研究员"

### 4.4 前端展示
- **节目单** `/schedule`：按日期分组卡片、自动刷新60s、状态/简介/徽章
- **直播大厅** `/live`：直播中卡片网格、30s 刷新、观看人数
- **回放中心** `/playback`：搜索、卡片网格、点击走权限验证弹窗
- **观看验证** `/watch/<id>`：骨架屏、房间卡、userid 验证、错误细化（适当性不足/VIP不足/用户不存在/网络异常）、播放器占位、404

### 4.5 观看鉴权（关键，当前实现有缺陷）
- 保利威自定义授权回调：校验 `MD5(secret+id+secret+ts)`，通过后按 `MD5(secret+id+secret+ts+secret+userid)` 回签
- 权限：用户适当性 ≥ 房间最低要求 且 VIP ≥ 最低要求，否则 403
- 优先级：适当性 > VIP

### 4.6 保利威集成
- 创建频道（v4）、回填频道ID/密码/推流/观看地址
- Mock 模式运行，预留真实 API 对接（appId/appSecret/userId/apiBase/customAuthSecret）

## 5. 数据模型（6 张表）
Team / Researcher / Preview / Room / User / room_researchers
核心字段与三层结构见 `需求点清单.md` 第一节，此处不重复。

## 6. 业务规则
- 注入窗口：开播前30min ~ 开播后30min；注入前备份原信息，窗口结束后恢复
- 命中窗口：预告±20min
- 属性流转：板块/品种 预告→直播间→回放 全链路继承
- 状态机：idle/live/ended/pending；未命中=实际开播不在窗口内

## 7. 非功能需求
| 维度 | 要求 |
|---|---|
| 性能 | 列表/前端数据接口 < 300ms；前端自动刷新不卡顿 |
| 安全 | appSecret/customAuthSecret 不得落前端；签名服务端校验；密钥外部化 |
| 合规 | 适当性/VIP 闸门必须在服务端强制（不能只靠前端隐藏） |
| 可用性 | 服务托管为 systemd，崩溃自启；SQLite 单节点可接受 |
| 部署 | 支持本地 + FUJITSM 自托管 + OECT 静态前端 |

## 8. 验收标准（建议）
1. 建预告→绑直播间→开播前自动注入→命中通知→结束自动恢复→回放生成，全链路跑通
2. **服务端**按观众真实身份做适当性/VIP 校验，低等级用户被 403（P0 修复后）
3. 创建频道后推流/观看地址正确回填（basic/get 补漏后）
4. 密钥全部外部化，源码不含明文
5. CORS 白名单覆盖实际前端域名

## 9. 优先级建议（迁移时参考）
- **P0**：鉴权重做（真实观众身份 + 频道绑定 custom 回调）、回放授权
- **P1**：basic/get 补漏、密钥外部化、枚举统一、CORS 对齐
- **P2**：真实用户体系、前端独立静态化部署、互动运营功能