MAcode/TCS-IPTV-系统说明文档.md

TCS-IPTV 内容可信锁定系统 — 完整说明文档

版本：V1.0（一期 MVP + 二期贯通 + 三期生态 + 四期大小屏融合·后端可代码部分） 编制日期：2026 年 6 月 运营主体：陕西 IPTV 运营公司（机构节点 MA.156.8531.6101） 配套文档：0-req-IPTV.md（需求）、1-prd-IPTV.md（PRD）、2-task-IPTV-MVP.md / 3-task-IPTV-二期.md / 4-task-IPTV-三期.md / 5-task-IPTV-四期.md（任务）、tcs-iptv/DELIVERY.md（交付说明）

本文面向业务专家、技术评审与试点联调三类读者，覆盖：业务背景与价值、核心原理、业务流程、系统架构、功能完成情况、试用说明、接口清单、质量与安全状况、后续路线。

---

一、项目背景与价值

1.1 要解决的问题

IPTV/网络视听内容在"送审 → 入库 → 分发 → 终端播放"链路中存在长期痛点：

• 审与发脱节：内容审核通过后，缺乏一个贯穿全链路、不可篡改的"身份"，无法保证分发出去的就是审过的那一版（"换壳重发""偷梁换柱"）。
• 多方编码割裂：CP、审核/媒资、运营商各有一套编码，同一内容跨系统对不上号，监管难以"一码贯穿"。
• 维权举证难：版权归属、首次锁定时间缺乏可信凭证，侵权追责成本高。
• 数据与分账不可信：播放数据由各平台自报，结算缺乏可信依据。
• 跨省/跨屏重复审核：同一内容跨省、跨大小屏（IPTV/OTT/手机）重复审核，效率低。

1.2 解决思路与价值

在 内容提供商（CP）、审核和监管部门、运营商 三方现有系统之上，建立一层"可信身份映射层"：

以 MA 码（监管身份锚点）+ 哈希码（技术指纹锚点） 双锚定， 实现内容"审过即锁定，锁定即通行，通行可追溯"。

价值维度	解法
权利（确权维权）	全链路存证 + 确权证据链 + 感知哈希侵权比对，"谁先锁定谁有权"
效率（少跑路）	一次锁定跨省/跨屏复用，三重校验快速准入，追更增量赋码
利益（可信分账）	以 MA 码为维度聚合可信播放数据，自动分账
监管（看得见管得住）	一码贯穿三方映射，一键应急下架，全国统计大屏

---

二、角色与术语

2.1 角色（三方）

角色	链上角色码	现有系统	在 TCS 中的职责
内容提供商 CP	cp	制作/媒资系统	送审节目信息 + 哈希包（不传原片）
审核和监管部门	reviewer（审核/媒资）、regulator（监管发码）	CSPS 审核系统 + 媒体资源库	合规审核、媒资入库、发布；监管发码与应急下架
运营商	operator	BOSS/CDN	注入前哈希校验、播放数据回传

说明：审核与监管部门内部细分两类链上权限 —— reviewer（CSPS/媒资库的审核与入库发布）与 regulator（监管主体，唯一可发码/下架）。

2.2 核心术语

• MA 码：监管身份锚点。六段式结构 MA.156.{行业节点}.{机构节点}/{类目}/{年份}{序列}，例：MA.156.8531.6101/WD/20260000004。
  • 156=国家码（中国）、8531=行业节点（IPTV 视听）、6101=机构节点（陕西）、WD/WJ/DY/DH=微短剧/网络剧/网络电影/网络动画。
• 集级子标识：一剧一码下按集寻址，形如 MA.156.8531.6101/WD/20260000004#E07（第 7 集）。
• 哈希码：技术指纹锚点。文件 SHA-256 / 分段 Merkle 根 / 感知哈希（用于侵权比对）。
• CTID（Content Twin ID）：内容机器主键，链下双锚定主键。
• 可信数据空间：联盟链（长安链 ChainMaker，国密），存哈希与映射、不存原片。
• 模式 B 自行发码：与 MA 发码机构对接获取"号段 + 备案规则"，由 TCS 在本地按规则原子发码。

---

三、核心设计原理

