Files
MAcode/2-task-IPTV-MVP.md
selfrelease a329d4906b init: AIGC-Hub/AVCC 方案文档 + TCS-IPTV 内容可信锁定系统 MVP
- 方案文档: AVCC 体系建设、IPTV TCS 需求(0-req)/PRD(1-prd)/任务(2-task)/二三四期任务
- tcs-iptv: Go 后端(哈希SDK/MA码生成/可信数据空间mock/业务编排/HTTP API+HMAC鉴权)
- web-console: React+AntD 监管大屏(角色工作台/全流程演示/监管片库)
- 一剧一码+集级哈希, 集级下架/恢复, 全栈测试通过
2026-06-14 16:50:31 +08:00

23 KiB
Raw Permalink Blame History

TCS-IPTV 内容可信锁定系统 — 开发任务文档(MVP / 一期)

版本:V1.0 编制日期:2026年6月 上游文档:0-req-IPTV.md(需求)、1-prd-IPTV.mdPRD 文档编号:2-task-IPTV 本期范围:MVP(一期) — 单省单运营商微短剧全流程 目标闭环:送审 → 赋码 → 审核 → 入库 → 发布 → 注入 → 下架


一、MVP 范围与功能映射

功能编号 功能 对应需求 本期
F01 母版多维哈希生成SDK 需求1
F02 送审申报与哈希上链 需求2
F03 MA码签发与1:1强绑定 需求3
F04 送审文件验真 需求4
F05 CSPS审核对接与转码版哈希绑定 需求5
F06 媒体资源库入库/发布与编码映射 需求6
F07 CDN注入校验 需求7
F10 全生命周期监管大屏查询 需求10
F11 违规应急下架 需求11
F12 版本变更与重审触发 需求12
F14 角色权限控制(三角色矩阵) 需求14
F15 异常处理规则 需求15
F16 可信数据空间存证与智能合约 需求16
F17 标准化开放API 需求17
安全与可信基线(哈希本地计算/链上存证/鉴权) 需求20
F08/F09/F13/F18-F22 终端抽检/数据聚合/跨省/权益场景 二期

二、技术栈(已确认)

选型 说明
联盟链 长安链 ChainMaker 2.x(国密 SM2/SM3/SM4 可信数据空间底层,合规优先
智能合约 GoChainMaker 链原生合约) issueMA / registerMapping / verifyHash 等
后端服务 Go 1.22 + Gin 验真、签发编排、映射、媒资对接、下架、监管查询等全部业务服务
链交互 Go + ChainMaker Go SDK chain-svc,屏蔽底链细节,提供 REST/gRPC;与合约同语言无跨语言摩擦
哈希SDK Go 核心库 + HTTP API 对外 文件SHA-256 / 分段Merkle / 感知哈希
关系数据库 PostgreSQL 16 业务元数据、映射缓存、内容主表镜像
数据访问 GORM / sqlc DB 访问与迁移
缓存 Redis 7.x 验真结果缓存、限流、会话
API网关 Kong / APISIX 鉴权、限流、日志
监管大屏前端 React 18 + Ant Design 5 + ECharts 全链路查询、应急下架操作台
鉴权 API Key + HMAC-SHA256 / Bearer Token 三方接入鉴权
构建 Go Modules + Makefile
测试 Go testing + testify + Testcontainers-go 单元/集成测试
部署 Docker + Kubernetes(试点可单集群) 静态二进制,镜像小
CI/CD GitLab CI 自动构建测试

待确认项:① 哈希SDK 是否需要向 CP 提供非 Go(如 Python)绑定(MVP 暂定 Go 库 + HTTP API 供外部);② CSPS 与媒体资源库的实际对接接口规范(需对接方提供)。

说明:合约本体与全部应用层后端服务统一采用 Go,与 ChainMaker 链原生同语言,链交互最顺、部署最轻;监管大屏前端采用 React。二期若业务编排显著变重(分账结算/复杂对账/报表),可再评估引入 JVM 业务中台。


三、任务分解(按工作包)

进度图例:[ ] 未开始 · [~] 进行中 · [x] 已完成 每个任务标注:目标 / 对应 / 验收 / 依赖

