docs(ops): 深化保洁、安保核心链路与工单流转细节

开发者文档/02-Ops领域/00-Ops领域总览.md

@@ -1,9 +1,43 @@
-# Ops领域总览
+# 00-Ops领域总览
 
-## 目标与面向读者
-Ops 是当前第一阶段的核心业务，包括工单、保洁、安保等日常运营管理。本文档面向相关业务的产品与研发。
+本文档是 AIOT 平台 Ops（人工作业）领域的核心入口。
+Ops 领域是平台当前的第一阶段核心基本盘，主要处理由人执行的各项业务流转。
 
-## 子业务模块
-- **工单管理**：待补充方案。
-- **保洁管理**：待补充方案。
-- **安保管理**：待补充方案。
+## 一、业务边界定义
+
+**Ops 领域负责：**
+- 工单的完整生命周期管理（创建、派单、抢单、执行、挂起、验收）。
+- 具体业务场景的人工作业标准（如保洁打卡、安保巡检）。
+- 现场人员的排班与绩效数据基础收集。
+
+**Ops 领域绝不负责：**
+- **设备底层协议解析**：Ops 不关心设备是 MQTT 还是 HTTP 报文，它只接收 IoT 领域转化后的标准“事件”。
+- **硬件实时控制**：Ops 不直接发指令给设备，若工单需要反控设备，必须调用 IoT 领域的内部 API。
+- **财务计费结算**：Ops 只记录耗时和耗材，真正的结算和财务账单属于更上层的计费域。
+
+## 二、当前落地状态
+
+| 模块 | 状态 | 说明 |
+|------|------|------|
+| **基础工单状态机** | 🟢 已实现 | PENDING -> ACCEPT -> PROGRESS -> COMPLETED 闭环已通 |
+| **抢单/派单基础逻辑** | 🟢 已实现 | 基础区域派单与并发抢单控制（基于 Redis）已上 |
+| **安保巡检路线** | 🟡 建设中 | 基础空间树复用完成，防作弊打卡待深化 |
+| **保洁耗材管理** | 🟡 建设中 | 耗材库存扣减与工单的事务一致性仍在打磨 |
+| **智能派单算法** | 🔴 规划中 | 下阶段迭代，基于位置与手头任务数的智能派发 |
+| **复杂异常流转** | 🔴 规划中 | 超时自动退回、不可抗力挂起的补偿机制待完善 |
+
+## 三、下属核心文档阅读指引
+
+在深入具体业务前，请按以下顺序阅读：
+
+1. **[[01-工单生命周期与状态机.md]]**
+   - 必读。这是所有 Ops 业务的底层底座，搞懂了状态机，就搞懂了代码里的核心 Enum 和边界校验。
+2. **[[02-保洁业务核心链路.md]]**
+   - 偏向“抢单执行与过程留存”，重点看并发控制和防篡改。
+3. **[[03-安保业务核心链路.md]]**
+   - 偏向“空间巡检与突发响应”，重点看基于空间的点位设计和告警强推。
+
+## 四、协作约束
+
+- **状态机不可私增**：前端/移动端绝对禁止硬编码状态流转逻辑。所有合法状态流转必须由后端判断，任何新增状态必须先落文档。
+- **领域数据隔离**：Ops 模块查询设备信息时，允许在工单表冗余少数字段（如设备名、位置），禁止每次都跨模块 `JOIN` 设备表。

开发者文档/02-Ops领域/01-工单生命周期与状态机.md

@@ -1,72 +1,65 @@
-# 工单生命周期与状态机
+# 01-工单生命周期与状态机
 
-## 目标与范围
-本文档定义 Ops 工单的核心生命周期、状态流转规则及关键决策点。
+工单（Ticket）是 Ops 领域流转的核心实体。所有的保洁、安保、维修任务，最终在底层都是一个工单。
+保证状态机的严谨和健壮，是 Ops 系统的第一要务。
 
-面向：后端、测试、产品、移动端联调。
+## 一、核心状态流转图
 
-## 工单生命周期
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING_DISPATCH : 创建工单
 
