docs: 项目交付说明(DELIVERY.md) + 三期任务文档归档

- 全相位回归测试通过(83用例/核心覆盖率85-100%) - 交付说明: 概述/技术栈/功能/结构/启动/质量/待环境事项/安全
2026-06-14 18:02:22 +08:00
parent 39fd428beb
commit 959e5ac18e
1 changed files with 157 additions and 0 deletions
@@ -0,0 +1,157 @@
+# 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 + 二期 + 三期（代码部分）已完成并通过回归测试，可用于演示、试点联调与功能验收。