MAcode/docs/08-核心业务时序图与状态机.md

第八章 核心业务时序图与状态机设计

版本：V1.0
基于文档：《AIGC-Hub智视码(AVCC)体系建设方案 V2.0》

本章主要面向研发团队，提供核心业务场景的交互时序图（Sequence Diagram）以及核心实体的状态机（State Machine）定义，支持开发阶段的接口对接与流程编码。

---

8.1 核心业务时序图

8.1.1 赋码全链路时序图（含审核与上链）

描述从创作者提交申请，到完成 AI 预审、版权上链并最终签发 AVCC 证书的全过程。

sequenceDiagram
    autonumber
    actor Creator as 创作者(工作台)
    participant CodeSvc as 赋码引擎(CodeSvc)
    participant Kafka as 消息队列(Kafka)
    participant ReviewSvc as 审核引擎(ReviewSvc)
    participant ChainSvc as 版权链引擎(ChainSvc)
    participant DB as 主数据库(PG)

    Creator->>CodeSvc: 1. 提交赋码申请(视频+版权材料)
    CodeSvc->>CodeSvc: 2. 预检(重复/黑名单/材料完整性)
    CodeSvc->>DB: 3. 创建赋码记录(status=pre_checking)
    CodeSvc-->>Creator: 4. 返回受理成功(202 Accepted)

    CodeSvc->>Kafka: 5. 发布事件[topic.avcc.apply.created]
    Kafka-->>ReviewSvc: 6. 消费事件，创建审核任务
    ReviewSvc->>DB: 7. 更新状态(status=ai_reviewing)
    
    rect rgb(240, 248, 255)
        Note over ReviewSvc: 执行 AI 多模态审核
        ReviewSvc->>ReviewSvc: 切片、多模型并行推理、融合决策
    end

    ReviewSvc->>DB: 8. 保存审核报告(review_reports)
    ReviewSvc->>Kafka: 9. 发布事件[topic.review.task.finished]
    
    Kafka-->>ChainSvc: 10. 消费事件，准备上链
    ChainSvc->>ChainSvc: 11. 调用智能合约 RegisterCopyright
    ChainSvc->>DB: 12. 保存链交易记录(chain_records)
    ChainSvc->>Kafka: 13. 发布事件[topic.chain.tx.confirmed]

    Kafka-->>CodeSvc: 14. 消费上链成功事件
    CodeSvc->>CodeSvc: 15. 执行 GenerateAVCC 算法生成六段式编码
    CodeSvc->>DB: 16. 更新赋码记录(status=approved, 填入AVCC)
    
    Creator->>CodeSvc: 17. 轮询/查询进度
    CodeSvc-->>Creator: 18. 返回 AVCC 证书信息

8.1.2 跨平台解析与鉴权时序图

描述第三方平台在分发作品前，如何通过 MA 网关验证流通权限。

sequenceDiagram
    autonumber
    participant App as 平台客户端(App)
    participant Platform as 平台后端
    participant Gateway as MA网关(Gateway)
    participant Redis as 缓存(Redis)
    participant ZIIOT as MA全球根系统

    App->>Platform: 1. 请求播放/分发某视频(附带AVCC)
    Platform->>Gateway: 2. POST /api/v1/avcc/parse (附带API Key)
    
    Gateway->>Gateway: 3. API Key 鉴权与限流检查
    Gateway->>Redis: 4. 查询 AVCC 缓存
    
    alt 缓存未命中
        Gateway->>ZIIOT: 5. 调用根解析接口(可选, 严格模式)
        ZIIOT-->>Gateway: 6. 返回根解析验证结果
        Gateway->>Gateway: 7. 计算流通权限(如 P类/G类)
        Gateway->>Redis: 8. 写入解析结果缓存(TTL=1h)
    end
    
    Gateway-->>Platform: 9. 返回解析结果与 circulation_rights
    
    alt 权限校验通过
        Platform-->>App: 10. 允许播放，下发视频流
    else 权限校验失败(如：O类跨平台)
        Platform-->>App: 11. 拒绝播放，下架处理
    end

8.1.3 跨平台播放分账时序图

描述播放行为如何转化为链上的分账清算记录。