工作包 0:项目脚手架与基础设施

  • T0.1 代码仓库与工程骨架

    • 目标:建立 monorepochain-svc / api-svc / hash-sdk / web-console)与基础工程结构
    • 对应:全局
    • 验收:各模块可独立构建;统一 lint/格式化;README 说明
    • 依赖:无
    • 完成:tcs-iptv/ monorepo 建立,cmd/{api-svc,chain-svc,hash-api} + internal/{config,httpx} + contracts + deploy + Makefile + READMEgo build ./... 通过
  • T0.2 联盟链测试网部署

    • 目标:搭建 ChainMaker(或 Fabric)测试网,含监管/审核监管/运营商三组织节点
    • 对应:需求16
    • 验收:三组织节点正常出块;可部署/调用合约;提供连接配置
    • 依赖:T0.1、技术栈确认
    • 待办:MVP 阶段先用 chain mockinternal/chain)解耦开发,真实 ChainMaker 测试网并行搭建
  • T0.3 数据库与中间件部署

    • 目标:部署 PostgreSQL、Redis,建立基础 schema 迁移工具
    • 对应:需求16
    • 验收:迁移脚本可执行;连接池配置;本地/测试环境可用
    • 依赖:T0.1
    • 完成:本地 PostgreSQL(库 tcs_iptv+ Redis 就绪;0001_init.sql 建 5 张镜像表(content_registry/hash_binding/identity_mapping/version_history/chain_tx),make migrate 通过
  • T0.4 API 网关与鉴权基线

    • 目标:接入 Kong/APISIX,实现 API Key + HMAC-SHA256 鉴权与限流
    • 对应:需求17、需求20
    • 验收:未签名/错误签名请求被拒;限流生效;调用日志记录
    • 依赖:T0.1
    • 待办:MVP 先在 api-svc 内实现 HMAC 鉴权中间件,网关接入二期
  • T0.5 CI/CD 流水线

    • 目标:GitLab CI 自动构建、单元测试、镜像打包
    • 对应:全局
    • 验收:提交触发流水线;测试不过则阻断合并
    • 依赖:T0.1
    • 待办

工作包 1:可信数据空间与智能合约(F16)

MVP 策略:业务规则在 internal/chain.MemoryChain 完整实现并测试通过(无需真实链即可开发); 真实合约规格见 contracts/tcs_registry/README.md,二期搭 ChainMaker 测试网后落地替换。

  • T1.1 核心数据结构与合约骨架

    • 目标:定义内容主表、哈希绑定表、三方编码映射表、版本变更表四类结构
    • 对应:需求16-AC1
    • 验收:结构可读写;单元测试覆盖
    • 完成:internal/model 四类模型 + internal/chain.Client 接口 + MemoryChain 实现 + 合约规格文档
  • T1.2 issueMA(签发+强绑定)

    • 对应:需求3、需求16-AC2、需求20-AC1
    • 验收:仅监管节点可调用;重复签发被拒;绑定不可覆盖;防重复哈希
    • 完成:MemoryChain.IssueMA,测试覆盖权限/重复/换壳
  • T1.3 registerMapping(三方编码映射)

    • 对应:需求16-AC3
    • 验收:MA 未签发时拒绝;映射可查
    • 完成:RegisterMapping,测试覆盖
  • T1.4 verifyHash(哈希校验)

    • 对应:需求16、需求4
    • 验收:匹配/不匹配返回正确(含转码版)
    • 完成:VerifyHash,测试覆盖匹配/不匹配/未知MA
  • T1.5 Merkle Tree 分段存证与按集定位

    • 对应:需求16-AC4、需求12-AC3
    • 验收:可按集校验;篡改单集能定位到具体集
    • 完成:internal/hash BuildMerkleTree + LocateChangedLeaves,测试覆盖
  • T1.6 链上存证审计与不可篡改校验

    • 对应:需求16-AC5、需求20-AC3
    • 验收:操作留痕;不可覆盖
    • 完成:txID 留痕 + 1:1 不可解绑规则;真实链不可篡改性由 ChainMaker 保证(规格已记录)

工作包 2:链交互服务(chain-svc)

  • T2.1 链交互封装层

    • 目标:封装合约调用(签发/映射/验真/查询),提供内部 REST/gRPC
    • 对应:需求16、需求17
    • 验收:业务服务无需感知底链细节;异常重试;测试覆盖
    • 依赖:T1.2-T1.6
  • T2.2 异步上链与确认机制

    • 目标:交易提交后监听区块确认,落库状态 pending→confirmed
    • 对应:需求16
    • 验收:确认回执准确;超时/失败有处理;测试覆盖
    • 依赖:T2.1

工作包 3:哈希计算 SDKF01

  • T3.1 文件哈希与分段 Merkle

    • 对应:需求1-AC1、AC2
    • 验收:大文件分段稳定;Merkle 根可复算一致
    • 完成:internal/hash sha.go + merkle.go,测试覆盖(含已知向量、篡改检测、奇数叶子)
  • T3.2 感知哈希计算

    • 对应:需求1-AC3
    • 验收:同内容感知哈希稳定;可计算汉明距离
    • 完成:aHash/dHash + HammingDistance,测试覆盖
  • T3.3 SDK 封装与本地存证

    • 对应:需求1-AC4、AC5、AC6、需求20-AC2
    • 验收:返回完整哈希值包;不支持/空文件报错;原文件不外传
    • 完成:ComputeFile + HashPackage + Validate,测试覆盖空文件/缺文件/缺字段

工作包 4:CP 送审与哈希上链(F02)

  • T4.1 送审申报接口与节目信息收录

    • 对应:需求2-AC1、AC2、需求17-AC1
    • 验收:合法申报返回流水号;哈希入可信空间
    • 完成:service.SubmitForReview(受理+CTID生成),测试覆盖
  • T4.2 重复哈希识别(防换壳重发)

    • 对应:需求2-AC3、需求15-AC5
    • 验收:重复哈希被拦截并返回原 MA码
    • 完成:HashExists 拦截,测试覆盖
  • T4.3 哈希值包完整性校验

    • 对应:需求2-AC5
    • 验收:缺字段被拒并提示
    • 完成:ErrIncompleteHashPkg,测试覆盖

注:T4.x 当前为 service 层实现,HTTP 接口(api-svc 路由)在工作包后段统一接入。


工作包 5:MA码生成与签发(F03,模式B 自行发码)

  • T5.0 MA码生成服务(号段管理 + 按规则发码)

    • 目标:登记发码机构分配的码段,按内容类目原子发码,保证全局唯一
    • 对应:需求3-AC1~AC4、AC10
    • 验收:顺序唯一、并发不重号、号段耗尽报错、格式校验/解析
    • 完成:internal/macodeGenerator + Segment + MemoryStore + Parse),9项测试通过(含200并发无重号)
  • T5.1 签发编排服务

    • 目标:审核通过后生成 MA码、调用 issueMA 签发并绑定,记录内容主表
    • 对应:需求3-AC2、AC5、AC9
    • 验收:签发成功并绑定;主表信息完整
    • 完成:service.ApproveAndIssue(自动发码+强绑定),测试覆盖
  • T5.2 MA码+哈希证书生成

    • 对应:需求3-AC7
    • 验收:证书含 MA码与哈希,可被验真校验
    • 完成:Certificate 字段,测试覆盖
  • T5.3 未赋码内容准入拦截

    • 对应:需求3-AC8
    • 验收:无证书内容被拦截
    • 待办:在媒资库/分发门禁处统一拦截(并入 T8.2)

