XW-AIOT/aiot-document
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ops): 重构工单队列系统文档，补充区域楼层模型和区域优先派单策略

Browse Source
This commit is contained in:
lzh
2026-04-07 00:06:02 +08:00
parent 105455ae27
commit 4bd3b680a7
2 changed files with 53 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
开发者文档/02-Ops领域/02-保洁业务核心链路.md
View File

@@ -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 任务，继续推送
```

67
开发者文档/02-Ops领域/02-工单队列系统.md
View File

@@ -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`）的保洁员，实现跨楼层支援派单。
## 六、与工单状态机的协作
## 八、与工单状态机的协作
队列系统与工单状态机是**正交**的：
- **队列系统**：管理"工单在派单引擎中的排队生命周期"