MAcode/方案对照报告.md

# IPTV 系统融合 MA 码方案 — 代码实现对照报告

> 生成日期：2026-06-30
> 对照文档：`IPTV系统融合MA码方案介绍.md`
> 代码仓库：`tcs-iptv/`
> 总体匹配度：**100%**（方案全部要求已实现），部分功能**超出方案要求**

---

## 一、整体系统架构对照

### 1. 业务系统层

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 内容提供商平台负责内容提交和内容管理 | `Service.SubmitForReview` + `POST /content/register` | ✅ 满足 |
| CPSP 系统负责内容受理、加工、审核和发布 | `Service.ReviewCSPS` + `Service.ApproveAndIssue` + `Service.IngestToLibrary` + `Service.PublishToOperator` | ✅ 满足 |
| 运营商平台负责内容接收、运营和分发 | `Service.InjectToCDN` + `Service.ReportPlayback` | ✅ 满足 |
| 内容按原有业务流程流转 | 送审 → CSPS审核 → 发码 → 入库 → 发布 → CDN注入 → 播放回传 | ✅ 满足 |

### 2. 内容资源层

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 片库为现有系统，负责存储实际媒体文件 | 片库为外部系统，代码不替代 | ✅ 满足（不侵入） |
| 目录库负责存储 MA、Hash、片库文件 ID、省内内容编码等映射关系 | `chain.Client` 统一存储 + `identity_mapping` 表 + `hash_binding` 表 | ✅ 满足 |
| 目录库可扩展审核状态、审核机构、审核时间、审核结论等 | `provenance.Store` 存证 + `FilingRecord` 备案关联 + `VersionChange` 版本变更 | ✅ 满足 |
| 目录库可独立部署 | `cmd/catalog-svc/` 独立微服务 + `internal/catalog` 包 + `CatalogStore` 可替换接口 | ✅ 满足 + 超出（方案仅提及"可独立部署"，已实现完整独立服务） |

### 3. 标识服务层

#### （1）标识服务模块

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| MA 生成 | `macode.Generator.Allocate()` 按类目从号段原子分配 | ✅ 满足 |
| Hash 登记 | `chain.IssueMA` 强绑定 + `chain.RegisterHashBinding` 追加绑定 | ✅ 满足 |
| 标识查询 — 根据 MA 查询 | `GET /content/mappings` + `GET /catalog/query-by-ma` | ✅ 满足 |
| 标识查询 — 根据 Hash 查询 | `GET /content/query-by-hash` + `GET /catalog/query-by-hash` | ✅ 满足 |
| 标识查询 — 根据省级内容编码查询 | `GET /content/query-by-provincial-code` + `GET /catalog/query-by-provincial-code` | ✅ 满足 |
| 标识查询 — 根据片库文件 ID 查询 | `GET /content/query-by-library-id` + `GET /catalog/query-by-library-id` | ✅ 满足 |
| 标识映射管理 | `chain.RegisterMapping`（CP/Reviewer/Operator 三方编码 + CDN 端点） | ✅ 满足 |
| 标识同步 | `internal/sync` 包 + `SyncService`（全量/增量同步 + 冲突检测 + 三种冲突策略） | ✅ 满足 + 超出（方案仅提及"标识同步"，已实现冲突解决策略） |
| 建立 MA 与 Hash 的映射关系 | `IssueMA` 1:1 强绑定 + `hash_binding` 表 | ✅ 满足 |
| 建立 MA 与片库文件 ID 的映射关系 | `RegisterMapping(PartyReviewer, mediaAssetID)` | ✅ 满足 |
| 建立 MA 与省级内容编码的映射关系 | `RegisterMapping(PartyCP, cpMediaID)` | ✅ 满足 |
| 将相关信息写入目录库 | `chain.Client` 统一写入 + `PersistentChain` PG 持久化 | ✅ 满足 |

#### （2）验真服务模块

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 判断内容是否已存在 | `chain.HashExists()` 防换壳重发 | ✅ 满足 |
| 判断是否已生成 MA | `chain.QueryContent()` 返回状态 | ✅ 满足 |
| 查询对应内容信息 | `chain.QueryContent` / `QueryByHash` / `QueryByProvincialCode` / `QueryByLibraryFileID` | ✅ 满足 |
| 查询是否存在历史记录 | `provenance.Store.Trail()` 全链路存证 | ✅ 满足 |
| 为审核人员提供辅助判断依据 | `Service.ScanVerify` 扫码验真 + `Service.Resolve` 跨域解析 | ✅ 满足 |
| 内容识别接口 | `GET /content/resolve` 跨域解析网关 | ✅ 满足 + 超出（方案未提及跨域解析，已实现大小屏融合） |
| Hash 匹配接口 | `POST /content/verify` + `POST /content/verify-episode` | ✅ 满足 |
| MA 查询接口 | `GET /content/mappings` | ✅ 满足 |
| 审核记录查询接口 | `GET /content/provenance` 全链路存证 | ✅ 满足 |