工作包 6:送审文件验真(F04

  • T6.1 验真接口(哈希比对)

    • 目标:计算送审文件哈希并与可信空间绑定哈希比对
    • 对应:需求4-AC1、AC2、需求17-AC2
    • 验收:匹配进入审核;返回 valid/bound_hash/submitted_hash/match/version;测试覆盖
    • 依赖:T2.1、T1.4
  • T6.2 不匹配退回与标记

    • 目标:哈希不匹配直接退回并标记"疑似版本替换"
    • 对应:需求4-AC3、需求15-AC1
    • 验收:不匹配被退回并标记;测试覆盖
    • 依赖:T6.1

工作包 7:CSPS 对接与转码版哈希(F05)

  • T7.1 CSPS 审核结论对接适配器

    • 目标:与 CSPS 审核系统对接,关联审核结论至 MA码/哈希,不改造 CSPS
    • 对应:需求5-AC1、AC2
    • 验收:CSPS 结论可关联并查询;对接为外挂式不改 CSPS 流程;测试覆盖(含 Mock CSPS)
    • 依赖:T2.1、对接规范确认
  • T7.2 转码版哈希绑定与父子关系

    • 目标:转码后各版本哈希绑定同一 MA码,建立母版-转码版父子关系
    • 对应:需求5-AC3、AC4、AC5
    • 验收:多转码版共享 MA码独立哈希;父子关系可查;测试覆盖
    • 依赖:T7.1、T1.2

工作包 8:媒体资源库入库/发布与映射(F06)

  • T8.1 媒资库入库与映射建立

    • 目标:审核合格内容入媒资库,建立"媒资编码↔MA码↔文件哈希↔转码版哈希"映射
    • 对应:需求6-AC1、AC2
    • 验收:入库后映射可查;保留媒资自有编码;测试覆盖
    • 依赖:T7.2、T1.3
  • T8.2 可发布状态门禁

    • 目标:未审核通过/未绑定 MA码的内容不得进入可发布状态
    • 对应:需求6-AC3
    • 验收:不合规内容无法发布;测试覆盖
    • 依赖:T8.1
  • T8.3 发布携带证书校验

    • 目标:向运营商发布必须携带 MA码+哈希证书,否则拒绝
    • 对应:需求6-AC4、AC5
    • 验收:缺证书发布被拒;测试覆盖
    • 依赖:T8.1

工作包 9CDN 注入校验(F07

  • T9.1 注入前哈希校验

    • 目标:运营商注入 CDN 前计算哈希并与绑定哈希比对
    • 对应:需求7-AC1、AC2
    • 验收:匹配允许注入并生成分发编码;测试覆盖
    • 依赖:T6.1、T8.3
  • T9.2 不匹配拒绝注入与告警

    • 目标:哈希不匹配拒绝注入、告警审核监管部门、暂停分发
    • 对应:需求7-AC3、需求15-AC2
    • 验收:不匹配被拦截并告警;测试覆盖
    • 依赖:T9.1
  • T9.3 运营商映射注册

    • 目标:注入成功后注册运营商映射(分发编码、CDN端点)
    • 对应:需求7-AC4
    • 验收:映射可查;测试覆盖
    • 依赖:T9.1、T1.3

工作包 10:版本变更与重审(F12

  • T10.1 绑定断裂检测与重审标记

    • 目标:哈希变化判定绑定断裂,记录版本变更,reaudit_required=true
    • 对应:需求12-AC1、AC2、需求15-AC4
    • 验收:变更被检出并记录;重审标记生效;测试覆盖
    • 依赖:T1.5、T6.1
  • T10.2 重审门禁

    • 目标:重审未通过的变更内容不得进入分发
    • 对应:需求12-AC4
    • 验收:未过重审内容被拦截;测试覆盖
    • 依赖:T10.1、T8.2

工作包 11:角色权限控制(F14

  • T11.1 三角色权限矩阵实现
    • 对应:需求14-AC1~AC5
    • 验收:越权操作被拒;签发/下架仅监管主体;测试覆盖各角色
    • 完成:chain 层 role 校验 + httpx HMAC 角色鉴权;TestE2E_PermissionMatrix 覆盖越权403/错误签名401

工作包 12:异常处理规则(F15

  • T12.1 全局异常处理与规则引擎
    • 对应:需求15-AC1~AC5(终端抽检异常 AC3 二期)
    • 验收:各异常分支按规则执行并留日志
    • 完成:service 层 ErrIncompleteHashPkg/ErrDuplicateContent/ErrHashMismatch/ErrNotApproved/ErrNoCertificate;送审退回、注入拒绝、换壳拦截、变更重审均测试覆盖

工作包 13:监管大屏与全链路查询(F10)

  • T13.1 按 MA码全链路状态查询接口

    • 对应:需求10、需求17-AC3
    • 验收:返回三方映射+CDN端点
    • 完成:GET /api/v1/content/mappings,端到端验证
  • T13.2 监管大屏前端

    • 对应:需求10、需求11
    • 验收:可视化查询、验真、应急下架
    • 完成:web-consoleVite+React18+AntD5),MA码查询/三方映射表/哈希验真/一键下架,npm run build 通过;浏览器端 Web Crypto HMAC 签名与后端一致

工作包 14:违规应急下架(F11

  • T14.1 下架指令解析与翻译

    • 目标:单一 MA码指令解析出三方编码+CDN端点,翻译为各方下架动作
    • 对应:需求11-AC1、AC2、需求17-AC3
    • 验收:一码解析出全部映射;翻译正确;测试覆盖
    • 依赖:T8.1、T9.3
  • T14.2 全网秒级同步下架

    • 目标:下架指令秒级同步至媒资库撤除发布+运营商下架;权限限监管主体
    • 对应:需求11-AC3、AC4
    • 验收:秒级同步;非监管主体无法发起;测试覆盖
    • 依赖:T14.1、T11.1
  • T14.3 应急下架操作台(前端)

    • 目标:监管在大屏一键下架并查看执行结果
    • 对应:需求11
    • 验收:操作便捷;执行状态可见;联调通过
    • 依赖:T14.2、T13.2

工作包 15:集成测试与试点验收

  • T15.1 端到端集成测试

    • 对应:MVP 验收标准
    • 验收:全链路自动化测试通过
    • 完成:internal/api/integration_test.go TestE2E_FullLifecycle,覆盖送审→发码→审核→入库→发布→注入→映射→下架
  • T15.2 版本篡改识别专项测试

    • 对应:需求12、需求18-AC4
    • 验收:篡改用例全部被识别定位
    • 完成:TestE2E_TamperRejected(注入篡改拒绝)+ TestE2E_VersionChangeLocatesEpisode(定位到第2集)
  • T15.3 应急下架时效测试

    • 对应:需求11、需求18-AC1
    • 验收:下架端到端耗时达标
    • 完成:TestE2E_TakedownLatency(秒级内,目标分钟级)
  • T15.4 单省单运营商试点联调

    • 对应:MVP 范围
    • 验收:真实环境跑通闭环;问题清单收敛
    • 待办:需真实 CSPS/媒资库/运营商对接环境,列入试点排期

补充:权限矩阵 E2ETestE2E_PermissionMatrix)覆盖 CP 越权发码 403、运营商越权下架 403、错误签名 401。


四、依赖关系总览

T0.* 基础设施
  └─ T1.* 智能合约 ─ T2.* 链交互
        ├─ T3.* 哈希SDK ─ T4.* CP送审 ─ T5.* MA签发 ─ T6.* 验真
        │                                                 ├─ T7.* CSPS+转码 ─ T8.* 媒资库 ─ T9.* CDN注入
        │                                                 └─ T10.* 版本重审
        ├─ T11.* 权限   ├─ T12.* 异常
        └─ T13.* 监管大屏 ─ T14.* 应急下架
                                   └─ T15.* 集成测试与试点验收

关键路径:T0 → T1 → T2 → T3/T4 → T5 → T6 → T7 → T8 → T9 → T14 → T15


五、进度记录(开发中持续更新)

日期 完成任务 备注 变更说明
2026-06-14 T0.1 工程骨架 monorepo 建立,go build ./... 通过 模块路径 github.com/tcs-iptv/tcs
2026-06-14 T0.3 数据库与迁移 本地 PG(tcs_iptv)+Redis5张镜像表 CTID列名改为 content_twin_id(避开PG保留字)
2026-06-14 环境决策 改用本地 PG/Redis,移除 docker-compose T0.2链网测先用mock解耦;T0.4鉴权先在api-svc内实现
2026-06-14 T1.1-T1.6 可信空间与合约 MemoryChain 实现全部合约规则,14项测试通过 真实合约规格见 contracts/tcs_registry/README.md
2026-06-14 T3.1-T3.3 哈希SDK 文件哈希/Merkle/感知哈希/SDK封装,13项测试通过 CTID 概念落地 model.Content
2026-06-14 环境 psql 加入 PATH~/.zshrc),Makefile 简化 go vet/build/test 全绿
2026-06-14 架构决策:MA发码模式B 与发码机构合作拿码段,TCS自行发码 需求3 改写为"生成+签发",新增 T5.0
2026-06-14 T5.0 MA码生成服务 internal/macode:号段管理+原子发码+解析,9项测试(含200并发无重号) 六段式 MA.156.{行业}.{机构}/{类目}/{年份}{序列}
2026-06-14 T4.1-4.3 / T5.1-5.2 业务编排 internal/service:送审→发码签发→验真,8项测试通过 service 层完成,HTTP 路由后段接入
2026-06-14 WP7-10 业务编排 CSPS对接/转码绑定/媒资库入库发布/CDN注入/版本重审/下架,service 层 + 16项测试 distribution.go
2026-06-14 WP4/9/13/14 HTTP接口 + 鉴权 api-svc 11个路由 + HMAC鉴权中间件(T0.4);端到端冒烟10步全绿 scripts/e2e_smoke.sh
2026-06-14 MA码持久化 PostgresStore 号段原子分配(行级UPSERT),200并发零重号;api-svc 优先PG回退内存 migrations/0002,解决重启丢号/多实例重号
2026-06-14 T13.2 监管大屏 web-consoleReact18+AntD5):查询/验真/下架,build通过 Web Crypto HMAC 与后端一致;演示模式安全提示
2026-06-14 M5 集成测试 api 集成测试5项全绿(全闭环/篡改拒绝/篡改定位/权限矩阵/下架时效) 全仓60+测试通过,MVP 代码完成
2026-06-14 集级粒度补齐 一剧一码+集级哈希绑定+集级子标识(MA码#E07)+按集验真;新增 verify-episode/episodes 接口 需求3增AC11-13migration 00033项集级测试通过,端到端验证
2026-06-14 全流程演示前端 web-console 新增"全流程演示"Tab:七步流水线一键执行+双锚定展示+篡改/下架按钮 FlowDemo.jsx,四角色签名
2026-06-14 流程顺序修正 改为"先审核后发码"(CSPS审核前移,发码加审核门禁) 需求3-AC2,全栈+测试+脚本同步
2026-06-14 集级面板 全流程页新增集级面板:各集独立哈希+集级子标识(MA码#E07)+按集验真/模拟篡改 FlowDemo 集级表格
2026-06-14 多角色工作台 RoleDesk:CP/审核监管/运营商 独立工作台+待办队列+全局看板,内容在各方桌面真实流转 新增 reviews/list 队列接口 + StatusIssued 状态
2026-06-14 监管片库 RoleDesk 新增"监管片库"Tab:全片库列表+状态筛选+应急下架+三方映射/集级钻取详情 LibraryDeskcontent.file_hash 透出
2026-06-14 集级下架 子集级精准下架(RevokeEpisode),只下架某集不影响整剧;片库详情按集下架 model.HashBinding.RevokedTestEpisodeTakedown
2026-06-14 恢复上架 整剧/子集 恢复上架(Restore/RestoreEpisode);片库列表与详情可下架↔恢复切换 下架后状态可逆

六、本期里程碑

  • M1:基础设施 + 智能合约就绪(工作包0、1、2)— 链规则用 MemoryChain 等价实现,真实链二期
  • M2:核心链路打通(哈希→送审→签发→验真,工作包3-6)
  • M3:审核入库发布注入闭环(工作包7-9)
  • M4:监管与应急下架(工作包10-14)
  • M5:集成测试通过(工作包15 T15.1-T15.3);单省试点联调 T15.4 待真实对接环境

七、MVP 收尾状态(2026-06-14

已完成(代码 + 测试): 工作包 0/1/3/4/5/7/8/9/10/11/12/13/14/15 测试总览: 全仓 60+ 用例通过;go vet / go build ./... / go test ./... 全绿;前端 npm run build 通过 端到端: API 集成测试 5 项(全闭环/篡改拒绝/篡改定位/权限矩阵/下架时效)+ 脚本冒烟 10 步

遗留待办(上生产前必做,列入二期/试点):

  1. T0.2 真实 ChainMaker 测试网 + 合约部署(替换 MemoryChain
  2. 链上镜像数据落 PostgreSQL(当前 content/mapping 仅在内存链,PG 镜像表已建待接入)
  3. 监管大屏改「控制台 BFF + 会话令牌」,密钥不下发浏览器(当前为演示态)
  4. T0.5 CI/CD 流水线
  5. T15.4 单省单运营商真实联调
  6. 二期权益场景 F18-F22 + 跨省复用 F13 + 终端抽检 F08

本任务文档为 MVP(一期)开发指导。开发过程中将根据实际进度持续更新任务状态([ ][~][x])与进度记录表。二期权益场景(F18-F22)与跨省复用(F13)将在 MVP 验收后单独排期。