1. 双锚定：MA 码（监管/法律身份）与哈希（技术指纹）在发码时 1:1 强绑定且不可解绑，链上同时记录 CTID。
2. 一剧一码 + 集级哈希：MA 码按"剧/备案"颁发（对齐网标证），各集独立哈希挂在同一码下，支持集级验真、集级下架/恢复。
3. 先审后发：CP 送审 → CSPS 审核通过 → 才发码签发（审过才发证发码），杜绝"先发码后审核"的空子。
4. 不传原片：链上只存哈希，原片仍走审核方既有渠道做内容审核 —— 最小侵入、不替代现有系统。
5. 防换壳重发：同一文件哈希再次送审被直接拦截并关联原 MA 码。
6. 权限分离：仅监管主体可发码与下架；发布必须携带"MA 码 + 哈希证书"。

---

四、业务流程

4.1 内容全生命周期（主流程）

CP 送审            监管发码签发          CSPS 审核 / 媒资        发布给运营商        CDN 注入校验
(不传原片)   ──▶   (审核通过后)    ──▶   入媒资库            ──▶ (携 MA+哈希证书)  ──▶ (注入前哈希比对)
节目信息+哈希包      1:1 强绑定哈希        建媒资编码映射                              匹配→放行 / 不匹配→拒绝告警

详细步骤：

1. CP 送审（cp）：提交标题、集数、类目、文件哈希、Merkle 根、感知哈希、各集哈希；系统校验哈希包完整性 + 防换壳重发，返回送审流水号 REV-… 与 CTID。
2. CSPS 合规审核（reviewer）：审核通过/驳回（原片走既有审核渠道，TCS 记审核结论）。
3. 发码签发（regulator，审过才发）：按类目从号段原子分配 MA 码，与哈希包 1:1 强绑定上链，生成"MA 码 + 哈希证书"。
4. 媒资库入库（reviewer）：建立媒资编码映射，状态 → 已入库。
5. 发布给运营商（reviewer）：校验证书（须含 MA 码）后，状态 → 已发布。
6. CDN 注入校验（operator）：注入前比对哈希；匹配则放行并注册运营商/CDN 映射，不匹配则拒绝并告警；同时做授权核验（地域/平台/期限）。
7. 终端抽检：终端按集抽检片段哈希，不匹配提示断流切备用源。

4.2 治理与权益流程（二期）

• 应急下架：监管主体一键下架，解析出该 MA 码绑定的三方编码与 CDN 端点；支持集级下架（只下某集，整剧其余集继续流通）与恢复上架。
• 版本变更重审：哈希变化判定绑定断裂，触发重审，并可定位被改的具体集。
• 可信分账：运营商以 MA 码为维度回传播放数据 → 聚合 → 按比例分账（示例 CP 60% / 平台 34% / 服务费 6%）。
• 追责取证 / 确权举证：全链路存证定位首次哈希变化环节与责任方；导出确权证据链；感知哈希侵权比对。
• 授权链：登记信息网络传播权（地域/平台/期限），发布与注入前核验。
• 跨省复用：B 省凭"MA 码 + 哈希证书"三重校验（码有效 + 哈希一致 + 非黑名单）快速准入。

4.3 大小屏融合流程（四期）

• 跨域解析网关：同一 MA 码在 IPTV/OTT/APP 统一解析（含集级子标识），返回一致的流通状态与跨屏可用性。
• 扫码验真：用户扫码返回真伪（链上存在且结构合法）+ 合规（仅 published 为合规流通）+ 流通状态，下架码判为"真码但不合规"。
• 跨屏权益通兑：以 MA 码为维度记录购买，任一屏购买即全屏（电视/手机/OTT）通看，重复购买幂等不重复扣费，权益归一到整剧 MA 码。

---

五、系统架构与工程结构

5.1 分层架构

            ┌───────────────── 监管大屏（React + AntD）─────────────────┐
            │  角色工作台 │ 全流程演示 │ 监管片库（权益与治理）          │
            └──────────────────────────┬──────────────────────────────┘
                                        │ 会话令牌（密钥不下发浏览器）
                              ┌─────────┴─────────┐
                              │  console-bff :8090 │（BFF 安全层）
                              └─────────┬─────────┘
                                        │ HMAC-SHA256 鉴权
   ┌────────────────────────── api-svc :8080（业务编排）──────────────────────────┐
   │ service：送审/审核/发码/入库/发布/注入/下架/分账/追责/确权/授权/跨省/解析/权益 │
   │ macode：六段式发码与号段（PG 行锁防重号） │ hash：SHA256/Merkle/感知哈希       │
   └───────────────┬─────────────────────────────────────┬─────────────────────────┘
                   │ chain.Client 接口                     │
        ┌──────────┴──────────┐                  ┌─────────┴─────────┐
        │ MemoryChain（等价实现）│  平滑替换 ──▶   │ ChainMaker 国密链   │（合约源码已就绪）
        └─────────────────────┘                  └───────────────────┘
                   │
        ┌──────────┴──────────┐
        │ PostgreSQL 16 / Redis │（号段游标、链上数据镜像、缓存）
        └─────────────────────┘

