From 4bd3b680a71fe43ccb4366090bc8f65836b02ec2 Mon Sep 17 00:00:00 2001 From: lzh Date: Tue, 7 Apr 2026 00:06:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(ops):=20=E9=87=8D=E6=9E=84=E5=B7=A5?= =?UTF-8?q?=E5=8D=95=E9=98=9F=E5=88=97=E7=B3=BB=E7=BB=9F=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=8C=E8=A1=A5=E5=85=85=E5=8C=BA=E5=9F=9F=E6=A5=BC=E5=B1=82?= =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E5=92=8C=E5=8C=BA=E5=9F=9F=E4=BC=98=E5=85=88?= =?UTF-8?q?=E6=B4=BE=E5=8D=95=E7=AD=96=E7=95=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 开发者文档/02-Ops领域/02-保洁业务核心链路.md | 113 ------------------- 开发者文档/02-Ops领域/02-工单队列系统.md | 67 ++++++++--- 2 files changed, 53 insertions(+), 127 deletions(-) delete mode 100644 开发者文档/02-Ops领域/02-保洁业务核心链路.md diff --git a/开发者文档/02-Ops领域/02-保洁业务核心链路.md b/开发者文档/02-Ops领域/02-保洁业务核心链路.md deleted file mode 100644 index 484b5f1..0000000 --- a/开发者文档/02-Ops领域/02-保洁业务核心链路.md +++ /dev/null @@ -1,113 +0,0 @@ -# 02-保洁业务核心链路 - -在 AIOT 平台中，保洁业务的核心不是简单的“抢单”，而是**基于智能工牌（BADGE）和工单队列（OrderQueue）的硬件级调度系统**。 - -## 一、工单队列状态机 (`OrderQueueStatusEnum`) - -保洁业务引入了独立的队列状态，用于管理工单在派单引擎中的生命周期： - -```mermaid -stateDiagram-v2 - [*] --> WAITING : 工单入队 - - WAITING --> PROCESSING : 派单引擎分配 - WAITING --> REMOVED : 工单取消 - - PROCESSING --> PAUSED : P0紧急任务打断/临时离线 - PROCESSING --> REMOVED : 工单完成 - - PAUSED --> PROCESSING : 恢复执行 - PAUSED --> REMOVED : 工单取消 - - REMOVED --> [*] -``` - -### 队列状态与工单状态的映射关系 - -| 队列状态 (`OrderQueueStatusEnum`) | 工单状态 (`WorkOrderStatusEnum`) | 说明 | -|----------------------------------|--------------------------------|------| -| `WAITING` (等待中) | `QUEUED` (排队中) | 工单已进入队列，等待派单引擎分配 | -| `PROCESSING` (处理中) | `DISPATCHED` / `CONFIRMED` / `ARRIVED` | 任务已下发，正在处理（包含已推送、已确认、已到岗任一状态） | -| `PAUSED` (暂停中) | `PAUSED` (已暂停) | 任务暂停（如 P0 紧急任务打断、保洁员临时离线） | -| `REMOVED` (已移除) | `COMPLETED` / `CANCELLED` | 任务已完成或已取消 | - -## 二、工单队列数据结构 (`OrderQueueDTO`) - -每条队列记录包含以下核心字段，用于精确控制派单顺序和状态追踪： - -### 身份关联字段 -- `userId`：保洁员用户 ID（执行人员 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` - - **效果**：优先级高的排在前面，同优先级按入队时间排序 - -### 时间追踪字段 -- `enqueueTime`：入队时间 -- `dequeueTime`：出队时间（工单开始执行时间） -- `pausedDuration`：累计暂停时长（秒） - -## 三、优先级策略 (`PriorityEnum`) - -系统支持 4 级优先级，P0 具有特殊打断能力： - -| 优先级 | 描述 | 队列排序权重 | 可打断当前任务 | -|--------|------|------------|--------------| -| `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)`：获取用户当前执行的任务 - -## 五、硬件联动：智能工牌（BADGE） - -队列系统与智能工牌深度绑定： - -1. **入队即推送**：工单入队后，系统通过 `OrderQueueService.enqueue` 将指令推送到保洁员的智能工牌（`deviceId`） -2. **按键确认**：保洁员在工牌上按键确认后，队列状态从 `WAITING` 变为 `PROCESSING`，同时工单状态变为 `CONFIRMED` -3. **信标打卡**：保洁员到达现场，工牌感应信标后，工单状态变为 `ARRIVED` -4. **离线检测**：如果工牌离线（`CleanerStatusEnum.OFFLINE`），当前任务自动暂停（`PROCESSING` -> `PAUSED`） - -## 六、队列与工单的完整流转示例 - -``` -1. 规则引擎生成保洁工单 -> 工单状态: PENDING -2. 调度引擎分配保洁员 -> 工单状态: QUEUED, 队列状态: WAITING -3. 推送至智能工牌 -> 工单状态: DISPATCHED -4. 保洁员按键确认 -> 工单状态: CONFIRMED, 队列状态: PROCESSING -5. 到达现场信标打卡 -> 工单状态: ARRIVED -6. 作业完成 -> 工单状态: COMPLETED, 队列状态: REMOVED -7. 系统自动检查该保洁员队列 -> 如有 WAITING 任务，继续推送 -``` \ No newline at end of file diff --git a/开发者文档/02-Ops领域/02-工单队列系统.md b/开发者文档/02-Ops领域/02-工单队列系统.md index 23369fb..c373af1 100644 --- a/开发者文档/02-Ops领域/02-工单队列系统.md +++ b/开发者文档/02-Ops领域/02-工单队列系统.md @@ -33,7 +33,7 @@ stateDiagram-v2 | `PAUSED` (暂停中) | `PAUSED` (已暂停) | 任务暂停（如 P0 紧急任务打断、执行人员临时离线） | | `REMOVED` (已移除) | `COMPLETED` / `CANCELLED` | 任务已完成或已取消 | -## 二、队列数据结构 (`OrderQueueDTO`) +## 二、工单队列数据结构 (`OrderQueueDTO`) 每条队列记录包含以下核心字段： @@ -58,7 +58,46 @@ stateDiagram-v2 - `dequeueTime`：出队时间（工单开始执行时间） - `pausedDuration`：累计暂停时长（秒） -## 三、优先级策略 (`PriorityEnum`) +## 三、区域与楼层模型 (`OpsBusAreaDO`) + +工单队列系统与**业务区域（Area）**深度绑定，区域按层级划分为： + +### 区域类型 (`AreaTypeEnum`) +| 类型 | 说明 | 示例 | +|------|------|------| +| `PARK` | 园区 | 整个科技园区 | +| `BUILDING` | 楼栋 | A栋、B栋 | +| `FLOOR` | 楼层 | 2楼、-1楼（地下一层） | +| `FUNCTION` | 功能区域 | 男卫、女卫、电梯厅、茶水间 | + +### 区域核心属性 +- `parentId` / `parentPath`：区域树结构（如 `1/2/3` 表示园区/楼栋/楼层） +- `floorNo`：**楼层号**（如 2、-1），用于按楼层查询和派单 +- `areaLevel`：区域等级（`HIGH`/`MEDIUM`/`LOW`），影响派单优先级 +- `standardDuration`：标准保洁时长（分钟），用于巡检归属判定 +- `cleaningFrequency`：保洁频率（次/天） + +## 四、区域优先派单策略 (`CleanerAreaAssignStrategy`) + +工单队列系统支持**区域优先**的派单策略： + +### 派单规则 +1. **同区域优先**：优先分配给负责该区域的保洁员（`listCleanersByArea`） +2. **楼层匹配**：通过 `floorNo` 查询同楼层的保洁员 +3. **状态过滤**：排除 `OFFLINE`（离线）状态的保洁员 +4. **P0 紧急任务**：优先选择 `IDLE`（空闲）状态，且电量充足、心跳最新的保洁员 +5. **普通任务**： + - 优先选择 `IDLE` 状态的保洁员 + - 无空闲时，选择等待队列较少的 `BUSY`（忙碌）保洁员 + +### 推荐评分算法 (`calculateScore`) +系统为每个候选保洁员计算推荐分数（0-100）： +- **基础分**：50 分 +- **状态分**：`IDLE` +30 分，`BUSY` +10 分 +- **电量分**：>80% +15 分，>50% +10 分，>20% +5 分 +- **心跳分**：5 分钟内有心跳 +5 分 + +## 五、优先级策略 (`PriorityEnum`) 系统支持 4 级优先级，P0 具有特殊打断能力： @@ -75,7 +114,7 @@ stateDiagram-v2 2. P0 任务插队执行 3. P0 完成后，被暂停的任务自动恢复（`PAUSED` -> `PROCESSING`） -## 四、队列核心操作 (`OrderQueueService`) +## 六、队列核心操作 (`OrderQueueService`) ### 基础生命周期操作 - `enqueue(opsOrderId, userId, priority, queueIndex)`：工单入队 @@ -93,26 +132,26 @@ stateDiagram-v2 - `getInterruptedTasksByUserId(userId)`：获取用户的暂停任务（按暂停时间排序） - `getCurrentTaskByUserId(userId)`：获取用户当前执行的任务 -## 五、使用场景 +## 七、使用场景 -### 场景 1：保洁工单排队 -保洁工单进入队列后，系统按 `queueScore` 排序，依次推送给保洁员的智能工牌。 +### 场景 1：同楼层保洁工单排队 +某楼层（`floorNo=2`）生成多个保洁工单，系统： +1. 查询该楼层绑定的保洁员（`selectListByFloorNo`） +2. 按 `queueScore` 排序入队 +3. 依次推送给保洁员的智能工牌 ### 场景 2：紧急任务插队 -某区域发生溢水（P0 紧急），系统： +某楼层发生溢水（P0 紧急），系统： 1. 创建 P0 优先级工单并入队 -2. 查找距离最近的保洁员 +2. 查找该楼层距离最近的保洁员（或同区域保洁员） 3. 如果该保洁员正在执行 P2 日常清洁，强制暂停当前任务 4. 推送 P0 紧急任务到工牌 5. 保洁员处理完 P0 后，自动恢复之前的 P2 任务 -### 场景 3：动态优先级调整 -某 VIP 客户投诉（原 P2 任务），客服手动升级为 P1： -- 调用 `adjustPriority` 修改队列记录的优先级 -- 重新计算 `queueScore` -- 在下次派单时优先处理 +### 场景 3：跨楼层支援 +当某楼层无空闲保洁员时，系统可扩展查询相邻楼层（`floorNo=1` 或 `3`）的保洁员，实现跨楼层支援派单。 -## 六、与工单状态机的协作 +## 八、与工单状态机的协作 队列系统与工单状态机是**正交**的： - **队列系统**：管理"工单在派单引擎中的排队生命周期"