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

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

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

开发者文档/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：保洁工单排队
+### 场景 1：同楼层保洁工单排队
-保洁工单进入队列后，系统按 `queueScore` 排序，依次推送给保洁员的智能工牌。
+某楼层（`floorNo=2`）生成多个保洁工单，系统：
+1. 查询该楼层绑定的保洁员（`selectListByFloorNo`）
+2. 按 `queueScore` 排序入队
+3. 依次推送给保洁员的智能工牌
 
 ### 场景 2：紧急任务插队
-某区域发生溢水（P0 紧急），系统：
+某楼层发生溢水（P0 紧急），系统：
 1. 创建 P0 优先级工单并入队
-2. 查找距离最近的保洁员
+2. 查找该楼层距离最近的保洁员（或同区域保洁员）
 3. 如果该保洁员正在执行 P2 日常清洁，强制暂停当前任务
 4. 推送 P0 紧急任务到工牌
 5. 保洁员处理完 P0 后，自动恢复之前的 P2 任务
 
-### 场景 3：动态优先级调整
+### 场景 3：跨楼层支援
-某 VIP 客户投诉（原 P2 任务），客服手动升级为 P1：
+当某楼层无空闲保洁员时，系统可扩展查询相邻楼层（`floorNo=1` 或 `3`）的保洁员，实现跨楼层支援派单。
-- 调用 `adjustPriority` 修改队列记录的优先级
-- 重新计算 `queueScore`
-- 在下次派单时优先处理
 
-## 六、与工单状态机的协作
+## 八、与工单状态机的协作
 
 队列系统与工单状态机是**正交**的：
 - **队列系统**：管理"工单在派单引擎中的排队生命周期"