5.2 工程结构

tcs-iptv/
├── cmd/
│   ├── api-svc/        # 业务后端（:8080）
│   ├── chain-svc/      # 链交互服务（:8081）
│   ├── hash-api/       # 哈希SDK HTTP API（:8082）
│   └── console-bff/    # 监管控制台 BFF（:8090）
├── internal/
│   ├── hash/           # 哈希核心（SHA256/Merkle/感知哈希）
│   ├── macode/         # MA码生成/解析/号段（含 PG 存储）
│   ├── chain/          # 可信数据空间抽象 + MemoryChain
│   ├── service/        # 业务编排（含 phase4.go 大小屏融合）
│   ├── playback/       # 播放聚合与分账
│   ├── provenance/     # 全链路存证与追责
│   ├── bff/            # 控制台 BFF
│   ├── api/            # HTTP 路由与处理器
│   ├── model/          # 领域模型（含 rights.go 跨屏权益）
│   └── config/ httpx/  # 配置、通用 HTTP / 鉴权
├── contracts/tcs_registry/  # ChainMaker Go 合约（独立模块）
├── deploy/migrations/  # PostgreSQL 迁移（0001-0003）
├── web-console/        # React 监管大屏
├── scripts/            # seed_demo.sh / e2e_smoke.sh
└── .gitlab-ci.yml

---

六、功能完成情况

图例：✅ 已完成（代码可交付，含测试）；⏸ 需外部环境/流程（非本机代码可完成，已诚实标注）。

6.1 一期 MVP（核心闭环）✅

模块	状态	说明
哈希 SDK	✅	文件 SHA-256 / 分段 Merkle / 感知哈希
MA 码生成	✅	六段式、号段原子分配、PostgreSQL 行锁防重号
可信数据空间	✅	1:1 强绑定不可解绑、防换壳重发、权限控制
送审→审核→发码→入库→发布→注入→下架	✅	全闭环
一剧一码 + 集级哈希	✅	集级验真、集级下架/恢复、整剧下架/恢复
HTTP API + HMAC 三角色权限	✅	四角色密钥
监管大屏	✅	角色工作台 / 全流程演示 / 监管片库

6.2 二期 贯通（权益场景）✅

能力	状态	说明
数据回传聚合 + 可信分账	✅	以 MA 码聚合，CP60/平台34/服务费6
全链路追责取证	✅	定位首次哈希变化环节与责任方
确权证据链 + 感知哈希侵权比对	✅	"谁先锁定谁有权"
追更增量赋码	✅	不触发存量重审、不重新发码
跨省复用快速准入	✅	三重校验（码有效+哈希一致+非黑名单）
授权链登记 + 发布/注入前核验	✅	地域/平台/期限拦截
终端片段抽检	✅	不匹配提示断流切源
前端"权益与治理"可视化	✅	分账/追责/确权/授权标签
CI/CD	✅	GitLab CI 流水线

6.3 三期 生态（代码可交付部分）✅ / ⏸

能力	状态	说明
备案对接（网标号/备案号关联）	✅	/content/bind-filing、/content/filing
监管数据日报	✅	/regulatory/daily-report
号段管理	✅	/admin/segments
全国统计（按省/类目/状态）	✅	/regulatory/national-stats
监管大屏 BFF 安全化	✅	密钥仅存后端，浏览器只用会话令牌
真实链合约源码	✅	contracts/tcs_registry/registry.go（ChainMaker Go）
真实链部署 / 等保测评 / 压测 / 行业标准	⏸	需外部环境与流程

6.4 四期 大小屏融合（后端可代码部分）✅ / ⏸

