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 遗留）

> ⏳ **延后（需基础设施环境）**：真实 ChainMaker 测试网需多节点+国密证书+链运行环境，本地开发环境不具备。
> MVP 的 `internal/chain.MemoryChain` 已实现等价合约语义（含 issueMA/registerMapping/verifyHash/revoke/revokeEpisode/restore），
> 全部二期业务逻辑已在其上开发并测试通过。待具备链环境后，按 `contracts/tcs_registry/README.md` 规格落地 Go 合约，
> 实现 `chain.Client` 的 ChainMaker 版本替换 MemoryChain（接口不变，无需改业务代码）。

- [ ] **A.1 ChainMaker 测试网搭建**（待链环境）
- [ ] **A.2 tcs_registry 合约落地**（待链环境）
- [ ] **A.3 chain-svc 切换真实链**（待链环境，接口已就绪）
- [ ] **A.4 链上数据 PostgreSQL 镜像**（PG 镜像表已建，待接入）

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

> ⏳ **延后（架构改造）**：BFF 化需新增独立后端服务持有凭证 + 会话体系，属较大改造。
> 当前演示态已在前端明确标注安全提示。建议与三期等保三级测评一并落地。

- [ ] **B.1 控制台 BFF**（待改造）
- [ ] **B.2 前端改造对接 BFF**（待改造）

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

- [x] **C.1 终端片段抽检**
  - 对应：需求8-AC1、AC4
  - 验收：按集校验片段哈希
  - ✅ 完成：`TerminalVerifySegment` + `POST /terminal/verify-segment`

- [x] **C.2 异常断流提示**
  - 对应：需求8-AC2、需求15-AC3
  - 验收：不匹配返回断流切源提示
  - ✅ 完成：不匹配返回"断流切备用源"提示，测试覆盖

- [~] **C.3 策略开关**
  - 对应：需求8-AC3
  - 说明：抽检开关属终端 SDK 配置项，随真实播放器 SDK 集成落地（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）

- [x] **H.1 增量哈希更新**
  - 对应：需求24-AC1、AC2、AC3
  - 验收：仅变化集重算，未变化部分复用
  - ✅ 完成：版本变更 Merkle 定位（一期）+ 追更增量绑定

- [x] **H.2 追更快速赋码**
  - 对应：需求24-AC4
  - 验收：新增集快速赋码，不触发存量重审、不重新发码
  - ✅ 完成：`AddEpisodes` + `POST /content/add-episodes`，测试覆盖（2集追更到4集）

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

- [x] **I.1 授权信息上链**
  - 对应：需求25-AC1
  - 验收：授权范围（地域/平台/期限）可登记可查
  - ✅ 完成：`RecordAuthorization` + `POST /content/authorize`

- [x] **I.2 发布/注入前授权核验**
  - 对应：需求25-AC2、AC3、AC4
  - 验收：超地域/过期/非授权平台分发被拦截
  - ✅ 完成：`CheckAuthorization` 嵌入 InjectToCDN + `POST /content/auth-check`，测试覆盖地域/平台/过期三类拦截

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

- [x] **J.1 跨省凭证准入**
  - 对应：需求13-AC1、AC2
  - 验收：三重校验（MA有效+哈希一致+非黑名单）
  - ✅ 完成：`CrossProvinceAdmit`，测试覆盖准入/哈希不符/黑名单/未知MA

- [x] **J.2 简化抽检与映射注册**
  - 对应：需求13-AC3、AC4
  - 验收：生成本省流水号，审核简化为抽检
  - ✅ 完成：准入即生成本省流水号 + `POST /content/cross-province`

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

- [x] **K.1 CI/CD 流水线**
  - 对应：全局
  - 验收：构建/测试/前端构建自动化
  - ✅ 完成：`.gitlab-ci.yml`（backend-build/test+cover、frontend-build）

- [~] **K.2 多省多运营商接入**
  - 对应：PRD 二期目标
  - 说明：技术能力已就绪（多机构号段+跨省准入+授权核验）；实际接入为商务/运营推进事项

---

## 四、二期里程碑

- [~] M6：真实 ChainMaker 落地 + 监管大屏 BFF 化（工作包 A、B）— 延后至有链环境/三期
- [x] M7：数据回传聚合 + 可信分账（工作包 D、E）
- [x] M8：追责取证 + 确权举证 + 授权核验（工作包 F、G、I）
- [x] M9：追更 + 跨省复用 + 终端抽检（工作包 C、H、J）
- [x] M10：CI/CD（工作包 K.1）；二期纯代码功能验收完成

---

## 六、二期完成状态（2026-06-14）

**已完成（代码 + 测试）：** 工作包 C/D/E/F/G/H/I/J/K.1 —— 二期全部纯代码功能
**测试：** 全仓测试全绿（playback/provenance + service 二期用例 30+）；`go vet`/`build`/`test ./...` 通过
**新增能力：**
- 利益：数据回传聚合 + 可信播放数据 + 自动分账（F09/F18）
- 权利：全链路追责取证 + 确权证据链 + 感知哈希侵权比对（F19/F20）
- 效率：追更增量赋码 + 跨省复用三重校验快速准入（F21/F13）
- 合规：授权链登记 + 发布/注入前授权核验（F22）
- 终端：片段抽检与断流提示（F08）
- 工程：GitLab CI/CD（K.1）

**延后（需环境/改造，建议并入三期）：**
- A 真实 ChainMaker 落地（需链环境；MemoryChain 已等价，接口就绪可平滑替换）
- B 监管大屏 BFF 化（需架构改造；建议与三期等保三级一并落地）
- K.2 多省多运营商实际接入（技术能力就绪，属商务/运营推进）

---

## 五、二期验收标准

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