docs(ops): 精简工单队列文档，只保留源码中真实存在的内容

2026-04-07 00:14:55 +08:00
parent 4bd3b680a7
commit 3e7e10f3cc
1 changed files with 54 additions and 144 deletions
--- a/开发者文档/02-Ops领域/02-工单队列系统.md
+++ b/开发者文档/02-Ops领域/02-工单队列系统.md
@@ -1,164 +1,74 @@
 # 02-工单队列系统

-工单队列系统是 AIOT 平台 Ops 领域的**公共基础设施**，用于管理所有需要排队调度的工单（目前主要用于保洁业务）。
-
-它解决了"多个工单如何有序分配给执行人员"以及"紧急任务如何插队"的核心问题。
+工单队列系统是 AIOT 平台 Ops 领域的公共基础设施，用于管理工单的排队与分配。

 ## 一、队列状态机 (`OrderQueueStatusEnum`)

-工单队列拥有独立于工单状态的**队列生命周期状态**：
+工单队列的生命周期状态：

-```mermaid
-stateDiagram-v2
-    [*] --> WAITING : 工单入队
-    
-    WAITING --> PROCESSING : 派单引擎分配
-    WAITING --> REMOVED : 工单取消
-    
-    PROCESSING --> PAUSED : P0紧急任务打断/临时离线
-    PROCESSING --> REMOVED : 工单完成
-    
-    PAUSED --> PROCESSING : 恢复执行
-    PAUSED --> REMOVED : 工单取消
-    
-    REMOVED --> [*]
-```
+| 队列状态 | 说明 | 对应工单状态 |
+|---------|------|-------------|
+| `WAITING` | 等待中 | `QUEUED` |
+| `PROCESSING` | 处理中 | `DISPATCHED`/`CONFIRMED`/`ARRIVED` |
+| `PAUSED` | 暂停中 | `PAUSED` |
+| `REMOVED` | 已移除 | `COMPLETED`/`CANCELLED` |

-### 队列状态与工单状态的映射关系
+## 二、队列数据结构 (`OrderQueueDTO`)

-| 队列状态 (`OrderQueueStatusEnum`) | 工单状态 (`WorkOrderStatusEnum`) | 说明 |
-|----------------------------------|--------------------------------|------|
-| `WAITING` (等待中) | `QUEUED` (排队中) | 工单已进入队列，等待派单引擎分配 |
-| `PROCESSING` (处理中) | `DISPATCHED` / `CONFIRMED` / `ARRIVED` | 任务已下发，正在处理（包含已推送、已确认、已到岗任一状态） |
-| `PAUSED` (暂停中) | `PAUSED` (已暂停) | 任务暂停（如 P0 紧急任务打断、执行人员临时离线） |
-| `REMOVED` (已移除) | `COMPLETED` / `CANCELLED` | 任务已完成或已取消 |
-
-## 二、工单队列数据结构 (`OrderQueueDTO`)
-
-每条队列记录包含以下核心字段：
-
-### 身份关联字段
- `userId`：执行人员用户 ID
- `opsOrderId`：关联的工单 ID
- `deviceId`：智能工牌设备 ID（硬件强绑定，保洁业务特有）
-
-### 优先级与排序字段
- `priority`：优先级（`0=P0紧急`, `1=P1重要`, `2=P2普通`, `3=P3低优`）
- `queueIndex`：队列顺序（1 表示最高优先级）
- `queueScore`：**队列分数（核心排序算法）**
-  - 计算公式：`优先级分数 + 时间戳`
-  - P0: `0 + timestamp`
-  - P1: `1000000 + timestamp`
-  - P2: `2000000 + timestamp`
-  - P3: `3000000 + timestamp`
-  - **效果**：优先级高的排在前面，同优先级按入队时间排序
-
-### 时间追踪字段
+核心字段：
+- `userId`：执行人员ID
+- `opsOrderId`：工单ID
+- `deviceId`：工牌设备ID
+- `priority`：优先级（0=P0, 1=P1, 2=P2, 3=P3）
+- `queueScore`：队列分数 = 优先级分数 + 时间戳
 - `enqueueTime`：入队时间
