Module Document

基础架构 · 指令协议平台产品文档

基础架构 · 指令协议平台产品文档

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

1. 产品定位

为设备云、App、固件、测试和售后提供统一指令协议定义、版本治理、模拟测试和兼容性验收入口。

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

定位维度	v0.1 口径
建设阶段	试产期最小可运营底盘，不做过度平台化。
事实源原则	飞书做协同入口，设备指令契约底座的配置、记录和审计进入结构化系统。
180 天目标	先跑通核心闭环，再按容量、安全和自动化逐步增强。

2. 使用对象与核心诉求

使用对象	核心诉求
固件研发	明确下行命令、上行事件、错误码和版本兼容规则。
设备云研发	按统一契约实现命令下发、ACK、进度、结果和重试。
App 研发	按能力模型展示控制项和状态反馈。
测试/售后	使用模拟器复现指令链路和异常场景。

3. 系统边界

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

4. 核心场景

新增设备能力时同步定义 App 控制、云端命令、固件处理和测试用例。
老固件不支持新指令时返回兼容错误并提示升级路径。
售后使用模拟器复现用户远程控制失败和设备异常上报。
发布前跑协议回归，确认 ACK/progress/result 的时序和幂等。

5. 功能清单

功能	说明
指令字典	统一维护命令、参数、响应、错误码、适用机型和固件版本。
契约版本	指令版本、schema 版本、兼容矩阵和废弃策略。
模拟器	模拟设备在线、离线、超时、拒绝、部分成功和异常上报。
测试套件	标准协议用例、回归用例、边界用例和时序用例。
能力发布	新能力从草案、评审、试产、正式、废弃全生命周期管理。

6. 业务流程

提出指令需求
定义契约草案
固件/云/App 联审
生成模拟器和测试用例
试产验证
正式发布和版本归档

7. 权限与运营规则

指令契约修改必须经过固件、设备云、App 和测试共同评审。
正式指令版本不可直接覆盖，变更必须新建版本并声明兼容关系。
高危命令需要二次确认、权限校验、幂等键和完整审计。
飞书只做评审通知，协议契约事实源保留在协议平台和代码仓。

8. 验收指标

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

9. 里程碑

阶段	交付物
0-30 天	梳理现有命令、错误码、Topic/API 命名和版本规则。
31-90 天	建立指令字典、模拟器、核心协议回归和能力矩阵。
91-180 天	接入发布流程、售后排障、自动化测试和跨版本兼容报告。

10. 风险点

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