基础架构 · 指令协议平台概要设计文档

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

1. 顶层设计

把设备指令、Topic/API、版本兼容、模拟器和协议测试作为跨模块契约管理，避免 App、云端、固件各写各的。

层级	设计
契约层	维护指令、事件、schema、错误码和版本兼容矩阵。
验证层	提供模拟器、协议测试、回归任务和测试报告。
运行层	向设备云、App 和售后提供能力查询和协议审计。

2. 核心业务流

flowchart LR
  N1["提出能力需求"] --> N2["生成指令草案"]
  N2["生成指令草案"] --> N3["联合评审"]
  N3["联合评审"] --> N4["生成测试场景"]
  N4["生成测试场景"] --> N5["真机验证"]
  N5["真机验证"] --> N6["发布版本"]

3. 业务概要设计

业务能力	概要设计
指令定义	包含命令名称、方向、参数 schema、响应 schema、错误码、幂等规则和权限级别。
版本治理	支持草案、试产、正式、废弃，废弃前给出替代指令和兼容窗口。
验收接入	固件、云端、App 任何一侧发布前必须关联协议测试报告。

4. 系统边界

负责	不负责
指令字典、Topic/API 契约、payload schema、版本矩阵、模拟器、协议测试用例、错误码和能力模型。	MQTT 基础通信管道、实时视频媒体链路、具体加工算法、固件内部状态机实现。

5. 系统顶层设计

组件	职责
Protocol Registry	维护指令、事件、schema、错误码和版本矩阵。
Simulator	模拟设备状态、网络异常和不同固件能力。
Contract Test Runner	执行协议回归、时序校验和边界测试。
Capability API	向 App、设备云、售后返回设备能力和兼容结果。

6. 系统流图

flowchart LR
  N1["App/Cloud/Firmware"] --> N2["Protocol Registry"]
  N2["Protocol Registry"] --> N3["Capability API"]
  N2["Protocol Registry"] --> N4["Simulator"]
  N4["Simulator"] --> N5["Contract Test Runner"]
  N5["Contract Test Runner"] --> N6["Report"]
  N7["Device Cloud"] --> N8["MQTT/HTTP"]
  N8["MQTT/HTTP"] --> N9["Device/Firmware"]
  N9["Device/Firmware"] --> N6["Report"]

7. 模型设计

模型	关键字段	说明
CommandDefinition	`command`、`version`、`schema`、`risk_level`、`status`	指令定义。
DeviceCapability	`model`、`firmware_version`、`commands`、`limits`	设备能力矩阵。
ProtocolTestCase	`case_id`、`command`、`scenario`、`expected`	协议测试用例。
CommandAudit	`device_id`、`command`、`operator`、`result`、`trace_id`	运行审计。

8. 验收点

验收点	标准
契约覆盖	核心设备能力 100% 有命令、响应、错误码和测试用例。
兼容可见	正式固件版本 100% 可查询支持的指令版本。
回归通过	发布前协议回归通过率不低于 95%，失败项有 owner。
高危审计	启动、停止、急停、远程加工等高危命令 100% 有审计记录。

9. 人力评估

角色	估算
设备云后端	1 人 3 周
固件研发	1 人 2 周
App 研发	0.5 人 1 周
测试	1 人 2 周
产品/架构	0.5 人 1 周

10. 风险点

风险	应对
协议变更绕过评审	设备云入口只接受已发布契约，高危命令启用白名单。
模拟器与真实设备偏差	模拟器用试产日志校准，关键场景必须真机回归。
版本兼容失控	能力矩阵按机型、固件、App、云端版本联合维护。