123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# 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 | 初稿：命令结构/类型/优先级/错误码 | 系统组 |
|