MAcode/docs/10-C2PA与第三方对接详细设计.md

第十章 C2PA 与第三方系统对接详细设计

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

本章详细定义了 AIGC-Hub 与外部系统（AI 工具、ZIIOT 根节点、联盟链底链）的底层对接实现逻辑，为 SDK 开发组和中间件开发组提供编码依据。

---

10.1 C2PA 水印 SDK 内部实现与工具对接

SDK 的核心目标是：在 AI 生成的图片/视频文件中，非破坏性地注入符合 C2PA 标准的元数据（Manifest），并包含 MA 专属扩展字段。

10.1.1 核心签名流程设计（基于 Rust c2pa-rs）

生成内容凭证的步骤：

1. 构造 Claim：收集生成环境信息（模型名、工具版本、时间戳）。
2. 附加 Assertions：
   • 基础哈希断言 (c2pa.hash.data)
   • 训练数据来源断言 (c2pa.training-mining)
   • MA 专属断言 (ma.avcc.fragment)
3. 加载签名密钥：使用广电云颁发的 CA 证书或创作者关联的证书。
4. 签名并嵌入：计算文件哈希，用私钥对 Claim 签名，并将签名打包成 JUMBF 格式注入文件头部（如 MP4 的 uuid box 或 JPEG 的 APP11 marker）。

10.1.2 AI 工具适配器 (Adapters) 实现逻辑

以最流行的开源生图工具 Stable Diffusion WebUI (A1111) 为例，实现对接扩展：

# 伪代码：sd-webui-aigchub-extension/scripts/c2pa_hook.py
import modules.scripts as scripts
from modules.processing import Processed
from aigc_hub_sdk import C2PAManifestBuilder, MAExtension

class AIGCHubScript(scripts.Script):
    def title(self):
        return "AIGC-Hub C2PA 自动打码"

    def show(self, is_img2img):
        return scripts.AlwaysVisible

    def postprocess(self, p, processed: Processed, *args):
        # 拦截生成后的图像
        for i, image in enumerate(processed.images):
            # 获取用户配置的 MA 节点代码
            platform_node = get_user_ma_node() 
            
            # 构建 MA 扩展
            ma_ext = MAExtension(
                platform_node=platform_node,
                object_category="10.1300200.AIGC",
                model_name=p.sampler_name,      # 记录采样器
                model_version=p.sd_model_name,  # 记录模型名
                generation_log_hash=hash(p.prompt) # 记录 Prompt 哈希
            )
            
            # 注入 C2PA 水印并覆盖原图
            image_path = processed.images_paths[i]
            builder = C2PAManifestBuilder()
            builder.add_assertion(ma_ext)
            builder.embed_in_place(image_path, private_key=get_local_key())

针对闭源云端工具（如 Runway/可灵），方案为：提供服务端 API，云端工具在渲染完成后，调用 AIGC-Hub 提供的 SDK 或 HTTP API 完成签名注入。

---

10.2 MA 根解析对接设计 (ZIIOT 对接)

广电云网关 (gateway-svc) 需要与 ZIIOT 全球根解析服务进行实时通信。

10.2.1 根解析协议与通信方式

• 协议：遵循 ISO/IEC 15459 标准的 RESTful API 或 Handle System 协议。
• 寻址逻辑： 当第三方请求解析 MA.156.10005.8361/10... 时：
  1. gateway-svc 发现前缀 MA.156.10005 属于本节点，直接在本地 PostgreSQL/Redis 查询。
  2. 如果平台请求验证 MA.156.99999... (其他行业节点)，gateway-svc 将请求代理至 ZIIOT 根服务器。

10.2.2 根节点注册/同步逻辑

广电云需要将自己分配出去的三级节点（如各大平台的 MA.156.10005.xxxx）定期或实时同步给 ZIIOT，以保证全球解析的可达性。

sequenceDiagram
    participant Gateway as 广电云网关
    participant ZIIOT as ZIIOT根系统
    
    Note over Gateway, ZIIOT: 平台节点注册同步
    Gateway->>ZIIOT: POST /api/v1/ma/sync_node
    Note right of Gateway: payload: {"node": "MA.156.10005.8361", "resolve_url": "https://gateway.aigc-hub.cn/resolve/"}
    ZIIOT-->>Gateway: 200 OK
    
    Note over Gateway, ZIIOT: 违规码全网吊销
    Gateway->>ZIIOT: POST /api/v1/ma/revoke
    Note right of Gateway: payload: {"avcc": "MA...CRD(xxx)", "reason": "blacklisted"}
    ZIIOT-->>Gateway: 200 OK (同步全球黑名单)

---

10.3 联盟链底层对接设计 (ChainMaker/Fabric)

chain-svc 作为区块链代理，负责屏蔽底链细节，向上层业务提供易用的 REST/gRPC 接口。

10.3.1 链服务架构

[ Business Services: CodeSvc / SettlementSvc ]
        │
     REST / Kafka
        ▼
[ chain-svc (Go) ]
        │
   (交易拼装/签名/序列化)
        │
   [ ChainMaker Go SDK ]
        │
      gRPC
        ▼
[ ChainMaker Nodes (联盟网络) ]

10.3.2 异步上链与确认机制

由于区块链共识（如 TBFT/Raft）存在延迟（通常秒级），不能同步阻塞业务请求。

处理流程：

1. 业务服务发送消息至 Kafka topic.chain.tx.pending。
2. chain-svc 消费消息，调用 SDK InvokeContract 发起交易。
3. chain-svc 收到同步返回的 tx_id，但这并不代表上链成功。
4. chain-svc 将 tx_id 写入本地表 chain_records (status=pending)。
5. chain-svc 启动一个区块监听器 (Block Listener/Event Subscriber)，订阅链上的新区块事件。
6. 当监听到该 tx_id 被打包进区块且交易有效时，更新本地表为 confirmed，并发送 topic.chain.tx.confirmed 消息。

Go 代码示意（订阅事件）：

// 监听链上合约事件
func SubscribeChainEvents() {
    ctx := context.Background()
    // 订阅 AIGC_Copyright 合约的 "RegisterSuccess" 事件
    ch, err := chainClient.SubscribeContractEvent(ctx, "AIGC_Copyright", "RegisterSuccess")
    if err != nil {
        log.Fatal(err)
    }
    
    for {
        select {
        case event := <-ch:
            txId := event.TxId
            payload := event.EventData
            // 1. 更新数据库状态
            db.UpdateChainRecordStatus(txId, "confirmed")
            // 2. 发送 Kafka 消息通知 CodeSvc
            kafkaProducer.Produce("topic.chain.tx.confirmed", buildMessage(txId, payload))
        case <-ctx.Done():
            return
        }
    }
}

10.3.3 链上隐私与权限控制

• 明文不入链：用户身份证号、敏感提示词（Prompt）、详细台词不能直接上链。上链的数据必须经过 SHA-256 哈希处理。
• 跨组织鉴权：智能合约内必须判断交易发起者的公钥/证书。例如 RecordUserRights（记录跨平台购买）只能由授权的 platform_node 或广电云节点发起，创作者无权直接调用。