diff --git a/开发者文档/02-Ops领域/02-工单队列系统.md b/开发者文档/02-Ops领域/02-工单队列系统.md index c373af1..83490c2 100644 --- 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`（工单）。 \ No newline at end of file +| 优先级 | 描述 | 可打断 | +|--------|------|--------| +| P0 | 紧急任务 | 是 | +| P1 | 重要任务 | 否 | +| P2 | 普通任务 | 否 | +| P3 | 低优任务 | 否 | \ No newline at end of file