# 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 启动步骤

```bash
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）：

```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 四期新接口试用示例

```bash
# 先用 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 等需外部环境/流程的事项，已在上文逐项标注。