From 90cd2a73696a0ae947fa91770836d38a305eed5b Mon Sep 17 00:00:00 2001 From: lzh Date: Mon, 6 Apr 2026 23:27:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(ops):=20=E8=A1=A5=E5=85=85=E4=BF=9D?= =?UTF-8?q?=E6=B4=81=E5=B7=A5=E5=8D=95=E9=98=9F=E5=88=97=E5=AE=8C=E6=95=B4?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=EF=BC=8C=E5=BC=95=E5=85=A5OrderQueueStatusEn?= =?UTF-8?q?um=E3=80=81PriorityEnum=E5=92=8CqueueScore=E6=8E=92=E5=BA=8F?= =?UTF-8?q?=E6=9C=BA=E5=88=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 开发者文档/02-Ops领域/02-保洁业务核心链路.md | 139 ++++++++++++++----- 1 file changed, 103 insertions(+), 36 deletions(-) diff --git a/开发者文档/02-Ops领域/02-保洁业务核心链路.md b/开发者文档/02-Ops领域/02-保洁业务核心链路.md index cc9ea73..484b5f1 100644 --- a/开发者文档/02-Ops领域/02-保洁业务核心链路.md +++ b/开发者文档/02-Ops领域/02-保洁业务核心链路.md @@ -1,46 +1,113 @@ -# 02-人员状态与派单调度 +# 02-保洁业务核心链路 -在 AIOT 平台中，保洁员/安保人员不仅在系统中有一个虚拟账号，更绑定了物理世界中的实体装备（智能工牌 BADGE）。因此，调度系统不仅要看软件逻辑，还要看硬件状态。 +在 AIOT 平台中，保洁业务的核心不是简单的“抢单”，而是**基于智能工牌（BADGE）和工单队列（OrderQueue）的硬件级调度系统**。 -## 一、执行人员状态模型 (CleanerStatusEnum) +## 一、工单队列状态机 (`OrderQueueStatusEnum`) -执行人员（如保洁员）的状态通过 `CleanerStatusEnum` 严格定义，决定了他们能否接收新派单： +保洁业务引入了独立的队列状态，用于管理工单在派单引擎中的生命周期： -1. **`IDLE` (空闲)** - - 描述：当前无进行中的工单，可以接收新单。 - - `canAcceptNewOrder`：`true`。 -2. **`BUSY` (忙碌)** - - 描述：工单进入 `CONFIRMED`（已确认接单）后，保洁员自动转为忙碌。 - - `canAcceptNewOrder`：`false`。 - - 退出条件：工单 `COMPLETED` 后，系统检查该员工的队列，若有任务则保持 `BUSY`，若无任务才转回 `IDLE`。 -3. **`PAUSED` (暂停)** - - 描述：临时离开（如吃饭、休息），禁止派单。 -4. **`OFFLINE` (离线)** - - 描述：**硬件强绑定**。如果员工随身佩戴的智能工牌离线或失去心跳，系统直接将其判定为 `OFFLINE`，杜绝向无响应设备派单。 +```mermaid +stateDiagram-v2 + [*] --> WAITING : 工单入队 + + WAITING --> PROCESSING : 派单引擎分配 + WAITING --> REMOVED : 工单取消 + + PROCESSING --> PAUSED : P0紧急任务打断/临时离线 + PROCESSING --> REMOVED : 工单完成 + + PAUSED --> PROCESSING : 恢复执行 + PAUSED --> REMOVED : 工单取消 + + REMOVED --> [*] +``` -## 二、派单策略矩阵 (DispatchStrategyEnum) +### 队列状态与工单状态的映射关系 -系统不支持“一刀切”的分配，而是根据不同的业务场景，提供丰富的策略（共 8 种）： +| 队列状态 (`OrderQueueStatusEnum`) | 工单状态 (`WorkOrderStatusEnum`) | 说明 | +|----------------------------------|--------------------------------|------| +| `WAITING` (等待中) | `QUEUED` (排队中) | 工单已进入队列，等待派单引擎分配 | +| `PROCESSING` (处理中) | `DISPATCHED` / `CONFIRMED` / `ARRIVED` | 任务已下发，正在处理（包含已推送、已确认、已到岗任一状态） | +| `PAUSED` (暂停中) | `PAUSED` (已暂停) | 任务暂停（如 P0 紧急任务打断、保洁员临时离线） | +| `REMOVED` (已移除) | `COMPLETED` / `CANCELLED` | 任务已完成或已取消 | -### 1. 自动派单策略簇 (`isAuto() == true`) -由调度算法自动推送到工牌： -- **`AUTO` (自动派单)**：系统根据复合规则（优先级、区域、技能、工作量综合）自动分配。 -- **`AREA_PRIORITY` (区域优先)**：优先分配给负责该区域的人员（如固定楼层保洁）。 -- **`NEAREST` (最近距离)**：**LBS/信标定位强相关**。基于工牌实时上报的坐标，分配给距离事发点最近的人员。 -- **`SKILL_MATCH` (技能匹配)**：匹配人员标签（如需要“高空作业”或“特种维修”）。 -- **`WORKLOAD_BALANCE` (工作量平衡)**：平衡分配，避免旱的旱死涝的涝死。 -- **`ROUND_ROBIN` (轮询分配)**：按顺序轮流派发。 +## 二、工单队列数据结构 (`OrderQueueDTO`) -### 2. 人工介入策略簇 (`requireManualIntervention() == true`) -- **`MANUAL` (手动派单)**：管理员在后台指定。 -- **`GRAB` (抢单模式)**：放入工单池，允许相关人员主动抢单。 +每条队列记录包含以下核心字段，用于精确控制派单顺序和状态追踪： -## 三、事件领域架构 (EventDomainEnum) +### 身份关联字段 +- `userId`：保洁员用户 ID（执行人员 ID） +- `opsOrderId`：关联的工单 ID +- `deviceId`：智能工牌设备 ID（硬件强绑定） -后端的处理高度模块化和事件驱动，划分为 6 大领域： -- **`RULE` (规则引擎)**：主要负责把 IoT 设备的原始异动转化为工单触发源。 -- **`DISPATCH` (调度)**：执行上述派单策略，决定“把任务给谁”。 -- **`BADGE` (工牌)**：处理向员工推送信令、接收员工确认按键的硬件交互。 -- **`BEACON` (信标)**：处理员工到达现场的物理打卡（信标感应）。 -- **`SYSTEM` (系统)**：底层基础流转。 -- **`PERFORMANCE` (绩效)**：工单完成后，计算结算时效与工作量。 \ No newline at end of file +### 优先级与排序字段 +- `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