Module Document

基础架构 · 指令协议平台详细设计文档

基础架构 · 指令协议平台详细设计文档

版本: v0.1
日期: 2026-07-06
归属: 基础架构 / 指令协议平台

1. 模块定位与目标

指令协议平台是 CNC 设备通信的契约管控中心。所有 Proto/私网联网协议的定义、版本、发布和 SDK 分发必须经由本平台，任何研发团队不得私自修改已发布协议。

目标 说明
统一协议事实源 Proto 定义文件、Topic 规范、payload schema 唯一存放于本平台。
SDK 受控分发 各端（固件/App/云端）只能从平台下载官方 SDK，不得手写裸协议。
禁止私改 已发布版本不可编辑，变更必须走评审流程创建新版本。
可追溯 每个协议版本、每次 SDK 下载、每次变更评审均有完整审计记录。

2. 执行计划

阶段 时间 交付物 Owner 工作量
P0 梳理存量 0–14 天 整理现有命令字、Topic、错误码清单，导入草稿 固件+设备云联合 2人×1周
P1 平台骨架 15–45 天 协议 Registry、版本锁定、评审流程、基础 Web UI 后端1+前端1 2人×4周
P2 SDK 生成 46–75 天 Proto→C/Go/TS SDK 自动生成 pipeline、下载入口、签名校验 后端1+固件1 2人×4周
P3 模拟器+回归 76–105 天 设备模拟器、协议回归 Runner、发布门禁 后端1+测试1 2人×4周
P4 接入所有端 106–135 天 固件/App/设备云全面切换 SDK，下线手工维护路径 各端 owner 分端并行

3. 困难点与复杂度分析

困难点 复杂度 应对
Proto 与私网协议双轨并存 高 统一抽象为”协议定义单元”，Proto 和 Topic/JSON-schema 分类型管理，SDK 生成器按类型分支。
SDK 多语言自动生成 高 先支持 C (固件)、Go (云端)、TypeScript (App)；用 protoc + 自定义模板；非 Proto 协议生成类型声明文件。
禁止私改的技术强制 中 已发布版本在存储层设为 immutable，Web UI 隐藏编辑入口；SDK 包含版本签名，设备云启动时校验签名。
历史协议存量迁移 中 分批导入，先标记”已归档/未正式管理”，不强制立刻换 SDK，设 90 天迁移窗口。
跨团队评审协同 中 评审流程集成飞书审批通知，必须固件+云端+App 三方 approve 才可发布。
设备现场离线 SDK 更新 中 SDK 随 OTA 包分发，OTA 服务从协议平台拉取签名包，保证版本一致性。

4. 核心流程

flowchart LR
  A["研发提出协议变更需求"] --> B["平台创建草案版本"]
  B --> C["固件 / 云端 / App 联合评审"]
  C --> D{评审通过?}
  D -->|否| B
  D -->|是| E["锁定版本 immutable"]
  E --> F["触发 SDK 自动生成"]
  F --> G["SDK 签名 + 发布到下载中心"]
  G --> H["各端下载 SDK"]
  H --> I["集成到固件 / App / 云端构建"]
  I --> J["协议回归测试通过"]
  J --> K["随发布版本上线"]

5. 系统架构

flowchart LR
  subgraph Portal["协议平台 Web"]
    UI["协议编辑 / 查看 UI"] --> REG["Protocol Registry API"]
    DL["SDK 下载中心"] --> SIGN["签名服务"]
  end
  subgraph Pipeline["SDK 生成 Pipeline"]
    REG --> GEN["protoc / schema-codegen"]
    GEN --> SIGN
    SIGN --> STORE["制品仓 (带版本签名)"]
  end
  subgraph Consumers["消费端"]
    STORE --> FW["固件 SDK (C)"]
    STORE --> CLD["云端 SDK (Go)"]
    STORE --> APP["App SDK (TS)"]
  end
  REG --> REVIEW["飞书评审通知"]
  REG --> AUDIT["审计日志"]

6. 关键技术决策

决策点 选择 理由
协议格式 Protobuf 3 为主，JSON Schema 为辅 固件侧用 Proto 编解码高效；私网控制指令若已用 JSON 可并存过渡。
SDK 生成 protoc + buf CLI + 自定义模板 buf 支持 lint/breaking change 检测，天然阻断不兼容变更。
版本不可变 存储层对象设 immutable flag + DB 行级锁定 UI 无法编辑，API 层返回 403，从技术而非流程强制。
评审流程 飞书审批 webhook 回调 研发已在飞书，减少工具切换，审批记录留在飞书可追溯。
SDK 签名 Ed25519 私钥签名 + 公钥随固件/云端部署 轻量，校验快，固件侧 C 库成熟。

7. 数据模型

模型 关键字段 说明
ProtocolDefinition id、name、protocol_type(proto/topic/schema)、category、status、created_by 协议定义主表。
ProtocolVersion id、protocol_id、version、content_hash、is_locked、published_at、deprecated_at 版本记录，is_locked=true 后不可编辑。
ReviewRecord id、version_id、reviewer_role、reviewer_id、decision、comment、decided_at 三方评审记录。
SdkArtifact id、version_id、lang、file_key、signature、size、built_at 生成的 SDK 制品。
SdkDownloadLog id、artifact_id、downloader_id、ip、team、downloaded_at 下载审计。
CompatibilityMatrix id、model、firmware_version、protocol_version_ids 设备能力兼容矩阵。

8. 接口设计

接口 方法 说明
/protocols GET/POST 协议列表 / 创建草案。
/protocols/{id}/versions GET/POST 版本列表 / 创建新版本（已发布后只读）。
/protocols/{id}/versions/{ver}/lock POST 提交评审并锁定，触发 SDK 生成。
/protocols/{id}/versions/{ver}/sdk/{lang} GET 下载指定语言 SDK，记录审计。
/protocols/{id}/versions/{ver}/reviews GET/POST 查看 / 提交评审意见。
/compatibility GET/POST 查询 / 更新设备兼容矩阵。

9. 验收点

验收点 量化标准
协议存量导入 现有全部命令字、Topic、错误码 100% 导入，归档状态明确。
版本不可编辑 已发布版本的编辑 API 返回 403，UI 编辑按钮不可点击。
SDK 自动生成 版本锁定后 5 分钟内 C/Go/TS 三种 SDK 可下载。
签名校验 设备云启动时 SDK 签名校验失败则拒绝加载，日志可见。
三方评审强制 未经固件/云端/App 三方 approve 的版本无法发布，系统级阻断。
下载可追溯 每次 SDK 下载有 downloader_id、team、IP 和时间记录。
回归覆盖 核心协议 100% 有回归用例，发布前回归通过率 ≥ 95%。

10. 风险与应对

风险 应对
存量协议混乱，梳理周期长 P0 阶段优先梳理高危指令（急停/启动/加工），其余分批归档。
固件侧 SDK 更新滞后 SDK 版本兼容矩阵公示，固件 CI 检测 SDK 版本是否匹配发布版本。
SDK 生成失败阻塞发布 生成失败不锁定版本，保留草案状态，告警到 on-call。
评审流程成为瓶颈 轻微变更（注释/文档）走快速通道，只需 1 方审批。