# 控制会话状态机

| 项目 | 内容 |
|------|------|
| 文档编号 | 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 | 初稿：会话状态/迁移表/互斥抢占规则 | 系统组 |