diff --git a/开发者文档/02-Ops领域/01-工单生命周期与状态机.md b/开发者文档/02-Ops领域/01-工单生命周期与状态机.md index fd22fb4..5f50c93 100644 --- a/开发者文档/02-Ops领域/01-工单生命周期与状态机.md +++ b/开发者文档/02-Ops领域/01-工单生命周期与状态机.md @@ -1,65 +1,59 @@ # 01-工单生命周期与状态机 -工单（Ticket）是 Ops 领域流转的核心实体。所有的保洁、安保、维修任务，最终在底层都是一个工单。 -保证状态机的严谨和健壮，是 Ops 系统的第一要务。 +工单（WorkOrder）是 Ops 领域的核心实体。本项目中的 Ops 不是传统的“手机 App 抢单”模式，而是**深度整合硬件（智能工牌 BADGE、感知信标 BEACON）**的物联网级调度系统。 -## 一、核心状态流转图 +## 一、核心状态流转图 (WorkOrderStatusEnum) + +根据 `WorkOrderStatusEnum.java`，工单的完整状态流转如下： ```mermaid stateDiagram-v2 - [*] --> PENDING_DISPATCH : 创建工单 - - PENDING_DISPATCH --> PENDING_ACCEPT : 自动派单/人工指派 - PENDING_DISPATCH --> CANCELLED : 创建人取消 - - PENDING_ACCEPT --> IN_PROGRESS : 员工接单/抢单成功 - PENDING_ACCEPT --> PENDING_DISPATCH : 员工拒单/超时未接单(回退) - - IN_PROGRESS --> COMPLETED : 执行完工(提交结果) - IN_PROGRESS --> SUSPENDED : 遇到阻碍(挂起申请) + [*] --> PENDING : 生成工单(待分配) - SUSPENDED --> IN_PROGRESS : 阻碍解除(继续执行) - SUSPENDED --> TERMINATED : 无法修复/人工终止 - - COMPLETED --> VERIFIED : 验收通过(闭环) - COMPLETED --> IN_PROGRESS : 验收驳回(打回重做) - - VERIFIED --> [*] - TERMINATED --> [*] + PENDING --> QUEUED : 进入派单队列(保洁特有) + PENDING --> DISPATCHED : 直接推送 + QUEUED --> DISPATCHED : 推送到智能工牌(已推送) + + DISPATCHED --> CONFIRMED : 员工按键确认(已确认) + DISPATCHED --> CANCELLED : 调度超时/撤回 + + CONFIRMED --> ARRIVED : 徽章感应到信标(已到岗) + CONFIRMED --> PAUSED : 临时暂停 + + ARRIVED --> COMPLETED : 作业完成或丢失信号(已完成) + ARRIVED --> PAUSED : 临时暂停 + + PAUSED --> ARRIVED : 恢复作业 + PAUSED --> CONFIRMED : 恢复作业(信标未感知) + + PENDING --> CANCELLED : 取消 + CONFIRMED --> CANCELLED : 取消 + + COMPLETED --> [*] CANCELLED --> [*] ``` -## 二、状态说明与触发条件 +## 二、状态说明与底层硬件联动 -| 状态枚举 | 状态名称 | 触发条件 / 操作者 | 核心业务校验 | -|---------|----------|-----------------|--------------| -| `PENDING_DISPATCH` | 待派单 | 系统创建 / 人工创建 | 判断触发源，决定是进入抢单池还是直接派单 | -| `PENDING_ACCEPT` | 待接单 | 调度器派发给指定人/组 | 需记录派单超时时间，触发定时任务监控 | -| `IN_PROGRESS` | 处理中 | 移动端点击“接单/抢单” | **并发控制**：校验此单是否已被他人抢走 | -| `SUSPENDED` | 已挂起 | 移动端提交“挂起”并附原因 | 必须要求上传现场照片及挂起理由 | -| `COMPLETED` | 已完工 | 移动端提交“完工” | 校验必填项（如对比照、耗材单、定位打卡） | -| `VERIFIED` | 已验收 | 后台/主管点击“验收通过” | 触发最终的评价和绩效数据结算 | -| `TERMINATED` | 已终止 | 管理员主动介入关闭 | 记录异常终止原因，解除相关设备锁定 | -| `CANCELLED` | 已取消 | 派单前创建人主动撤销 | 只能在 `PENDING_DISPATCH` 阶段操作 | +在本项目中，工单状态的变化直接对应了**物理硬件的事件 (EventDomainEnum)**。 -## 三、异常分支与补偿机制（当前难点） +| 状态码 (`status`) | 状态描述 | 触发源与硬件联动逻辑 | +|-----------------|----------|----------------------| +| `PENDING` | 待分配 | 规则引擎(`RULE`)、客服等触发生成工单。 | +| `QUEUED` | 排队中 | **保洁特有**：已推荐保洁员，在队列中等待推送。 | +| `DISPATCHED` | 已推送 | 调度器(`DISPATCH`)将指令下发到**智能工牌(`BADGE`)**。工牌可能震动或亮起。 | +| `CONFIRMED` | 已确认 | 保洁员在智能工牌上**按下确认按钮**。此时触发状态流转。 | +| `ARRIVED` | 已到岗 | **核心特性**：员工到达现场，工牌扫描/感应到现场的**感知信标(`BEACON`)**，自动流转为作业中。 | +| `PAUSED` | 已暂停 | 员工临时离开信标区域或主动暂停。 | +| `COMPLETED`| 已完成 | 作业完成（可通过工牌按键或离开信标一定时间自动结算）。 | +| `CANCELLED`| 已取消 | 中途取消（可随时发起，除终态外）。 | -状态机在理想情况下是顺畅的，但在实际业务中会遇到各种异常，代码实现必须处理以下分支： +## 三、业务判断约束 (代码级) -### 1. 超时自动退回（建设中） -- **场景**：派单给保安 A，但 A 在 15 分钟内未点击接单（`PENDING_ACCEPT`）。 -- **处理**：定时任务扫描，将工单强行回退到 `PENDING_DISPATCH` 状态，触发重派或转派逻辑，并向主管发送告警。 +所有状态跃迁受限于枚举类中的硬性校验： +1. `isCleaningBusinessStatus()`：`QUEUED`、`DISPATCHED`、`CONFIRMED` 属于保洁业务强相关的分发状态。 +2. `canConfirm()`：只有处于 `DISPATCHED`（已推送）状态的工单，才允许保洁员进行硬件按键确认。 +3. `canStartWorking()`：`CONFIRMED` 或 `DISPATCHED` 状态下，一旦感应到信标，都可以开始作业（兼容特殊直接到场场景）。 +4. `canComplete()`：必须先达到 `ARRIVED`（已到岗）状态，才允许扭转为 `COMPLETED`。 -### 2. 抢单并发冲突（已实现） -- **场景**：工单进入保洁抢单池，保洁 A 和 B 同时点击抢单。 -- **处理**：必须使用 Redis 分布式锁 `ops:ticket:grab:lock:{ticketId}`。只有一个能抢到并扭转为 `IN_PROGRESS`，另一个返回“手慢无”业务提示，**绝对禁止出现一单两人接**。 - -### 3. 验收驳回的数据隔离（规划中） -- **场景**：主管验收发现保洁不合格，驳回工单（`COMPLETED` -> `IN_PROGRESS`）。 -- **处理**：原有的完工照片和记录必须被作为“历史快照”存档，不能被新的执行记录直接物理覆盖，以便追溯整个返工过程。 - -## 四、研发规约 - -1. **状态流转绝对由后端控制**：移动端只负责发指令（如 `POST /ticket/accept`），具体变成什么状态由后端 Service 内的流转逻辑决定，前端根据返回的新状态重新渲染。 -2. **禁止跨级流转**：如直接从 `PENDING_DISPATCH` 跳到 `COMPLETED`，除非是特殊的 Mock 测试接口。 -3. **状态日志**：任何状态的跃迁，必须在表 `ops_ticket_log` 中记录：原状态、新状态、操作人、操作时间和变更备注。这是后期扯皮的唯一证据。 \ No newline at end of file +这保证了员工**必须亲自到达物理现场（信标打卡）**才能完成工单，杜绝了远程虚假完工。 \ No newline at end of file diff --git a/开发者文档/02-Ops领域/02-保洁业务核心链路.md b/开发者文档/02-Ops领域/02-保洁业务核心链路.md index d1c4f76..cc9ea73 100644 --- a/开发者文档/02-Ops领域/02-保洁业务核心链路.md +++ b/开发者文档/02-Ops领域/02-保洁业务核心链路.md @@ -1,43 +1,46 @@ -# 02-保洁业务核心链路 +# 02-人员状态与派单调度 -保洁业务是基于 Ops 底层工单状态机的具体特化场景。 -它的业务核心诉求是：**快速响应、防作弊、规范留存。** +在 AIOT 平台中，保洁员/安保人员不仅在系统中有一个虚拟账号，更绑定了物理世界中的实体装备（智能工牌 BADGE）。因此，调度系统不仅要看软件逻辑，还要看硬件状态。 -## 一、派单与抢单策略 +## 一、执行人员状态模型 (CleanerStatusEnum) -保洁任务大多具有“区域化”和“即时性”特点，调度策略与安保不同。 +执行人员（如保洁员）的状态通过 `CleanerStatusEnum` 严格定义，决定了他们能否接收新派单： -### 1. 派单策略 -- **指定派发**：针对例行保洁（如每日清晨大扫除），由系统固定排班直接生成 `PENDING_ACCEPT` 工单发给指定保洁员。 -- **区域虚拟池抢单（当前主力）**： - - 针对突发保洁（如某洗手间漏水）。 - - 工单生成后进入 `PENDING_DISPATCH`。 - - 根据事发点位，向该楼层/区域关联的“保洁组”进行广播推送。 -- **智能调度（下阶段规划）**：未来将根据保洁员的实时定位距离、手头未完成工单数量进行加权打分，自动派给最优人选。 +1. **`IDLE` (空闲)** + - 描述：当前无进行中的工单，可以接收新单。 + - `canAcceptNewOrder`：`true`。 +2. **`BUSY` (忙碌)** + - 描述：工单进入 `CONFIRMED`（已确认接单）后，保洁员自动转为忙碌。 + - `canAcceptNewOrder`：`false`。 + - 退出条件：工单 `COMPLETED` 后，系统检查该员工的队列，若有任务则保持 `BUSY`，若无任务才转回 `IDLE`。 +3. **`PAUSED` (暂停)** + - 描述：临时离开（如吃饭、休息），禁止派单。 +4. **`OFFLINE` (离线)** + - 描述：**硬件强绑定**。如果员工随身佩戴的智能工牌离线或失去心跳，系统直接将其判定为 `OFFLINE`，杜绝向无响应设备派单。 -### 2. 并发抢单逻辑 -由于突发工单是广播的，抢单时的并发控制是红线： -1. 移动端发起抢单请求。 -2. 后端拦截，尝试获取 Redis 锁 `ops:ticket:grab:lock:{ticketId}`。 -3. 锁获取成功后，校验工单当前状态是否仍为 `PENDING_DISPATCH`。 -4. **并发数限制校验**：检查该保洁员当前处于 `IN_PROGRESS` 状态的工单是否超过配置上限（如最多只能同时进行 3 弹任务）。 -5. 校验通过，写入接单人信息，状态扭转为 `IN_PROGRESS`。释放锁。 +## 二、派单策略矩阵 (DispatchStrategyEnum) -## 二、执行反馈标准动作（防篡改） +系统不支持“一刀切”的分配，而是根据不同的业务场景，提供丰富的策略（共 8 种）： -保洁人员在现场执行完毕点击“完工”时，不能只是简单的状态更新，必须包含以下标准化材料的强制校验： +### 1. 自动派单策略簇 (`isAuto() == true`) +由调度算法自动推送到工牌： +- **`AUTO` (自动派单)**：系统根据复合规则（优先级、区域、技能、工作量综合）自动分配。 +- **`AREA_PRIORITY` (区域优先)**：优先分配给负责该区域的人员（如固定楼层保洁）。 +- **`NEAREST` (最近距离)**：**LBS/信标定位强相关**。基于工牌实时上报的坐标，分配给距离事发点最近的人员。 +- **`SKILL_MATCH` (技能匹配)**：匹配人员标签（如需要“高空作业”或“特种维修”）。 +- **`WORKLOAD_BALANCE` (工作量平衡)**：平衡分配，避免旱的旱死涝的涝死。 +- **`ROUND_ROBIN` (轮询分配)**：按顺序轮流派发。 -### 1. LBS 定位打卡校验 -- 点击完工时，必须随接口上报当前 GPS/WIFI 定位坐标。 -- 后端计算该坐标与工单要求点位的距离，超过设定阈值（如 100 米）则拒绝完工，防止“异地云完工”。 +### 2. 人工介入策略簇 (`requireManualIntervention() == true`) +- **`MANUAL` (手动派单)**：管理员在后台指定。 +- **`GRAB` (抢单模式)**：放入工单池，允许相关人员主动抢单。 -### 2. 清理前后对比照（核心证据） -- 必须强制上传至少两张照片：【清理前】与【清理后】。 -- **防篡改机制**： - - 照片上传在移动端层面必须限制“只能当场拍照”，禁止从相册挑选。 - - 后端接收图片后，规划接入服务端统一打上不可逆的时间戳与定位水印。 +## 三、事件领域架构 (EventDomainEnum) -### 3. 耗材扣减（一致性难点） -- 如果保洁使用了特殊耗材（如两瓶清洁剂），在完工时需同步勾选消耗量。 -- 后端在处理 `COMPLETED` 状态跃迁时，需开启数据库事务，同步扣减库存域（Inventory）的数量。 -- 若库存不足或发生死锁，工单完工事务必须一并回滚，保证数据强一致性。 \ No newline at end of file +后端的处理高度模块化和事件驱动，划分为 6 大领域： +- **`RULE` (规则引擎)**：主要负责把 IoT 设备的原始异动转化为工单触发源。 +- **`DISPATCH` (调度)**：执行上述派单策略，决定“把任务给谁”。 +- **`BADGE` (工牌)**：处理向员工推送信令、接收员工确认按键的硬件交互。 +- **`BEACON` (信标)**：处理员工到达现场的物理打卡（信标感应）。 +- **`SYSTEM` (系统)**：底层基础流转。 +- **`PERFORMANCE` (绩效)**：工单完成后，计算结算时效与工作量。 \ No newline at end of file