#### （3）MA 管理模块

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| MA 创建 | `Service.ApproveAndIssue` → `chain.IssueMA`（审过才发码） | ✅ 满足 |
| MA 维护 | `SetContentStatus` / `RegisterHashBinding` / `RegisterMapping` / `AddEpisodes` 追更 | ✅ 满足 |
| MA 合并 | `chain.MergeMA` + `POST /content/merge`（哈希绑定和映射迁移） | ✅ 满足 |
| MA 拆分 | `chain.SplitMA` + `POST /content/split`（按集号拆分） | ✅ 满足 |
| MA 失效 | `chain.Revoke` 下架 + `StatusRevoked` | ✅ 满足 |
| 状态管理 | `SetContentStatus` + 10 种状态常量（pending → approved → issued → in_library → published → revoked → merged → split 等） | ✅ 满足 |
| 一致性校验 | `provenance.Store.Accountability` 哈希一致性检查 + 责任界定 | ✅ 满足 |
| 合并/拆分后映射关系迁移与一致性校验 | `MergeMA`/`SplitMA` 中迁移 bindings 和 mappings + 哈希索引更新 | ✅ 满足 |
| 保证 MA 编码的唯一性、稳定性和可管理性 | `IssueMA` 不可重复签发 + `hashIndex` 唯一索引 + 号段原子分配 | ✅ 满足 |

#### （4）系统管理模块

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 用户管理 | `AdminService` 用户 CRUD + API Key 生成/重置/禁用 + `admin_handlers.go` 6 个 API | ✅ 满足 |
| 组织管理 | `AdminService` 组织 CRUD + 号段关联 + `admin_handlers.go` 5 个 API | ✅ 满足 |
| 权限管理 | `httpx.AuthMiddleware` HMAC-SHA256 签名鉴权 + `RBACManager` 动态权限矩阵 | ✅ 满足 + 超出（方案仅提及"权限管理"，已实现可配置 RBAC 权限矩阵 + 40+ 权限常量 + 动态增删） |
| 配置管理 | `config.Load()` 环境变量加载 + 多后端切换（memory/pg/chainmaker） | ✅ 满足 |
| 日志管理 | `provenance.Store` 全链路存证（不可篡改时间序事件） | ✅ 满足 + 超出（方案仅提及"日志管理"，已实现全链路存证 + 责任界定取证 + 版权确权证据链） |
| 运行监控 | `internal/monitor` Prometheus 4 金指标 + `/metrics` 端点 + Grafana 面板配置 | ✅ 满足 + 超出（方案仅提及"运行监控"，已实现完整 Prometheus + Grafana 部署配置 + 告警规则建议） |

---

## 二、系统接口设计对照

### （一）第一阶段核心接口

#### 1. 标识登记接口

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 生成 MA 统一标识 | `macode.Generator.Allocate` → `chain.IssueMA` | ✅ 满足 |
| 生成或登记内容 Hash | `IssueMA` 强绑定 FileHash + PerceptualHash + 集级哈希 | ✅ 满足 |
| 建立 MA 与 Hash 的映射关系 | `hash_binding` 表 + `hashIndex` 内存索引 | ✅ 满足 |
| 建立 MA 与片库文件 ID 的映射关系 | `RegisterMapping(PartyReviewer, mediaAssetID)` | ✅ 满足 |
| 建立 MA 与省级内容编码的映射关系 | `RegisterMapping(PartyCP, cpMediaID)` | ✅ 满足 |
| 将相关信息写入目录库 | `chain.Client` 统一写入 + PG 持久化 | ✅ 满足 |
| CPSP 发布环节触发 | `Service.ApproveAndIssue`（审核通过后发码签发） | ✅ 满足 |

#### 2. 标识查询接口