- `dequeueTime`：出队时间（工单开始执行时间）
- `pausedDuration`：累计暂停时长（秒）
+- `queueStatus`：队列状态

-## 三、区域与楼层模型 (`OpsBusAreaDO`)
+## 三、区域模型 (`OpsBusAreaDO`)

-工单队列系统与**业务区域（Area）**深度绑定，区域按层级划分为：
+区域层级（`AreaTypeEnum`）：
+- `PARK`：园区
+- `BUILDING`：楼栋
+- `FLOOR`：楼层
+- `FUNCTION`：功能区域

-### 区域类型 (`AreaTypeEnum`)
-| 类型 | 说明 | 示例 |
-|------|------|------|
-| `PARK` | 园区 | 整个科技园区 |
-| `BUILDING` | 楼栋 | A栋、B栋 |
-| `FLOOR` | 楼层 | 2楼、-1楼（地下一层） |
-| `FUNCTION` | 功能区域 | 男卫、女卫、电梯厅、茶水间 |
+核心字段：
+- `parentId`/`parentPath`：区域树
+- `floorNo`：楼层号
+- `areaLevel`：区域等级（HIGH/MEDIUM/LOW）
+- `standardDuration`：标准保洁时长（分钟）

-### 区域核心属性
- `parentId` / `parentPath`：区域树结构（如 `1/2/3` 表示园区/楼栋/楼层）
- `floorNo`：**楼层号**（如 2、-1），用于按楼层查询和派单
- `areaLevel`：区域等级（`HIGH`/`MEDIUM`/`LOW`），影响派单优先级
- `standardDuration`：标准保洁时长（分钟），用于巡检归属判定
- `cleaningFrequency`：保洁频率（次/天）
+## 四、派单策略 (`BadgeDeviceAreaAssignStrategy`)

-## 四、区域优先派单策略 (`CleanerAreaAssignStrategy`)
+**当前启用的策略**：工牌设备区域优先分配

-工单队列系统支持**区域优先**的派单策略：
+### 派单流程
+1. 查询该区域的工牌设备（`listBadgesByArea`）
+2. 过滤在线设备（`isOnline`）
+3. 选择最佳设备：
+   - P0紧急：优先`canAcceptNewOrder`（IDLE）、电量充足、心跳最新
+   - 普通任务：优先IDLE，无IDLE则选等待队列少的BUSY设备

-### 派单规则
-1. **同区域优先**：优先分配给负责该区域的保洁员（`listCleanersByArea`）
-2. **楼层匹配**：通过 `floorNo` 查询同楼层的保洁员
-3. **状态过滤**：排除 `OFFLINE`（离线）状态的保洁员
-4. **P0 紧急任务**：优先选择 `IDLE`（空闲）状态，且电量充足、心跳最新的保洁员
-5. **普通任务**：
-   - 优先选择 `IDLE` 状态的保洁员
-   - 无空闲时，选择等待队列较少的 `BUSY`（忙碌）保洁员
+### 推荐评分
+- 基础分：50
+- 状态分：可接单+30，忙碌+10
+- 电量分：>80%+15，>50%+10，>20%+5
+- 心跳分：5分钟内+5

-### 推荐评分算法 (`calculateScore`)
-系统为每个候选保洁员计算推荐分数（0-100）：
- **基础分**：50 分
- **状态分**：`IDLE` +30 分，`BUSY` +10 分
- **电量分**：>80% +15 分，>50% +10 分，>20% +5 分
- **心跳分**：5 分钟内有心跳 +5 分
+## 五、核心操作 (`OrderQueueService`)

-## 五、优先级策略 (`PriorityEnum`)
+- `enqueue`：入队
+- `dequeue`：出队
+- `startExecution`：开始执行
+- `pauseTask`/`resumeTask`：暂停/恢复
+- `adjustPriority`：调整优先级
+- `getWaitingTasksByUserId`：获取等待中任务

