selfrelease
158 lines
6.6 KiB
Markdown
158 lines
6.6 KiB
Markdown
# 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 + 二期 + 三期（代码部分）已完成并通过回归测试，可用于演示、试点联调与功能验收。
|