docs(ops): 新增保洁巡检业务文档，剖析基于蓝牙信标的LBS校验及基于停留时长的归属判定算法

开发者文档/02-Ops领域/04-保洁巡检与归属判定链路.md

@@ -0,0 +1,76 @@
+# 04-保洁巡检与归属判定链路
+
+在 AIOT 平台的 Ops 领域中，**保洁巡检（Inspection）**不是简单地填个表单，而是一套闭环的“质量控制与责任追溯”体系。巡检不仅负责发现问题，还负责通过算法判定责任归属，并自动化驱动后续的整改工单。
+
+本文档基于 `viewsh-module-environment-biz` 的底层代码，梳理完整的巡检业务逻辑。
+
+## 一、巡检执行与位置防伪验证
+
+巡检员到达现场并提交巡检结果时，系统首先要解决“云巡检（不在现场假打卡）”的问题。这依靠与现场**蓝牙信标（BEACON）**的联动实现。
+
+### 1. 基于蓝牙信标的 LBS 强校验 (`verifyLocation`)
+- 巡检员的移动端设备（App / 智能工牌）在进入区域时，会扫描周围的蓝牙信标，并将感知到的设备列表（`DetectedBeaconVO`，含 MAC 地址和信号强度 RSSI）打包上报。
+- 后端通过 `OpsAreaDeviceRelationDO` 查询该区域绑定的法定信标（`RELATION_TYPE_BEACON`）。
+- **校验逻辑**：上传的信标列表中，必须有至少一个信标的 MAC 地址与后台绑定的设备一致，且信号强度（RSSI）必须大于设定的距离阈值，才能证明巡检员“确实站在了该区域内”。
+
+### 2. 巡检结果判定 (`submitInspection`)
+- 后端通过 `OpsInspectionTemplateDO` 拉取该区域的巡检模版（检查项列表）。
+- 巡检员逐项提交通过/不通过状态。
+- **一票否决制**：所有检查项中只要有任意一项被标记为“不合格（`isPassed = false`）”，则整个区域的巡检结果判定为 **不合格（`RESULT_STATUS_FAILED`）**。
+
+## 二、异步归属判定核心算法 (Attribution)
+
+当巡检结果为“不合格”时，系统必须解答一个核心问题：**这是刚打扫完又被弄脏了（突发状况），还是上一个保洁员根本没好好打扫（个人责任）？**
+
+系统在事务提交后，通过 `InspectionAsyncHandler` 异步触发**归属判定 (`InspectionAttributionService`)**：
+
+```mermaid
+flowchart TD
+    Start[巡检判定为不合格] --> Async[异步触发归属判定]
+    Async --> FindLastOrder[追溯该区域最近一个 COMPLETED 的保洁工单]
+    
+    FindLastOrder --> Check{是否找到该工单?}
+    Check -- 否 --> Normal[归属判定：正常 (无责任人)]
+    Check -- 是 --> CalcDuration[获取该单保洁员实际停留时长 T_stay]
+    
+    CalcDuration --> GetStandard[获取该区域配置的标准保洁时长 T_standard]
+    GetStandard --> Compare{T_stay >= T_standard ?}
+    
+    Compare -- 是 (达标) --> Emergency[归属判定：突发状况]
+    Compare -- 否 (不达标) --> Personal[归属判定：个人责任]
+    
+    Emergency --> Mark[记录责任与扣分]
+    Personal --> Mark
+```
+
+### 1. 个人责任 (`ATTRIBUTION_PERSONAL = 1`)
+- **条件**：保洁员在执行上一个工单时，实际停留的时长（`stayDurationSeconds`）**小于**该区域配置的标准时长（`standardDurationSeconds`）。
+- **业务意义**：保洁员“走马观花”，未按要求做满时间，导致巡检不合格，属于个人失职（通常会联动扣减绩效或信用分）。
+
+### 2. 突发状况 (`ATTRIBUTION_EMERGENCY = 2`)
+- **条件**：保洁员的实际停留时长**大于或等于**标准时长。
+- **业务意义**：保洁员已经做足了标准时间，尽到了责任。此次巡检不合格是因为环境的不可控变化（如刚扫完又有人泼了咖啡），保洁员免责。
+
+## 三、自动整改派单机制 (Rectification)
+
+追责是为了绩效，但现场的脏乱差必须立即解决。因此，无论归属判定的结果是谁的责任，系统都会强制触发**整改派单 (`InspectionRectificationService`)**。
+
+### 1. 派生整改工单 (`CleanOrderAutoCreateReqDTO`)
+当巡检不合格时，系统会自动在后台调用派单引擎，派生一张特殊的整改工单：
+- **工单类型 (`OrderType`)**：保洁 (`CLEAN`)
+- **触发源 (`SourceType`)**：巡检系统 (`INSPECTION`)
+- **优先级 (`Priority`)**：**P1 (重要级别)**，确保该整改单优先于日常任务被派发。
+- **保洁类型 (`CleaningType`)**：点位突发保洁 (`SPOT`)
+- **难度等级**：设定为较高的 3 级。
+
+### 2. 关联追溯
+生成的整改工单 ID（`generatedOrderId`）会反向写回 `OpsInspectionRecordDO` 的记录中。
+这就在数据链条上形成了完整的闭环：
+`巡检记录 (发现问题) -> 归属判定 (定责) -> 整改工单 (解决问题)`
+
+## 四、小结
+
+保洁巡检并非孤立的业务，它与**IoT 蓝牙信标底座**及**工单队列调度**深度结合：
+1. **IoT 兜底真实性**：防远程打卡。
+2. **算法兜底公平性**：用停留时长数据作为判责依据，减少人为口角。
+3. **自动化兜底响应率**：机器自动生成 P1 工单，秒级流转入抢单/派单队列，实现全自动的闭环闭管。