# 命令状态机

| 项目 | 内容 |
|------|------|
| 文档编号 | DES-05 |
| 文档名称 | 命令状态机 |
| 版本 | V1.0 |
| 状态 | 已评审（Reviewed） |
| 适用系统 | 机器人智慧服务系统（命令服务 Alpha） |
| 编写日期 | 2026-08-10 |
| 关联文档 | DOC-09 控制命令字典、控制会话状态机、越权-冲突-超时测试记录 |

---

## 1. 概述

命令状态机定义控制命令从创建到终态的全部状态与迁移规则。**命令服务 Alpha（3030）** 已按本文档实现：每条命令携带 `status` 与 `events[]`（迁移审计链），超时自动重试，取消/重试受状态约束。

## 2. 命令状态定义（CMD-STATE）

| 状态 | 编码 | 说明 |
|------|------|------|
| 待发送 | `PENDING` | 命令已创建，排队等待下发（预留态） |
| 已下发 | `SENT` | 已发送至设备端，等待 ACK |
| 已确认 | `ACKED` | 设备已确认收到，准备执行 |
| 执行中 | `EXECUTING` | 设备正在执行 |
| 成功 | `SUCCEEDED` | 执行成功（终态） |
| 失败 | `FAILED` | 执行失败（终态，可手动重试） |
| 超时 | `TIMEOUT` | 超时未完成（终态，可手动重试） |
| 已取消 | `CANCELLED` | 用户取消/会话关闭（终态） |

## 3. 状态迁移图

```
                自动重试(≤maxRetries)
      ┌─────────────────────────────────┐
      │                                 ▼
创建 → PENDING → SENT ──ACK──→ ACKED ──exec──→ EXECUTING ──result──→ SUCCEEDED
                    │          │                    │
                    │cancel    │cancel              │result(failed)
                    ▼          ▼                    ▼
                 CANCELLED   CANCELLED            FAILED ──retry──→ SENT
                    ▲                                  ▲
                    │                                  │
                    └──── 会话关闭自动取消 ────────────┘
    TIMEOUT（超时且重试耗尽）──retry──→ SENT
```

## 4. 状态迁移表（CMD-TRANSITION）

| 当前状态 | 事件 | 目标状态 | 触发方 | 条件 / 动作 |
|----------|------|----------|--------|-------------|
| `PENDING` | `DISPATCH` | `SENT` | 平台 | 发送至设备通道 |
| `SENT` | `DEVICE_ACK` | `ACKED` | 设备 | 记录 ackAt；ACK 携带 `executing:true` 可直接进入 EXECUTING |
| `ACKED` | `EXEC_START` | `EXECUTING` | 设备 | 设备开始执行 |
| `EXECUTING` | `RESULT_OK` | `SUCCEEDED` | 设备 | `result{status:'success'}`；清除超时定时器 |
| `EXECUTING` | `RESULT_FAIL` | `FAILED` | 设备 | `result{status:'failed', errorCode}`；清除定时器 |
| `SENT`/`ACKED`/`EXECUTING` | `TIMEOUT` | `TIMEOUT` | 平台 | 超时；重试次数 < maxRetries 时先自动重试（→SENT） |
| `PENDING`/`SENT`/`ACKED` | `CANCEL` | `CANCELLED` | 用户/会话 | 仅非执行态可取消 |
| `TIMEOUT`/`FAILED` | `RETRY` | `SENT` | 用户 | 手动重试，retries+1 |
| 任意非终态 | `SESSION_CLOSE` | `CANCELLED` | 平台 | 控制会话关闭，自动取消未终态命令 |

## 5. 超时与重试策略（CMD-TIMEOUT）

| 参数 | 默认值 | 范围 | 说明 |
|------|--------|------|------|
| `timeoutMs` | 30000 | 1000~300000 | 从 SENT 起算，到达终态或 ACK+result 全流程的超时预算 |
| `maxRetries` | 1 | 0~3 | 超时自动重试次数；重试后重新计时 |
| 重试间隔 | 0（立即） | — | Alpha 版立即重发，后续版本可加指数退避 |

**计时规则：** 命令创建即启动定时器；进入 SUCCEEDED/FAILED/CANCELLED 时取消；自动重试与手动重试均重新启动定时器。

## 6. 命令事件审计（CMD-EVENT）

每条命令维护 `events[]` 不可变事件链，用于联调定位与测试记录核对：

```json
{
  "at": "2026-08-10T10:00:00.000Z",
  "from": "SENT",
  "to": "ACKED",
  "reason": "device_ack"
}
```

| reason 取值 | 说明 |
|-------------|------|
| `dispatch` | 创建下发 |
| `device_ack` | 设备确认 |
| `exec_start` | 开始执行 |
| `exec_result` | 结果回传 |
| `auto_retry` | 超时自动重试 |
| `manual_retry` | 用户手动重试 |
| `user_cancel` | 用户取消 |
| `timeout` | 超时终态 |

## 7. 与设备接入/状态服务的衔接

- **下发前置校验**：命令服务调用设备接入服务 `GET /api/devices/:id/online`，设备离线返回 `40902` 拒绝下发（设备接入服务不可达时降级放行）。
- **执行联动**：命令进入 EXECUTING 时，状态服务侧设备 `mode` 切换为 `working`/`patrol`；命令终态后恢复 `idle`（联调阶段由设备端模拟上报）。

---

**变更记录**

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| V1.0 | 2026-08-10 | 初稿：命令状态定义/迁移表/超时重试/事件审计 | 系统组 |