# 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 在 **内容提供商（CP）、审核和监管部门、运营商** 三方现有系统之上，建立一层"**可信身份映射层**"：
以 **MA 码（监管身份）+ 哈希码（技术指纹）** 双锚定，实现 IPTV 内容"**审过即锁定，锁定即通行，通行可追溯**"。

核心设计：
- **一剧一码 + 集级哈希**：MA 码按"剧/备案"颁发（对齐网标证），各集独立哈希挂同一码下，支持集级寻址/验真/下架
- **不替代现有系统**：原片走审核方既有渠道做内容审核，TCS 只处理哈希上链与映射（最小侵入）
- **模式 B 自行发码**：与发码机构对接获取号段，按备案规则原子发码

---

## 二、技术栈

| 层 | 选型 |
|----|------|
| 后端/链交互/哈希SDK | Go 1.23 + Gin |
| 智能合约 | Go（ChainMaker 链原生，国密 SM2/SM3/SM4） |
| 联盟链 | 长安链 ChainMaker 2.x（MVP/二期用 MemoryChain 等价实现，接口就绪） |
| 数据库/缓存 | PostgreSQL 16 / Redis 7.x |
| 监管大屏 | React 18 + Ant Design 5 |
| 控制台安全 | BFF + 会话令牌（密钥不下发浏览器） |
| 鉴权 | API Key + HMAC-SHA256 |
| CI/CD | GitLab CI |

---

## 三、已交付功能（按相位）

### 一期 MVP（核心闭环）
送审 → CSPS审核 → 发码签发 → 媒资库入库 → 发布 → CDN注入校验 → 应急下架
- 哈希SDK（文件SHA-256 / 分段Merkle / 感知哈希）
- MA码生成（六段式，号段原子分配，PostgreSQL 行锁防重号）
- 可信数据空间（合约规则：1:1强绑定不可解绑、防换壳重发、权限控制）
- 一剧一码 + 集级哈希 + 集级下架/恢复
- HTTP API + HMAC 三角色权限 + 监管大屏（角色工作台/全流程演示/监管片库）

### 二期 贯通（权益场景）
- **利益**：数据回传聚合（F09）+ 可信播放数据 + 自动分账（F18，CP60/平台34/服务费6）
- **权利**：全链路追责取证（F19，定位偷换环节）+ 确权证据链（F20）+ 感知哈希侵权比对
- **效率**：追更增量赋码（F21）+ 跨省复用三重校验快速准入（F13）
- **合规**：授权链登记 + 发布/注入前授权核验（F22，地域/平台/期限拦截）
- **终端**：片段抽检与断流提示（F08）
- 前端可视化：监管片库"权益与治理"标签（分账/追责/确权/授权）
- CI/CD：GitLab CI 流水线

### 三期 生态（代码可交付部分）
- 备案对接（A.1）：网标号/备案号关联 MA 码
- 监管上报（A.2）：监管数据日报
- 号段管理（B.1）：多机构号段列表与容量
- 全国统计（C/F.2）：按省/类目/状态聚合 + 全国监管大屏
- **监管大屏 BFF 安全化（B）**：密钥仅存后端，浏览器只用会话令牌
- 真实链合约源码（G）：`contracts/tcs_registry/registry.go`（ChainMaker Go）

---

## 四、工程结构

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

---

## 五、快速启动

> 依赖：本地 PostgreSQL（库 tcs_iptv）+ Redis，Go 1.23，Node 20+

```bash
cd tcs-iptv

# 1. 数据库迁移
make migrate

# 2. 启动后端
make run-api          # api-svc :8080
go run ./cmd/console-bff   # BFF :8090（可选）

# 3. 启动前端
cd web-console && npm install && npm run dev   # :5173/5174

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

# 5. 全相位冒烟
bash scripts/e2e_smoke.sh
```

监管大屏：http://localhost:5174 （角色工作台 / 全流程演示 / 监管片库）

---

## 六、质量状况

| 指标 | 状况 |
|------|------|
| 测试用例 | 83 个，全部通过 |
| 核心覆盖率 | playback 100% / hash 88% / service 85% / macode 75% |
| go vet / build | 通过 |
| 前端构建 | 通过 |
| 端到端冒烟 | 一期→三期全相位通过 |

---

## 七、待外部环境/流程的事项（非代码可完成）

| 项 | 说明 | 就绪度 |
|----|------|--------|
| 真实 ChainMaker 测试网 | 需多节点国密链环境 | 合约源码 + chain.Client 接口已就绪，平滑替换 MemoryChain |
| 链上数据 PG 镜像接入 | 需真实链 | 镜像表已建（migrations） |
| 性能压测 / 高可用灾备 | 需集群+压测工具+多节点 | 架构支持，待环境 |
| 等保三级正式测评 | 需第三方测评机构+正式环境 | 安全设计就绪（BFF/HMAC/国密/审计） |
| HSM 密钥托管 | 需硬件 | 接口预留 |
| 行业分账标准发布 | 政策/行业协作 | 分账引擎已实现 |
| 多省/平台实际接入 | 商务运营推进 | 多机构号段+跨省准入+授权核验能力就绪 |
| 四期 大小屏融合（OTT/APP） | 需端侧 SDK 集成环境 | 待启动 |

---

## 八、安全说明

- ✅ 已实现：HMAC-SHA256 鉴权、三角色权限矩阵、MA码1:1不可解绑、哈希本地计算不上链原片、关键操作存证、**监管大屏 BFF 化（密钥不下发浏览器）**
- ⚠️ 上生产前：真实链替换、等保三级测评、HSM 托管、生产凭证接 Vault/SSO

---

> 本系统 MVP + 二期 + 三期（代码部分）已完成并通过回归测试，可用于演示、试点联调与功能验收。