任务	状态	说明
C.1 MA 跨域解析网关	✅	GET /content/resolve
C.2 大小屏身份互通	✅	同一 MA 码跨 iptv/ott/app 一致解析与哈希身份
B.2 扫码验真	✅	POST /content/scan-verify
D.1 跨屏权益通兑	✅	POST /rights/purchase、/rights/verify，任一屏购买全屏通看
A.1/A.2 OTT 端 SDK / 播放器抽检	⏸	复用后端 inject/verify/resolve/terminal 能力；端侧 SDK 待真实终端
B.1 移动端壳接入	⏸	复用统一鉴权与后端校验；RN/小程序待移动端环境
E.1 移动端 C2PA 内容凭证	⏸	依赖 C2PA 类水印 SDK，衔接 AVCC 体系

---

七、试用说明

7.1 环境准备

本地直接使用已安装的 PostgreSQL / Redis，无需 Docker。

• Go 1.23+
• Node 20+（前端）
• PostgreSQL 16（创建库 tcs_iptv，psql 已加入 PATH）
• Redis 7.x

可选环境变量（缺省即适配本地）：

变量	默认值
TCS_POSTGRES_DSN	postgres://postgres@localhost:5432/tcs_iptv?sslmode=disable
TCS_REDIS_ADDR	localhost:6379
TCS_API_ADDR	:8080

7.2 启动步骤

cd tcs-iptv

# 1. 数据库迁移（库 tcs_iptv 需已创建）
make migrate
make db-check        # 列出已建表
make redis-check     # 应返回 PONG

# 2. 运行测试（确认环境就绪）
make test

# 3. 启动后端
make run-api                 # api-svc  :8080
go run ./cmd/console-bff     # BFF      :8090（监管大屏走 BFF，可选）

# 4. 启动前端监管大屏
cd web-console && npm install && npm run dev   # :5173/5174

# 5. 造演示数据（陕西 IPTV 场景）
bash scripts/seed_demo.sh

# 6. 全相位端到端冒烟
bash scripts/e2e_smoke.sh

监管大屏访问：http://localhost:5174（角色工作台 / 全流程演示 / 监管片库）。 seed_demo.sh 会打印生成的 MA 码，可复制到大屏查询全链路三方映射。

7.3 演示场景（陕西 IPTV）

参与方	示例
管理方（审核+监管）	陕西 IPTV 运营公司（机构节点 6101）
内容提供商 CP	西安曲江丝路文化传播 / 陕文投艺达影视 / 西部电影集团（西影）
运营商	中国电信陕西（天翼高清）/ 中国移动陕西（魔百和）/ 中国联通陕西
示例内容	《长安少年行》(微短剧) /《白鹿原·麦客》(网络剧) /《丝路驼铃》(网络电影)

7.4 API 鉴权与调用