-### 核心状态
-```
-草稿(Draft) → 待分配(Pending) → 已分配(Assigned) → 执行中(InProgress) → 待验收(Review) → 已完成(Completed)
-                    ↓                    ↓                  ↓
-               已取消(Cancelled)    已转派(Reassigned)   已驳回(Rejected)
+    PENDING_DISPATCH --> PENDING_ACCEPT : 自动派单/人工指派
+    PENDING_DISPATCH --> CANCELLED : 创建人取消
+
+    PENDING_ACCEPT --> IN_PROGRESS : 员工接单/抢单成功
+    PENDING_ACCEPT --> PENDING_DISPATCH : 员工拒单/超时未接单(回退)
+
+    IN_PROGRESS --> COMPLETED : 执行完工(提交结果)
+    IN_PROGRESS --> SUSPENDED : 遇到阻碍(挂起申请)
+    
+    SUSPENDED --> IN_PROGRESS : 阻碍解除(继续执行)
+    SUSPENDED --> TERMINATED : 无法修复/人工终止
+
+    COMPLETED --> VERIFIED : 验收通过(闭环)
+    COMPLETED --> IN_PROGRESS : 验收驳回(打回重做)
+
+    VERIFIED --> [*]
+    TERMINATED --> [*]
+    CANCELLED --> [*]
 ```
 
-### 状态定义
+## 二、状态说明与触发条件
 
-| 状态 | 定义 | 触发条件 |
-|------|------|----------|
-| 草稿 | 工单已创建但未发布 | 创建者保存草稿 |
-| 待分配 | 工单已发布，等待派单 | 草稿发布 / 自动触发 |
-| 已分配 | 工单已指派给执行人 | 派单成功 |
-| 执行中 | 执行人已接单并开始作业 | 执行人确认接单 |
-| 待验收 | 执行人提交完成，等待验收 | 执行人标记完成 |
-| 已完成 | 验收通过，工单闭环 | 验收人确认通过 |
-| 已取消 | 工单被取消，不再执行 | 创建者/管理员取消 |
-| 已转派 | 工单被转给其他执行人 | 原执行人转派 |
-| 已驳回 | 验收不通过，打回重做 | 验收人驳回 |
+| 状态枚举 | 状态名称 | 触发条件 / 操作者 | 核心业务校验 |
+|---------|----------|-----------------|--------------|
+| `PENDING_DISPATCH` | 待派单 | 系统创建 / 人工创建 | 判断触发源，决定是进入抢单池还是直接派单 |
+| `PENDING_ACCEPT` | 待接单 | 调度器派发给指定人/组 | 需记录派单超时时间，触发定时任务监控 |
+| `IN_PROGRESS` | 处理中 | 移动端点击“接单/抢单” | **并发控制**：校验此单是否已被他人抢走 |
+| `SUSPENDED` | 已挂起 | 移动端提交“挂起”并附原因 | 必须要求上传现场照片及挂起理由 |
+| `COMPLETED` | 已完工 | 移动端提交“完工” | 校验必填项（如对比照、耗材单、定位打卡） |
+| `VERIFIED` | 已验收 | 后台/主管点击“验收通过” | 触发最终的评价和绩效数据结算 |
+| `TERMINATED` | 已终止 | 管理员主动介入关闭 | 记录异常终止原因，解除相关设备锁定 |
+| `CANCELLED` | 已取消 | 派单前创建人主动撤销 | 只能在 `PENDING_DISPATCH` 阶段操作 |
 
-## 状态流转规则
+## 三、异常分支与补偿机制（当前难点）
 
-### 正向流程
-```
-待分配 → 已分配 → 执行中 → 待验收 → 已完成
-```
+状态机在理想情况下是顺畅的，但在实际业务中会遇到各种异常，代码实现必须处理以下分支：
 
-### 异常/分支流程
-- 待分配 → 已取消（创建者取消）
-- 已分配 → 已转派（执行人无法处理）
-- 已分配 → 已取消（管理员介入）
-- 执行中 → 已转派（执行人变更）
-- 待验收 → 已驳回（质量不达标）
-- 已驳回 → 执行中（重新执行）
+### 1. 超时自动退回（建设中）
+- **场景**：派单给保安 A，但 A 在 15 分钟内未点击接单（`PENDING_ACCEPT`）。
+- **处理**：定时任务扫描，将工单强行回退到 `PENDING_DISPATCH` 状态，触发重派或转派逻辑，并向主管发送告警。
 
-## 关键业务规则
+### 2. 抢单并发冲突（已实现）
+- **场景**：工单进入保洁抢单池，保洁 A 和 B 同时点击抢单。
+- **处理**：必须使用 Redis 分布式锁 `ops:ticket:grab:lock:{ticketId}`。只有一个能抢到并扭转为 `IN_PROGRESS`，另一个返回“手慢无”业务提示，**绝对禁止出现一单两人接**。
 
