MAcode/3-task-IPTV-二期.md

# TCS-IPTV 开发任务文档（二期：贯通）

> 版本：V1.0
> 上游文档：0-req-IPTV.md（需求）、1-prd-IPTV.md（PRD）、2-task-IPTV.md（一期/MVP）
> 文档编号：3-task-IPTV-二期
> 周期：6 个月（M7-M12）
> 主题：多省多运营商、扩品类、强化权益（分账/追责/确权/追更/授权核验）+ MVP 遗留生产化

---

## 一、二期范围与功能映射

| 功能编号 | 功能 | 对应需求 | 本期 |
|---------|------|---------|:----:|
| F08 | 终端播放哈希抽检 | 需求8 | ✅ |
| F09 | 统一维度数据上报与聚合 | 需求9 | ✅ |
| F13 | 跨省复用快速准入 | 需求13 | ✅ |
| F18 | 可信播放数据聚合与分账结算依据 | 需求21 | ✅ |
| F19 | 全链路责任界定与追责取证 | 需求22 | ✅ |
| F20 | 版权确权与维权举证 | 需求23 | ✅ |
| F21 | 追更与增量哈希更新 | 需求24 | ✅ |
| F22 | 授权链上链与发布前授权核验 | 需求25 | ✅ |
| — | MVP 遗留生产化（真实链/数据落库/BFF/CI） | — | ✅ |

---

## 二、二期技术栈增量

| 层 | 增量选型 | 说明 |
|----|---------|------|
| 联盟链 | 长安链 ChainMaker 2.x 测试网（三组织节点）| 替换 MVP 的 MemoryChain，落地真实合约 |
| 合约 | tcs_registry（Go 合约）正式部署 | issueMA/registerMapping/verifyHash/revoke 等 |
| 数据回传 | Kafka（可选）/ 批量 REST | 海量播放数据回传与聚合 |
| 分析 | ClickHouse / PostgreSQL 聚合表 | 以 MA 码为维度的播放/分账聚合 |
| 终端 | 播放器 SDK（C/Go/JS）| 片段哈希抽检 |
| 监管大屏 | 控制台 BFF（Go）+ 会话令牌 | 密钥不下发浏览器（替换演示态直连）|
| CI/CD | GitLab CI + 镜像扫描 | 自动构建测试发布 |

---

## 三、任务分解

> 进度图例：`[ ]` 未开始 · `[~]` 进行中 · `[x]` 已完成

### 工作包 A：真实联盟链落地（MVP 遗留）

- [ ] **A.1 ChainMaker 测试网搭建**
  - 目标：三组织（监管/审核监管/运营商）节点组网，国密 SM2/SM3
  - 对应：需求16、需求20
  - 验收：节点正常出块；证书与权限配置就绪
  - 依赖：一期

- [ ] **A.2 tcs_registry 合约落地**
  - 目标：按 contracts/tcs_registry 规格实现并部署 Go 合约
  - 对应：需求16-AC2、需求3、需求14
  - 验收：issueMA/registerMapping/verifyHash/revoke/revokeEpisode 全部链上可调用，规则与 MemoryChain 一致
  - 依赖：A.1

- [ ] **A.3 chain-svc 切换真实链**
  - 目标：chain.Client 增加 ChainMaker 实现，配置切换 MemoryChain↔真实链
  - 对应：需求16
  - 验收：一期全部用例在真实链通过；异步上链与区块确认机制生效
  - 依赖：A.2

- [ ] **A.4 链上数据 PostgreSQL 镜像**
  - 目标：content/hash/mapping/version 落 PG 镜像表，支撑高效查询
  - 对应：需求16-AC1
  - 验收：链为权威源，PG 为查询镜像，最终一致；监管查询走 PG
  - 依赖：A.3

### 工作包 B：监管大屏生产化（MVP 遗留）

- [ ] **B.1 控制台 BFF**
  - 目标：新增 Go BFF，持有凭证，浏览器仅用会话令牌
  - 对应：需求20、需求14
  - 验收：密钥不出现在前端；登录态 + RBAC；审计登录操作
  - 依赖：一期

- [ ] **B.2 前端改造对接 BFF**
  - 目标：web-console 去掉前端 HMAC 直连，改走 BFF 会话
  - 对应：需求20
  - 验收：演示态安全告警移除；功能不回退
  - 依赖：B.1

### 工作包 C：终端播放哈希抽检（F08）

- [ ] **C.1 播放器抽检 SDK**
  - 目标：终端下载片段后计算哈希，与链上比对
  - 对应：需求8-AC1、AC4
  - 验收：多集按集增量校验；提供 C/Go/JS 绑定
  - 依赖：A.3

- [ ] **C.2 异常断流与上报**
  - 目标：抽检不匹配断流、切备用源、上报异常日志
  - 对应：需求8-AC2、需求15-AC3
  - 验收：篡改片段被识别并切源；日志可查
  - 依赖：C.1

- [ ] **C.3 策略开关**
  - 目标：按网络负载策略性开启/关闭抽检
  - 对应：需求8-AC3
  - 验收：可配置开关；高负载自动降级
  - 依赖：C.1

### 工作包 D：数据回传与统一聚合（F09）

- [x] **D.1 播放数据回传接口**
  - 目标：运营商以 MA 码为维度批量回传播放/消费事件
  - 对应：需求9-AC1
  - 验收：批量接收+校验；未知/已下架 MA 码被拒
  - ✅ 完成：`POST /data/playback` + service.ReportPlayback（链上状态门禁），端到端验证