-系统支持 4 级优先级，P0 具有特殊打断能力：
+## 六、优先级 (`PriorityEnum`)

-| 优先级 | 描述 | 队列排序权重 | 可打断当前任务 |
-|--------|------|------------|--------------|
-| `P0` | 紧急任务（溢水、危险品泄漏、严重安全事故） | 0 | **是** (`canInterrupt=true`) |
-| `P1` | 重要任务（VIP 客户投诉、重要访客接待） | 1 | 否 |
-| `P2` | 普通任务（日常清洁超时、周期性保养） | 2 | 否 |
-| `P3` | 低优任务（日常巡检、例行清洁） | 3 | 否 |
-
-### P0 紧急任务的打断机制
-当 P0 任务入队时，如果目标执行人员正在执行 P1/P2/P3 任务：
-1. 当前任务被强制暂停（`PROCESSING` -> `PAUSED`）
-2. P0 任务插队执行
-3. P0 完成后，被暂停的任务自动恢复（`PAUSED` -> `PROCESSING`）
-
-## 六、队列核心操作 (`OrderQueueService`)
-
-### 基础生命周期操作
- `enqueue(opsOrderId, userId, priority, queueIndex)`：工单入队
- `dequeue(queueId)` / `dequeueByOpsOrderId(opsOrderId)`：工单出队（完成/取消时）
- `startExecution(queueId)`：开始执行（`WAITING` -> `PROCESSING`）
- `pauseTask(queueId)`：暂停任务（`PROCESSING` -> `PAUSED`）
- `resumeTask(queueId)`：恢复任务（`PAUSED` -> `PROCESSING`）
-
-### 优先级动态调整
- `adjustPriority(queueId, newPriority, reason)`：调整优先级（用于紧急插队）
- `upgradeToUrgent(opsOrderId, reason)`：升级为 P0 紧急任务
-
-### 查询接口
- `getWaitingTasksByUserId(userId)`：获取用户的等待中任务（按 `queueScore` 排序）
- `getInterruptedTasksByUserId(userId)`：获取用户的暂停任务（按暂停时间排序）
- `getCurrentTaskByUserId(userId)`：获取用户当前执行的任务
-
-## 七、使用场景
-
-### 场景 1：同楼层保洁工单排队
-某楼层（`floorNo=2`）生成多个保洁工单，系统：
-1. 查询该楼层绑定的保洁员（`selectListByFloorNo`）
-2. 按 `queueScore` 排序入队
-3. 依次推送给保洁员的智能工牌
-
-### 场景 2：紧急任务插队
-某楼层发生溢水（P0 紧急），系统：
-1. 创建 P0 优先级工单并入队
-2. 查找该楼层距离最近的保洁员（或同区域保洁员）
-3. 如果该保洁员正在执行 P2 日常清洁，强制暂停当前任务
-4. 推送 P0 紧急任务到工牌
-5. 保洁员处理完 P0 后，自动恢复之前的 P2 任务
-
-### 场景 3：跨楼层支援
-当某楼层无空闲保洁员时，系统可扩展查询相邻楼层（`floorNo=1` 或 `3`）的保洁员，实现跨楼层支援派单。
-
-## 八、与工单状态机的协作
-
-队列系统与工单状态机是**正交**的：
- **队列系统**：管理"工单在派单引擎中的排队生命周期"
- **工单状态机**：管理"工单本身的业务状态流转"
-
-一个工单可以同时拥有：
- 队列状态：`PROCESSING`（正在队列中执行）
- 工单状态：`CONFIRMED`（已确认接单）或 `ARRIVED`（已到岗）
-
-当工单完成时，两者同步变为 `REMOVED`（队列）和 `COMPLETED`（工单）。
+| 优先级 | 描述 | 可打断 |
+|--------|------|--------|
+| P0 | 紧急任务 | 是 |
+| P1 | 重要任务 | 否 |
+| P2 | 普通任务 | 否 |
+| P3 | 低优任务 | 否 |