-### 派单规则
-1. 支持手动派单和自动派单两种模式
-2. 自动派单考虑：执行人负载、技能匹配、地理位置
-3. 派单失败进入待分配队列，等待重新派单
+### 3. 验收驳回的数据隔离（规划中）
+- **场景**：主管验收发现保洁不合格，驳回工单（`COMPLETED` -> `IN_PROGRESS`）。
+- **处理**：原有的完工照片和记录必须被作为“历史快照”存档，不能被新的执行记录直接物理覆盖，以便追溯整个返工过程。
 
-### 超时规则
-- 待分配超时：N 小时未分配，触发告警并升级
-- 执行中超时：超过预计工期，触发进度确认
-- 待验收超时：N 小时未验收，自动完成或升级
+## 四、研发规约
 
-### 优先级规则
-- P0：紧急，立即处理
-- P1：高优先级，当日完成
-- P2：普通，按排期处理
-- P3：低优先级，可延后
-
-## 与 IoT 的联动点
-- 工单创建可触发设备联动（如保洁工单自动解锁门禁）
-- 设备告警可自动生成工单
-- 工单完成可触发设备状态变更
-
-## 待补充
-- 具体超时时间阈值
-- 自动派单算法细节
-- 与具体业务（保洁/安保）的字段差异
+1. **状态流转绝对由后端控制**：移动端只负责发指令（如 `POST /ticket/accept`），具体变成什么状态由后端 Service 内的流转逻辑决定，前端根据返回的新状态重新渲染。
+2. **禁止跨级流转**：如直接从 `PENDING_DISPATCH` 跳到 `COMPLETED`，除非是特殊的 Mock 测试接口。
+3. **状态日志**：任何状态的跃迁，必须在表 `ops_ticket_log` 中记录：原状态、新状态、操作人、操作时间和变更备注。这是后期扯皮的唯一证据。

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

@@ -1,74 +1,43 @@
-# 保洁业务核心链路
+# 02-保洁业务核心链路
 
-## 目标与范围
-定义保洁业务从需求触发到服务完成的完整链路。
+保洁业务是基于 Ops 底层工单状态机的具体特化场景。
+它的业务核心诉求是：**快速响应、防作弊、规范留存。**
 
-## 业务触发场景
+## 一、派单与抢单策略
 
-### 场景一：计划保洁
-- 按固定周期自动生成保洁工单
-- 适用于日常保洁、周期性深度保洁
+保洁任务大多具有“区域化”和“即时性”特点，调度策略与安保不同。
 
-### 场景二：即时保洁
-- 现场发现问题，即时发起保洁请求
-- 适用于突发污渍、临时清洁需求
+### 1. 派单策略
+- **指定派发**：针对例行保洁（如每日清晨大扫除），由系统固定排班直接生成 `PENDING_ACCEPT` 工单发给指定保洁员。
+- **区域虚拟池抢单（当前主力）**：
+  - 针对突发保洁（如某洗手间漏水）。
+  - 工单生成后进入 `PENDING_DISPATCH`。
+  - 根据事发点位，向该楼层/区域关联的“保洁组”进行广播推送。
+- **智能调度（下阶段规划）**：未来将根据保洁员的实时定位距离、手头未完成工单数量进行加权打分，自动派给最优人选。
 
-### 场景三：告警触发
-- IoT 设备检测到异常（如地面水渍传感器）
-- 自动生成保洁工单并派单
+### 2. 并发抢单逻辑
+由于突发工单是广播的，抢单时的并发控制是红线：
+1. 移动端发起抢单请求。
+2. 后端拦截，尝试获取 Redis 锁 `ops:ticket:grab:lock:{ticketId}`。
+3. 锁获取成功后，校验工单当前状态是否仍为 `PENDING_DISPATCH`。
+4. **并发数限制校验**：检查该保洁员当前处于 `IN_PROGRESS` 状态的工单是否超过配置上限（如最多只能同时进行 3 弹任务）。
+5. 校验通过，写入接单人信息，状态扭转为 `IN_PROGRESS`。释放锁。
 
-## 核心链路流程
+## 二、执行反馈标准动作（防篡改）
 
-```
-触发 → 工单生成 → 派单 → 执行人接单 → 到达现场 → 执行保洁 → 完成提交 → 验收 → 闭环
-```
+保洁人员在现场执行完毕点击“完工”时，不能只是简单的状态更新，必须包含以下标准化材料的强制校验：
 
-### 详细步骤
+### 1. LBS 定位打卡校验
+- 点击完工时，必须随接口上报当前 GPS/WIFI 定位坐标。
+- 后端计算该坐标与工单要求点位的距离，超过设定阈值（如 100 米）则拒绝完工，防止“异地云完工”。
 
