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