web-Iot/docs/DOC-09-控制命令字典-V1.0草案.md

DOC-09 控制命令字典 V1.0 草案

项目	内容
文档编号	DOC-09
文档名称	控制命令字典
版本	V1.0 草案
状态	草案（Draft）
适用系统	机器人智慧服务系统
编写日期	2026-08-10
关联文档	DOC-08 设备数据字典、命令状态机

---

1. 文档目的

统一 命令服务 Alpha 下发的全部控制命令语义，定义命令通用结构、命令类型、参数约束与错误码，作为前端控制台、设备端 SDK 与联调测试的共同契约。

2. 命令通用结构（CMD-COMMON）

命令服务 Alpha 创建命令（POST /api/commands）的通用结构：

字段	类型	必填	约束	说明
id	string	✅	UUID	平台生成，全局唯一
seq	string	✅	8 位大写 hex	命令流水号（可读性强，用于日志对账）
deviceId	string	✅	见 DOC-08 §3	目标设备
type	enum	✅	见 §3	命令类型
params	object	❌	见 §3 各类型	命令参数
priority	enum	❌	high/normal/low，默认 normal	优先级
timeoutMs	integer	❌	1000~300000，默认 30000	命令超时
maxRetries	integer	❌	0~3，默认 1	最大自动重试次数
source	string	❌	默认 web	命令来源（web/api/device）
status	enum	✅	见命令状态机.md	当前状态

3. 命令类型定义（CMD-TYPE）

3.1 运动控制类

命令	中文	适用设备	参数	说明
move	移动	巡检机器人	`{direction: 'forward'	'backward', distance?: m, speed?: m/s}`
rotate	转向	巡检机器人	{angle: -360~360, speed?: °/s}	原地旋转，正=顺时针
stop	停止	巡检机器人/无人机	`{brake?: 'normal'	'emergency'}`

3.2 任务控制类

命令	中文	适用设备	参数	说明
task_start	启动任务	巡检机器人/无人机	{taskId: string, waypoints?: [...]}	启动巡检/航线任务
task_cancel	取消任务	巡检机器人/无人机	{}	中断当前任务并返航/回位

3.3 能源与系统类

命令	中文	适用设备	参数	说明
charge	自动充电	巡检机器人	{pileId?: string}	对接指定/就近充电桩
reboot	重启	全部	{delayMs?: number}	延时重启设备
config_set	配置下发	全部	{key: string, value: any}	设置设备参数

3.4 安全与感知类

命令	中文	适用设备	参数	说明
emergency_stop	紧急停机	巡检机器人/无人机	{reason?: string}	最高优先级，立即停机/降落，不可被普通命令打断
photo	拍照	巡检机器人/无人机	`{camera?: 'rgb'	'thermal', count?: 1~10}`

4. 命令优先级规则（CMD-PRIORITY）

优先级	编码	说明
紧急	high	急停类命令，可抢占任何普通命令；同类高优先行
普通	normal	常规控制命令，按队列顺序执行
低	low	批量/后台命令，高优命令可插队

互斥规则（与测试记录配套）：

• 同一设备同一时刻仅允许 1 条 move/task_start 类互斥命令在执行（EXECUTING）。
• 执行中若收到新的互斥命令 → 新命令返回 40902 设备忙（设备侧未空闲）。
• emergency_stop 不受互斥限制，可随时下发并打断当前命令。

5. 命令执行结果（CMD-RESULT）

设备端通过 POST /api/commands/:id/result 回传：

字段	类型	约束	说明
status	enum	success / failed	执行结果
output	object	❌	执行产出（如 photo 的图片 URL）
errorCode	enum	❌	见 §6，失败时必填

6. 错误码（CMD-ERROR-CODE）

错误码	中文	说明
E0000	成功	无
E1001	设备离线	目标设备不在线
E1002	设备不存在	deviceId 未注册
E1003	设备忙	设备正在执行互斥命令
E2001	参数非法	命令参数校验失败
E2002	命令不支持	设备能力不包含该命令类型
E2003	任务不存在	taskId 无效
E3001	执行超时	设备未在 timeoutMs 内完成
E3002	执行中断	被 emergency_stop 等打断
E4001	内部错误	设备端异常

7. 命令生命周期速查

创建 → SENT → ACKED → EXECUTING → SUCCEEDED / FAILED
                 ↘ TIMEOUT（自动重试 ≤maxRetries 次）→ SENT
取消（仅 SENT/ACKED）→ CANCELLED

完整迁移规则见《命令状态机.md》。

---

变更记录

版本	日期	变更内容	作者
V1.0 草案	2026-08-10	初稿：命令结构/类型/优先级/错误码	系统组