命令状态机

项目	内容
文档编号	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[] 不可变事件链，用于联调定位与测试记录核对：

{
  "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	初稿：命令状态定义/迁移表/超时重试/事件审计	系统组

4.9 KiB Raw Permalink Blame History Unescape Escape