-| 阶段 | 关键动作 | 系统行为 | 移动端行为 |
-|------|----------|----------|------------|
-| 触发 | 计划/即时/告警 | 创建工单草稿 | - |
-| 工单生成 | 补充位置、保洁类型、要求 | 生成正式工单 | 推送通知 |
-| 派单 | 匹配执行人 | 计算最优执行人 | 发送接单提醒 |
-| 接单 | 执行人确认 | 状态变更为"执行中" | 显示工单详情 |
-| 到达现场 | 扫码/定位签到 | 记录到达时间 | 签到页面 |
-| 执行保洁 | 按标准作业 | 计时、可上传过程照片 | 作业指导、拍照 |
-| 完成提交 | 提交完成、上传结果 | 状态变更为"待验收" | 提交完成 |
-| 验收 | 验收人检查 | 验收通过/驳回 | 验收通知 |
-| 闭环 | 评价、归档 | 工单完成、数据统计 | - |
+### 2. 清理前后对比照（核心证据）
+- 必须强制上传至少两张照片：【清理前】与【清理后】。
+- **防篡改机制**：
+  - 照片上传在移动端层面必须限制“只能当场拍照”，禁止从相册挑选。
+  - 后端接收图片后，规划接入服务端统一打上不可逆的时间戳与定位水印。
 
-## 关键字段
-
-### 工单特有字段
-- 保洁类型：日常保洁 / 深度保洁 / 专项保洁
-- 保洁区域：具体位置、面积
-- 保洁标准：参考的保洁标准编号
-- 预计工时
-- 所需物料清单
-
-### 执行反馈字段
-- 实际开始时间
-- 实际完成时间
-- 现场照片（Before/After）
-- 异常情况说明
-- 物料消耗记录
-
-## 质量检查点
-
-### 执行前
-- 执行人资质确认
-- 物料准备确认
-- 现场安全确认
-
-### 执行中
-- 过程照片留痕
-- 关键节点打卡
-
-### 执行后
-- 验收标准对照
-- 客户满意度评价
-
-## 待补充
-- 具体保洁标准定义
-- 物料管理流程
-- 与 IoT 设备的联动细节（如清洁机器人）
+### 3. 耗材扣减（一致性难点）
+- 如果保洁使用了特殊耗材（如两瓶清洁剂），在完工时需同步勾选消耗量。
+- 后端在处理 `COMPLETED` 状态跃迁时，需开启数据库事务，同步扣减库存域（Inventory）的数量。
+- 若库存不足或发生死锁，工单完工事务必须一并回滚，保证数据强一致性。

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

@@ -1,92 +1,47 @@
-# 安保业务核心链路
+# 03-安保业务核心链路
 
-## 目标与范围
-定义安保业务从任务触发到完成巡逻/处理的完整链路。
+安保业务相比于保洁，更加注重**路线的规律性**与**突发事件的强响应**。
+它强依赖于系统的“空间树”基础数据。
 
-## 业务触发场景
+## 一、巡检点位与路线规划
 
-### 场景一：定时巡逻
-- 按预设路线和时间进行巡逻
-- 适用于日常安保、区域巡查
+安保日常工作的核心是“巡更”。
 
-### 场景二：事件响应
-- 接到告警或求助，立即响应
-- 适用于突发事件、紧急求助
+### 1. 空间树复用
+- 巡检点（Check Point）直接关联系统底层的“空间树（Space Tree）”节点（如 1栋-2层-弱电井）。
+- 每个巡检点在物理世界对应一个 NFC 贴片或专属二维码。
 
-### 场景三：定点值守
-- 在关键位置定点值守
-- 适用于出入口、重要区域
+### 2. 路线规划与生成
+- **路线（Route）**：由一系列有序的巡检点组成。
+- 系统通过定时任务（如每天凌晨 1 点），根据排班计划和预设路线，批量生成安保巡检工单。
+- 巡检工单在移动端显示为任务清单，安保人员需按照顺序依次前往各个点位进行扫码/碰一碰。
 
-## 核心链路流程
+### 3. 防作弊与漏检处理
+- 后端严格校验两次扫码的时间差：如果两个相距 500 米的巡检点，扫码间隔只有 5 秒，系统将判定为异常并自动打上 `SUSPICIOUS` 标签。
+- 到了规定时间未完成的点位，自动标记为“漏检”，并纳入该人员绩效扣分计算中。
 
-### 巡逻任务链路
-```
-计划生成 → 派单 → 开始巡逻 → 巡逻中（打点） → 巡逻完成 → 异常处理（如有） → 闭环
-```
+## 二、异常上报与流转路径
 
