109 lines
4.9 KiB
Markdown
109 lines
4.9 KiB
Markdown
# 命令状态机
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 文档编号 | 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 | 初稿：命令状态定义/迁移表/超时重试/事件审计 | 系统组 |
|