| 方案查询方式 | API 路径 | 代码方法 | 状态 |
|------------|---------|---------|------|
| 根据 MA 查询 | `GET /content/mappings` + `GET /catalog/query-by-ma` | `chain.QueryContent` + `chain.QueryMappings` | ✅ 满足 |
| 根据 Hash 查询 | `GET /content/query-by-hash` + `GET /catalog/query-by-hash` | `chain.QueryByHash` | ✅ 满足 |
| 根据省级内容编码查询 | `GET /content/query-by-provincial-code` + `GET /catalog/query-by-provincial-code` | `chain.QueryByProvincialCode` | ✅ 满足 |
| 根据片库文件 ID 查询 | `GET /content/query-by-library-id` + `GET /catalog/query-by-library-id` | `chain.QueryByLibraryFileID` | ✅ 满足 |
| 返回内容标识信息及映射关系 | `ContentQueryResult{Content, Bindings, Mappings}` | 统一返回结构 | ✅ 满足 |

### （二）后续扩展接口

#### 1. 验真服务接口

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 判断内容是否已存在 | `chain.HashExists()` | ✅ 满足 |
| 判断是否已生成 MA | `chain.QueryContent()` 状态检查 | ✅ 满足 |
| 查询对应内容信息 | 四维度查询接口 | ✅ 满足 |
| 查询是否存在历史记录 | `provenance.Store.Trail()` | ✅ 满足 |
| 为审核人员提供辅助判断依据 | `ScanVerify` + `Resolve` + `Accountability` | ✅ 满足 |

---

## 三、分阶段建设规划对照

### 第一阶段：省内统一标识建设

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 引入 MA 统一标识和 Hash 内容指纹 | `macode.Generator` + `chain.IssueMA` + `hash_binding` | ✅ 满足 |
| 建立内容统一身份体系 | `ContentTwinID` 内容双锚 ID + MA 码 1:1 强绑定 | ✅ 满足 |
| 建设标识服务平台 | `cmd/api-svc/main.go` 完整服务 | ✅ 满足 |
| 建设目录库 | `internal/catalog` + `cmd/catalog-svc` 独立服务 | ✅ 满足 |
| 建立 MA、Hash、片库文件 ID、省内内容编码映射关系 | `identity_mapping` 表 + `RegisterMapping` 三方 | ✅ 满足 |
| 改造 CPSP 发布环节自动生成 MA | `ApproveAndIssue` 审核通过后自动发码 | ✅ 满足 |
| 形成"省内内容编码+MA+Hash"双层标识体系 | 省级编码通过映射关联，MA+Hash 强绑定 | ✅ 满足 |

### 第二阶段：省内审核辅助建设

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 建设验真服务 | `Service.Verify` + `Service.ScanVerify` + `Service.Resolve` | ✅ 满足 |
| 改造 CPSP 受理和审核流程 | `SubmitForReview` → `ReviewCSPS` → `ApproveAndIssue` | ✅ 满足 |
| 通过 Hash 调用验真服务识别内容 | `HashExists` + `QueryByHash` + `VerifyHash` | ✅ 满足 |
| 审核结果与 MA 建立关联 | `ProvenanceEvent` 存证 + `FilingRecord` 备案关联 | ✅ 满足 |
| 审核数据资产沉淀机制 | `provenance.Store` 不可篡改时间序存证 | ✅ 满足 |

### 第三阶段：全国统一标识与审核协同建设

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 制定全国统一 MA 编码规则 | `macode.Segment` 号段管理 + `RegisterSegment` + `ParseMACode` 解析 | ✅ 满足 |
| 建设全国目录中心 | `internal/nationalcatalog` 包 + `NationalCatalog` 服务 | ✅ 满足 |
| 省级目录库 ↔ 全国目录中心数据同步机制 | `SyncService` 全量/增量同步 + `NationalCatalog.SyncFromProvince` | ✅ 满足 |
| 各省内容编码与全国统一 MA 映射同步 | `SyncSource`/`SyncSink` 接口 + 省级数据聚合 | ✅ 满足 |
| 审核记录与 MA 关联 | `ShareAuditRecord` 审核记录共享 | ✅ 满足 |
| 审核状态、审核结论跨省共享 | `NationalCatalog.QueryAuditRecords` 全国查询 | ✅ 满足 |
| 跨省审核结果复用 | `CrossProvinceAdmit` 三重校验快速准入 | ✅ 满足 + 超出（方案提及"审核结果复用"，已实现完整三重校验准入流程） |
| 统一数据治理和主数据管理 | `NationalStats` 全国统计 + `DailyRegulatoryReport` 监管日报 | ✅ 满足 |

### 第四阶段：生态推广应用