sequenceDiagram
    autonumber
    participant Platform as 平台后端
    participant Gateway as 广电云网关
    participant ClickHouse as 时序数据库
    participant Settlement as 清算引擎
    participant ChainSvc as 智能合约(联盟链)

    Platform->>Gateway: 1. 批量回传播放数据(Event: play)
    Gateway->>Kafka: 2. 投递到[topic.playback.event]
    Kafka-->>ClickHouse: 3. 消费入库，实时聚合
    
    loop 每日/每月定时调度
        Settlement->>ClickHouse: 4. 提取周期内各 AVCC 播放与收益汇总
        Settlement->>ChainSvc: 5. 触发合约 ExecuteSettlement
        ChainSvc->>ChainSvc: 6. 链上按比例分配(创作者/模型/IP/平台)
        ChainSvc-->>Settlement: 7. 返回链上交易回执(tx_hash)
        Settlement->>Settlement: 8. 更新 PostgreSQL(settlement_records)
    end

---

8.2 核心状态机定义

8.2.1 审核状态机 (review_status)

控制作品在赋码审批流程中的流转。

stateDiagram-v2
    [*] --> pending: 提交申请
    pending --> pre_checking: 开始预检
    
    pre_checking --> ai_reviewing: 预检通过
    pre_checking --> rejected: 预检失败(重复/黑名单)
    
    ai_reviewing --> human_reviewing: 需人工复核(P类/合规边缘)
    ai_reviewing --> approved: AI秒批通过(O类/合规高分)
    ai_reviewing --> rejected: AI判定违规且不可修改
    
    human_reviewing --> approved: 人工终审通过
    human_reviewing --> rejected: 人工终审驳回
    
    approved --> revoked: 事后发现侵权/违规(吊销)
    
    rejected --> [*]
    revoked --> [*]

状态流转说明：

• pending -> pre_checking：赋码引擎 (code-pre-check) 执行
• pre_checking -> ai_reviewing：触发 Kafka 消息交由审核引擎执行
• ai_reviewing -> human_reviewing：融合决策层判定 suggested_level=P 或置信度处于边缘区间时触发
• approved：触发生成 AVCC 和上链操作

8.2.2 流通状态机 (circulation_status)

控制已赋码作品在全网的合法流通权限。

stateDiagram-v2
    [*] --> active: 获得AVCC证书
    
    active --> suspended: 收到侵权投诉/配合调查
    suspended --> active: 调查澄清，恢复流通
    
    active --> revoked: 严重违规/黑名单/伪造授权
    suspended --> revoked: 侵权坐实
    
    active --> expired: 网标有效期结束
    expired --> active: 续期申请通过
    
    revoked --> [*]: 永久失效，MA根节点同步注销

触发机制：

• active -> suspended：由管理后台运营人员手工触发（对应 API /api/v1/avcc/suspend）
• active -> expired：定时任务每日扫描 expires_at 字段自动触发
• active -> revoked：广电总局下发黑名单指令，或 ZIIOT 根节点触发码资源回收

---

8.3 并发与异常处理策略

8.3.1 分布式锁（防止并发重复赋码）

在 CodeSvc 分配 MA 码段时，必须加锁：

• 锁 Key：lock:allocate:{platform_node}
• 机制：Redis Redlock，持有锁期间从数据库/缓存中原子性获取最大序列号并 +1，生成完毕后释放锁。

8.3.2 失败补偿与 Saga 模式

针对图 8.1.1 中的长事务（跨越 Code, Review, Chain），采用 基于事件的 Saga 模式：

• 如果步骤 10-13（版权上链）失败，Kafka 会基于死信队列（DLQ）重试 3 次。
• 若 3 次均失败，触发补偿事务：ChainSvc 发布 topic.chain.tx.failed，CodeSvc 消费后将 review_status 置为 failed，并通知创作者重新提交。

8.3.3 幂等性设计

• 所有涉及到数据库更新（状态流转）的 Kafka 消费者，必须检查记录的 version 或当前状态。
• 例如：UPDATE avcc_records SET status = 'approved' WHERE id = ? AND status = 'human_reviewing'，避免重复消费导致状态错乱。