docs(ops): 补充保洁工单队列完整描述，引入OrderQueueStatusEnum、PriorityEnum和queueScore排序机制
This commit is contained in:
@@ -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` (绩效)**：工单完成后，计算结算时效与工作量。
|
||||
### 优先级与排序字段
|
||||
- `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 任务，继续推送
|
||||
```
|
||||
Reference in New Issue
Block a user