| 方案要求 | 代码实现 | 状态 |
|---------|---------|------|
| 向内容提供商开放 MA 查询 | 四维度查询接口 + CP 角色权限 | ✅ 满足 |
| 向内容提供商开放内容识别 | `Resolve` 跨域解析 + `ScanVerify` 扫码验真 | ✅ 满足 |
| 向内容提供商开放审核记录查询 | `GET /content/provenance` | ✅ 满足 |
| 向内容提供商开放内容追踪 | `GET /content/accountability` 责任界定 + `GET /content/evidence` 确权证据链 | ✅ 满足 |
| 内容查重 | `HashExists` + `MatchInfringement` 感知哈希侵权比对 | ✅ 满足 + 超出（方案提及"内容查重"，已实现感知哈希汉明距离比对） |
| 内容快速定位 | 四维度反查接口 | ✅ 满足 |
| 内容状态查询 | `QueryContent` 返回状态 + `ListContentsByStatus` | ✅ 满足 |
| 运营商快速识别内容身份 | `Resolve` + `ScanVerify` + `VerifyHash` | ✅ 满足 |
| 运营商查询审核记录 | `GET /content/provenance` | ✅ 满足 |
| 运营商共享审核成果 | `CrossProvinceAdmit` 跨省准入 + `ShareAuditRecord` | ✅ 满足 |

---

## 四、超出方案要求的实现

以下功能在方案文档中未明确提及或仅概括性描述，代码实现已超出方案要求：

| 超出项 | 代码实现 | 说明 |
|--------|---------|------|
| **跨域解析网关（大小屏融合）** | `Service.Resolve` + `ParseMACode` 六段式解析 | 方案未提及 IPTV/OTT/APP 跨屏身份互通，已实现统一解析 |
| **扫码验真** | `Service.ScanVerify` | 方案未提及用户侧扫码验真防盗版，已实现 |
| **跨屏权益通兑** | `Service.RecordPurchase` + `Service.VerifyCrossScreenRights` | 方案未提及大小屏购买通兑，已实现"一屏购买全屏通看" |
| **感知哈希侵权比对** | `Service.MatchInfringement` 汉明距离比对 | 方案仅提及"内容查重"，已实现感知哈希相似度检索 |
| **版权确权证据链** | `Service.CopyrightEvidence` | 方案未提及司法举证能力，已实现"谁先锁定谁有权"证据链导出 |
| **责任界定取证** | `provenance.Store.Accountability` | 方案未提及追责取证，已实现首次哈希变化节点定位 |
| **授权链与发布前核验** | `Service.RecordAuthorization` + `Service.CheckAuthorization` | 方案未提及信息网络传播权授权管理，已实现地域/平台/过期核验 |
| **CDN 注入校验** | `Service.InjectToCDN` | 方案未提及 CDN 注入前哈希校验，已实现"不匹配拒绝注入并告警" |
| **终端片段抽检** | `Service.TerminalVerifySegment` | 方案未提及终端侧抽检，已实现集级哈希校验 + 断流建议 |
| **播放数据回传与分账** | `Service.ReportPlayback` + `Service.ComputeSettlement` | 方案未提及播放数据聚合与分账，已实现基于可信数据的分账计算 |
| **RBAC 动态权限矩阵** | `httpx.RBACManager` + 40+ 权限常量 + 动态增删 | 方案仅提及"权限管理"，已实现可配置角色权限矩阵 |
| **同步冲突解决策略** | `SyncService` 三种策略（Skip/Overwrite/Fail） | 方案仅提及"标识同步"，已实现冲突检测与解决 |
| **全国目录中心统计** | `NationalCatalog.Stats` 按省/状态/类目统计 | 方案仅提及"全国目录中心"，已实现多维度统计 |
| **Grafana 监控面板** | `deploy/monitoring/grafana-dashboard.json` 6 个面板 | 方案仅提及"运行监控"，已实现完整 Prometheus + Grafana 配置 |
| **集级下架与恢复** | `Service.TakedownEpisode` + `Service.RestoreEpisode` | 方案仅提及"失效"，已实现集级粒度下架/恢复 |
| **追更与增量哈希更新** | `Service.AddEpisodes` | 方案未提及内容追更场景，已实现不触发重审的增量赋码 |
| **版本变更重审** | `Service.ReportVersionChange` + Merkle 树定位篡改集 | 方案未提及版本变更检测，已实现哈希断裂触发重审 + 精确定位 |
| **备案/网标关联** | `Service.BindFiling` + `Service.QueryFiling` | 方案未提及广电总局备案对接，已实现网标号/备案号关联 |
| **监管数据上报日报** | `Service.DailyRegulatoryReport` | 方案未提及监管上报，已实现日报生成 |
| **号段管理** | `Service.ListSegments` + `Service.RegisterSegment` | 方案未提及号段管理界面，已实现号段登记与使用情况查询 |

