web-Iot/docs/控制会话状态机.md

控制会话状态机

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

---

1. 概述

控制会话（Control Session）描述 操作员 ↔ 设备 之间的实时控制连接生命周期。会话是"命令下发"的前置条件：只有会话处于 ESTABLISHED 状态时，才允许下发互斥类控制命令（move/rotate/task_start 等）。

2. 会话状态定义（CS-STATE）

状态	编码	说明
空闲	IDLE	无会话，设备未被任何操作员控制
连接中	CONNECTING	客户端发起 AUTH 握手，等待设备确认
已建立	ESTABLISHED	握手完成，操作员持有控制权，可下发命令
忙	BUSY	会话建立但设备正在执行互斥命令（命令状态机 EXECUTING）
挂起	SUSPENDED	网络抖动/设备暂时不可控，会话保留待恢复
已关闭	CLOSED	会话终止（超时/主动断开/被抢占），控制权释放

3. 状态迁移图

        AUTH 握手成功
IDLE ────────────────→ ESTABLISHED
  ↑                      │  │
  │ 释放/超时            │  │ 下发互斥命令
  │                      │  ▼
CLOSED ←── 超时/抢占 ── BUSY
  ↑                      │
  │ 主动断开/设备离线     │ 命令完成（SUCCEEDED/FAILED/TIMEOUT）
  └──────────────────────┴──────────────→ ESTABLISHED

ESTABLISHED ── 网络抖动/设备忙 ──→ SUSPENDED ── 恢复/超时 ──→ ESTABLISHED / CLOSED

4. 状态迁移表（CS-TRANSITION）

当前状态	事件	目标状态	条件 / 动作
IDLE	AUTH_REQ	CONNECTING	客户端发送 AUTH 包 {type:'AUTH', token, userName, deviceId}
CONNECTING	AUTH_OK	ESTABLISHED	设备确认；记录 owner、sessionId，启动保活计时
CONNECTING	AUTH_FAIL	IDLE	token 无效/越权 → 拒绝连接，记审计日志
CONNECTING	TIMEOUT	IDLE	握手超时（5s 无 AUTH_OK）
ESTABLISHED	CMD_DISPATCH	BUSY	下发互斥命令成功（move/rotate/task_start）
BUSY	CMD_FINISH	ESTABLISHED	命令进入终态（SUCCEEDED/FAILED/TIMEOUT）
ESTABLISHED/BUSY	LINK_DEGRADE	SUSPENDED	网络 RTT 超阈值/设备无响应；暂停命令下发
SUSPENDED	LINK_RECOVER	ESTABLISHED	链路恢复，继续未完成任务
SUSPENDED	RESUME_TIMEOUT	CLOSED	挂起超时（30s）未恢复 → 释放控制权
任意非终态	CLOSE	CLOSED	操作员主动释放 / 设备离线 / 被抢占
CLOSED	REOPEN	CONNECTING	重新申请控制权

5. 会话互斥与抢占（CS-MUTEX）

规则编号	规则	说明
CS-M1	一机一会话	同一设备同时仅允许 1 个 ESTABLISHED 会话
CS-M2	抢占需授权	新操作员申请控制权时，若已有会话：仅 admin 可强制抢占，原会话收到 PRECEDED 后关闭；普通用户收到 403 设备被占用
CS-M3	会话与命令联动	会话 CLOSED 时，该设备 PENDING/SENT 命令自动取消（CANCELLED）
CS-M4	会话保活	客户端每 10s 发送保活帧；30s 无帧 → 判定链路断开，SUSPENDED→CLOSED

6. 会话对象字段（CS-OBJECT）

字段	类型	说明
sessionId	string	UUID，会话唯一标识
deviceId	string	目标设备
owner	string	持有控制权的操作员账号
role	enum	admin / operator / viewer
state	enum	见 §2
currentCommandId	string	当前执行中命令（BUSY 时非空）
createdAt / updatedAt	datetime	会话时间戳
closedReason	enum	user_close / timeout / preempted / device_offline / auth_fail

7. 与命令状态机的衔接

会话 ESTABLISHED + 下发 move ──→ 命令状态机: SENT → ACKED → EXECUTING（会话→BUSY）
命令 SUCCEEDED/FAILED/TIMEOUT ──→ 会话 BUSY→ESTABLISHED
会话 CLOSED ──→ 未终态命令 → CANCELLED

---

变更记录

版本	日期	变更内容	作者
V1.0	2026-08-10	初稿：会话状态/迁移表/互斥抢占规则	系统组