-### 事件响应链路
-```
-事件上报 → 工单生成 → 紧急派单 → 响应确认 → 现场处置 → 处置完成 → 上报结果 → 闭环
-```
+安保在巡检中不仅是“打卡”，更承担了“发现问题”的职能。
 
-## 详细步骤
+### 1. 巡检内异常上报
+- 安保扫码某个巡检点时，发现消防栓玻璃破裂。
+- 在移动端当前点位的巡检单中，直接点击【上报异常】。
+- 提交描述和照片后，该巡检点的状态变为【异常已记录】，但当前**巡检主工单仍可继续往下进行**。
 
-### 巡逻任务
+### 2. 派生维修工单
+- 上述异常提交后，系统后台会捕捉到这个动作。
+- 后端异步触发流转，自动**派生（Spawn）**出一个新的【维修工单】，归属到工程维修组。
+- 在数据关系上，该维修工单的 `parent_id` 或 `source_id` 指向安保的巡检单，形成追溯链路。
 
-| 阶段 | 关键动作 | 系统行为 | 移动端行为 |
-|------|----------|----------|------------|
-| 计划生成 | 按巡逻计划生成任务 | 创建巡逻工单 | 推送任务提醒 |
-| 派单 | 分配给巡逻人员 | 计算巡逻路线 | 显示巡逻路线 |
-| 开始巡逻 | 巡逻人员确认开始 | 开始计时、记录轨迹 | 巡逻模式启动 |
-| 巡逻中 | 按路线巡逻、打点 | 记录打点时间、位置 | 打点页面、轨迹记录 |
-| 巡逻完成 | 完成巡逻路线 | 计算完成率、用时 | 巡逻总结 |
-| 异常处理 | 发现异常上报 | 生成异常工单 | 异常上报页面 |
+## 三、突发事件（IoT联动）强推播
 
-### 事件响应
+这是安保业务防线中最关键的应急链路。当 IoT 领域传来如“烟雾报警”等严重异常时：
 
-| 阶段 | 关键动作 | 系统行为 | 移动端行为 |
-|------|----------|----------|------------|
-| 事件上报 | 告警/求助触发 | 生成紧急工单、高优先级 | 紧急通知 |
-| 紧急派单 | 立即指派最近安保人员 | 计算最优响应人员 | 紧急接单提醒 |
-| 响应确认 | 安保人员确认响应 | 开始计时 | 响应确认 |
-| 现场处置 | 到达现场、处置事件 | 记录到达时间、处置过程 | 处置记录、拍照 |
-| 处置完成 | 完成处置、提交结果 | 状态变更 | 提交完成 |
-| 上报结果 | 汇总处置情况 | 归档、统计 | - |
+### 1. 紧急工单生成
+- 后端接收到高优告警事件，直接绕过人工审核，自动生成等级为 `URGENT` 的安保应急工单。
 
-## 关键字段
-
-### 巡逻任务特有字段
-- 巡逻路线：预设路线编号
-- 巡逻点位：需打卡的关键点位
-- 巡逻频次：每日/每周次数
-- 巡逻时段：具体时间段
-
-### 事件响应特有字段
-- 事件类型：入侵/火灾/求助/设备故障/其他
-- 紧急程度：P0/P1/P2/P3
-- 事件位置：具体位置、坐标
-- 上报来源：IoT告警/人工上报/系统触发
-
-### 执行反馈字段
-- 实际巡逻轨迹
-- 打点记录（时间、位置、照片）
-- 异常情况描述
-- 处置措施记录
-- 现场照片/视频
-
-## 与 IoT 的联动
-
-### 触发联动
-- 门禁异常 → 自动生成巡逻任务
-- 视频监控告警 → 推送最近安保人员
-- 烟感/红外告警 → 紧急事件工单
-
-### 执行联动
-- 巡逻人员接近 → 自动解锁门禁
-- 紧急事件 → 联动广播、照明
-- 完成巡逻 → 自动布防
-
-## 待补充
-- 具体巡逻路线定义
-- 与视频监控系统的对接
-- 紧急事件升级机制
+### 2. LBS 强推播与锁定
+- 系统利用所有安保人员最后一次上传的 GPS 坐标，计算出距离事发点 500 米范围内的在线安保人员。
+- **强提醒**：向这些人的 App 发送最高优先级的 WebSocket 消息，拉起强制弹窗和震动报警。
+- **抢单锁定**：与保洁的普通抢单不同，这类紧急事件若 1 分钟内无人抢单，系统将强行指派给距离最近的安保，并通过自动拨打语音电话（规划中）进行通知，确保事件 100% 得到响应。