- [x] **D.2 MA 码维度聚合**
  - 目标：CP 播放量/审核量/运营商分发量按 MA 码统一聚合
  - 对应：需求9-AC2、AC3
  - 验收：三方口径一致；提供统一数据视图
  - ✅ 完成：`internal/playback` Store.Summary + `GET /data/playback-summary`

### 工作包 E：可信播放数据与分账结算（F18 / 需求21）

- [x] **E.1 链上可信播放数据**
  - 目标：以 MA 码聚合的播放数据作为可信依据
  - 对应：需求21-AC1、AC2
  - 验收：CP 与运营商所见口径一致
  - ✅ 完成：playback.Summary，data_source 标注"链上可信播放数据"

- [x] **E.2 分账结算依据**
  - 目标：以可信播放数据作为统一结算依据
  - 对应：需求21-AC3、AC4、AC5
  - 验收：分账精确无丢分（服务费取余兜底）；可查询
  - ✅ 完成：playback.ComputeSettlement（CP60/平台34/服务费6）+ `POST /settlement/compute`，8项测试通过

### 工作包 F：责任界定与追责取证（F19 / 需求22）

- [x] **F.1 全链路存证查询**
  - 目标：按 MA 码调取各节点哈希存证（送审/审核/转码/媒资/注入）
  - 对应：需求22-AC1、AC3
  - 验收：各节点带时间戳、操作方
  - ✅ 完成：`internal/provenance` Store + 各环节埋点 + `GET /content/provenance`

- [x] **F.2 责任定位与取证报告**
  - 目标：比对各节点哈希，定位首次变化节点与责任方
  - 对应：需求22-AC2、AC4
  - 验收：能精确定位问题环节；转码版不误判
  - ✅ 完成：`Accountability` + `GET /content/accountability`，定位到 cdn_inject 节点；4项测试

### 工作包 G：版权确权与维权举证（F20 / 需求23）

- [x] **G.1 确权证据链**
  - 目标：MA 码+哈希+上链时间戳形成不可抵赖确权证据
  - 对应：需求23-AC1、AC2、AC4
  - 验收：可导出含『谁先锁定谁有权』声明的证据链
  - ✅ 完成：`CopyrightEvidence` + `GET /content/evidence`

- [x] **G.2 感知哈希侵权比对**
  - 目标：感知哈希相似度比对，标记疑似侵权并关联原 MA 码
  - 对应：需求23-AC3
  - 验收：相同/相似感知哈希命中并分级（high/medium）
  - ✅ 完成：`MatchInfringement`（HammingDistance）+ `POST /content/infringe-match`

### 工作包 H：追更与增量哈希更新（F21 / 需求24）

- [ ] **H.1 增量哈希更新**
  - 目标：仅对变化集/片段重算哈希，Merkle 仅更新变化叶子
  - 对应：需求24-AC1、AC2、AC3
  - 验收：未变化部分复用原审核结论
  - 依赖：A.4

- [ ] **H.2 追更快速赋码**
  - 目标：新增集快速赋码，不触发存量重审
  - 对应：需求24-AC4
  - 验收：追更秒级完成赋码与发布
  - 依赖：H.1

### 工作包 I：授权链与发布前核验（F22 / 需求25）

- [ ] **I.1 授权信息上链**
  - 目标：信息网络传播权（地域/期限/平台）上链存证
  - 对应：需求25-AC1
  - 验收：授权范围可查；变更可追溯
  - 依赖：A.4

- [ ] **I.2 发布/注入前授权核验**
  - 目标：发布与 CDN 注入前核验授权范围，越权拦截
  - 对应：需求25-AC2、AC3、AC4
  - 验收：超地域/过期/非授权平台分发被拦截
  - 依赖：I.1

### 工作包 J：跨省复用快速准入（F13 / 需求13）

- [ ] **J.1 跨省凭证准入**
  - 目标：B 省凭 MA 码+哈希证书准入，不重传内容文件
  - 对应：需求13-AC1、AC2
  - 验收：三重校验（MA有效+哈希一致+非黑名单）通过
  - 依赖：A.4

- [ ] **J.2 简化抽检与映射注册**
  - 目标：B 省审核简化为合规抽检，生成本省流水号+映射
  - 对应：需求13-AC3、AC4
  - 验收：复用周期 15-30天 → 3-5天
  - 依赖：J.1

### 工作包 K：平台接入扩展与 CI/CD

- [ ] **K.1 CI/CD 流水线**
  - 目标：GitLab CI 自动构建/测试/镜像扫描/发布
  - 对应：全局
  - 验收：提交触发；测试不过阻断
  - 依赖：一期

- [ ] **K.2 多省多运营商接入**
  - 目标：扩展至 3-5 省，接入主流 CP 10 家以上
  - 对应：PRD 二期目标
  - 验收：平台接入≥15家；网络剧/网络电影品类覆盖
  - 依赖：A.3

---

## 四、二期里程碑

- [ ] M6：真实 ChainMaker 落地 + 监管大屏 BFF 化（工作包 A、B）
- [ ] M7：数据回传聚合 + 可信分账（工作包 D、E）
- [ ] M8：追责取证 + 确权举证 + 授权核验（工作包 F、G、I）
- [ ] M9：追更 + 跨省复用 + 终端抽检（工作包 C、H、J）
- [ ] M10：多省多运营商接入 + CI/CD（工作包 K）；二期验收

---

## 五、二期验收标准

- 真实联盟链替换 MemoryChain，一期全部用例在链上通过
- 监管大屏密钥不下发浏览器（BFF 会话）
- 分账对账差异 <5%；追责可定位到环节；确权证据可导出
- 跨省复用周期 3-5 天；追更秒级；授权越权可拦截
- 平台接入 ≥15 家；月赋码量 ≥5 万部；月度盈亏平衡