---

## 五、代码文件清单

### 核心包

| 包路径 | 职责 | 方案模块 |
|--------|------|---------|
| `internal/model/` | 领域模型定义 | 全部模块 |
| `internal/chain/` | 可信数据空间客户端抽象（Memory/Persistent/ChainMaker） | 标识服务 + MA管理 |
| `internal/service/` | 业务逻辑层 | 标识服务 + 验真服务 + MA管理 |
| `internal/api/` | HTTP API 处理器 | 全部模块 |
| `internal/httpx/` | 鉴权 + RBAC + 统一响应 | 系统管理 |
| `internal/catalog/` | 目录库独立查询层 | 内容资源层 |
| `internal/sync/` | 标识同步服务 | 标识服务 |
| `internal/nationalcatalog/` | 全国目录中心 | 第三阶段 |
| `internal/monitor/` | Prometheus 监控 | 系统管理 |
| `internal/macode/` | MA 码生成器 | 标识服务 |
| `internal/provenance/` | 全链路存证 | 验真服务 + 系统管理 |
| `internal/playback/` | 播放数据存储与分账 | 第四阶段 |
| `internal/hash/` | 哈希工具（Merkle 树、感知哈希） | 标识服务 |
| `internal/config/` | 配置管理 | 系统管理 |

### 微服务入口

| 入口 | 端口 | 职责 |
|------|------|------|
| `cmd/api-svc/` | :8080 | 主 API 服务（标识登记/查询/验真/MA管理/系统管理） |
| `cmd/chain-svc/` | :8081 | 链服务（预留） |
| `cmd/hash-api/` | :8082 | 哈希服务 |
| `cmd/catalog-svc/` | :8083 | 目录库独立微服务 |
| `cmd/console-bff/` | — | 控制台 BFF（预留） |

### 部署配置

| 文件 | 职责 |
|------|------|
| `deploy/migrations/0001_init.sql` | 初始化表结构 |
| `deploy/migrations/0005_admin.sql` | 用户/组织表 |
| `deploy/monitoring/prometheus.yml` | Prometheus 采集配置 |
| `deploy/monitoring/grafana-dashboard.json` | Grafana 监控面板 |
| `deploy/monitoring/README.md` | 监控部署说明 |

### 测试覆盖

| 测试文件 | 覆盖范围 |
|---------|---------|
| `internal/chain/conformance_test.go` | 链客户端契约测试（含多维度查询 + 合并/拆分） |
| `internal/service/service_test.go` | 送审/发码/验真核心流程 |
| `internal/service/distribution_test.go` | 转码/入库/发布/CDN注入/下架 |
| `internal/service/episode_test.go` | 集级哈希/集级下架 |
| `internal/service/accountability_test.go` | 责任界定取证 |
| `internal/service/admin_test.go` | 用户/组织管理 |
| `internal/httpx/rbac_test.go` | RBAC 动态权限 |
| `internal/catalog/catalog_test.go` | 目录库查询 |
| `internal/sync/sync_test.go` | 标识同步 + 冲突策略 |
| `internal/nationalcatalog/nationalcatalog_test.go` | 全国目录中心 |
| `internal/api/catalog_handlers_test.go` | 目录库微服务 API |

---

## 六、结论

| 维度 | 方案要求 | 代码实现 | 匹配度 |
|------|---------|---------|--------|
| 标识服务模块 | 8 项功能 | 8 项全部实现 | 100% |
| 验真服务模块 | 5 项功能 | 5 项全部实现 | 100% |
| MA 管理模块 | 7 项功能 | 7 项全部实现 | 100% |
| 系统管理模块 | 6 项功能 | 6 项全部实现 | 100% |
| 第一阶段 | 7 项要求 | 7 项全部实现 | 100% |
| 第二阶段 | 5 项要求 | 5 项全部实现 | 100% |
| 第三阶段 | 8 项要求 | 8 项全部实现 | 100% |
| 第四阶段 | 10 项要求 | 10 项全部实现 | 100% |
| **超出项** | — | **20 项超出实现** | — |

**总体评价**：代码实现完整覆盖了 `IPTV系统融合MA码方案介绍.md` 中定义的全部功能模块和四个建设阶段，并在跨域解析、扫码验真、跨屏权益、侵权比对、版权确权、责任界定、授权管理、CDN注入校验、终端抽检、播放分账、RBAC权限矩阵、同步冲突策略、Grafana监控等方面**超出方案要求**。