所有 /api/v1/** 接口需 HMAC-SHA256 鉴权。

• 签名串：base64( HMAC-SHA256( secret, "{METHOD}\n/api/v1{path不含query}" ) )
• 请求头：Authorization: TCS {apiKey}:{signature}

预置四角色示例密钥（生产从 Vault/DB 加载）：

角色	apiKey	secret
监管主体	ak-regulator	sk-regulator
审核/媒资	ak-reviewer	sk-reviewer
内容提供商	ak-cp	sk-cp
运营商	ak-operator	sk-operator

通用签名/调用函数（bash）：

BASE="http://localhost:8080/api/v1"
sign() { printf '%s\n%s' "$2" "$3" | openssl dgst -sha256 -hmac "$1" -binary | base64; }
call() { # key secret method path body
  local sig; sig=$(sign "$2" "$3" "/api/v1${4%%\?*}")
  if [ "$3" = "GET" ]; then curl -s "$BASE$4" -H "Authorization: TCS $1:$sig";
  else curl -s -X "$3" "$BASE$4" -H "Authorization: TCS $1:$sig" -H "Content-Type: application/json" -d "$5"; fi
}

7.5 四期新接口试用示例

# 先用 seed_demo.sh 生成一个已发布的 MA 码，记为 $MA

# C.1/C.2 跨域解析（GET，跨屏统一解析；支持集级子标识 #E03）
call ak-regulator sk-regulator GET "/content/resolve?ma_code=$MA"
call ak-regulator sk-regulator GET "/content/resolve?ma_code=$MA#E03"

# B.2 扫码验真（返回 authentic 真伪 / compliant 合规）
call ak-operator sk-operator POST /content/scan-verify "{\"ma_code\":\"$MA\"}"

# D.1 跨屏权益：电视端购买
call ak-operator sk-operator POST /rights/purchase \
  "{\"ma_code\":\"$MA\",\"user_hash\":\"user-1\",\"screen\":\"iptv\"}"

# D.1 手机端核验权益 → 通看，不重复付费
call ak-operator sk-operator POST /rights/verify \
  "{\"ma_code\":\"$MA\",\"user_hash\":\"user-1\",\"screen\":\"app\"}"

---

八、接口清单（节选，均在 /api/v1 下）

分类	方法 路径	说明
送审/发码	POST /content/register	CP 送审（哈希包，不传原片）
	POST /content/csps-result	CSPS 合规审核结论
	POST /content/issue	审核通过后发码签发（仅监管）
验真	POST /content/verify	整剧哈希验真
	POST /content/verify-episode	集级验真
分发	POST /content/ingest / publish / inject	入库 / 发布 / CDN 注入校验
治理	POST /content/takedown / takedown-episode	整剧 / 集级应急下架（仅监管）
	POST /content/restore / restore-episode	恢复上架
	GET /content/mappings	三方映射与 CDN 端点查询
权益	POST /data/playback / GET /data/playback-summary	播放回传 / 可信聚合
	POST /settlement/compute	可信分账
追责确权	GET /content/provenance / accountability / evidence	存证 / 追责 / 确权
	POST /content/infringe-match	感知哈希侵权比对
授权/追更/跨省	POST /content/authorize / auth-check / add-episodes / cross-province	—
终端	POST /terminal/verify-segment	终端片段抽检
三期生态	POST /content/bind-filing、GET /content/filing、GET /regulatory/national-stats、GET /regulatory/daily-report、GET /admin/segments	备案/统计/上报/号段
四期大小屏	GET /content/resolve	跨域解析网关
	POST /content/scan-verify	扫码验真
	POST /rights/purchase	记录跨屏购买
	POST /rights/verify	跨屏权益核验

---

九、质量状况

指标	状况
测试用例	100+（含四期 18 个新单测），全部通过
核心覆盖率	playback 100% / hash 88% / service 85% / macode 75%
go build ./... / go vet	通过
前端构建	通过
端到端冒烟	一期 → 四期（后端可代码部分）全相位通过

---

十、待外部环境/流程的事项（诚实标注，非代码可完成）

项	说明	就绪度
真实 ChainMaker 国密测试网	需多节点链环境	合约源码 + chain.Client 接口就绪，平滑替换 MemoryChain
链上数据 PG 镜像接入	需真实链	镜像表已建（migrations）
性能压测 / 高可用灾备	需集群 + 压测工具	架构支持，待环境
等保三级正式测评	需第三方机构 + 正式环境	安全设计就绪（BFF/HMAC/国密/审计）
HSM 密钥托管	需硬件	接口预留
行业分账标准发布	政策/行业协作	分账引擎已实现
OTT / 移动端 SDK 接入	需 Android TV/OTT、RN/小程序真实终端	后端解析/校验/权益能力就绪可复用
移动端 C2PA 内容凭证	需 C2PA 类水印 SDK，衔接 AVCC	待端侧环境

---

十一、安全说明

• ✅ 已实现：HMAC-SHA256 鉴权、三角色权限矩阵、MA 码 1:1 不可解绑、哈希本地计算不上链原片、关键操作存证、监管大屏 BFF 化（密钥不下发浏览器）。
• ⚠️ 上生产前需补齐：真实国密链替换、等保三级测评、HSM 密钥托管、生产凭证接入 Vault/SSO。
• 网络暴露提示：当前示例服务以预置密钥启动，仅用于本机演示/联调；公网部署前必须更换密钥来源并启用 TLS、网关与审计。

---

十二、版本与后续路线

阶段	主题	状态
一期 MVP	内容可信锁定核心闭环	✅ 完成
二期 贯通	权利/效率/利益/合规场景	✅ 完成
三期 生态	备案对接/全国监管/BFF 安全/真实链合约	✅ 代码部分完成；部署待环境
四期 大小屏融合	跨域解析/扫码验真/跨屏权益	✅ 后端完成；端侧 SDK 待环境

四期完成后，TCS-IPTV 从"IPTV 内容可信锁定"升级为"全场景视听内容可信身份基础设施"， 可与 AVCC（AIGC 视听内容编码）体系形成大小屏、传统/AIGC 内容的统一身份底座。

---

本系统一期至四期"可本机代码部分"均已实现并通过回归测试，可用于演示、试点联调与功能验收。 剩余为真实链部署、等保测评、压测、HSM、行业标准、端侧 SDK 等需外部环境/流程的事项，已在上文逐项标注。