From dec2b06d74a46e13f3a6f853f0ef7251c6d2fe65 Mon Sep 17 00:00:00 2001 From: lzh Date: Mon, 6 Apr 2026 23:01:05 +0800 Subject: [PATCH] =?UTF-8?q?docs(ops):=20=E6=B7=B1=E5=8C=96=E4=BF=9D?= =?UTF-8?q?=E6=B4=81=E3=80=81=E5=AE=89=E4=BF=9D=E6=A0=B8=E5=BF=83=E9=93=BE?= =?UTF-8?q?=E8=B7=AF=E4=B8=8E=E5=B7=A5=E5=8D=95=E6=B5=81=E8=BD=AC=E7=BB=86?= =?UTF-8?q?=E8=8A=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 开发者文档/02-Ops领域/00-Ops领域总览.md | 48 ++++++-- .../02-Ops领域/01-工单生命周期与状态机.md | 109 ++++++++--------- 开发者文档/02-Ops领域/02-保洁业务核心链路.md | 97 ++++++--------- 开发者文档/02-Ops领域/03-安保业务核心链路.md | 111 ++++++------------ 4 files changed, 158 insertions(+), 207 deletions(-) diff --git a/开发者文档/02-Ops领域/00-Ops领域总览.md b/开发者文档/02-Ops领域/00-Ops领域总览.md index 49d1e35..6bd9f6d 100644 --- a/开发者文档/02-Ops领域/00-Ops领域总览.md +++ b/开发者文档/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` 设备表。 \ No newline at end of file diff --git a/开发者文档/02-Ops领域/01-工单生命周期与状态机.md b/开发者文档/02-Ops领域/01-工单生命周期与状态机.md index 8e4031d..fd22fb4 100644 --- a/开发者文档/02-Ops领域/01-工单生命周期与状态机.md +++ b/开发者文档/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` 中记录：原状态、新状态、操作人、操作时间和变更备注。这是后期扯皮的唯一证据。 \ No newline at end of file diff --git a/开发者文档/02-Ops领域/02-保洁业务核心链路.md b/开发者文档/02-Ops领域/02-保洁业务核心链路.md index 468ce72..d1c4f76 100644 --- a/开发者文档/02-Ops领域/02-保洁业务核心链路.md +++ b/开发者文档/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）的数量。 +- 若库存不足或发生死锁，工单完工事务必须一并回滚，保证数据强一致性。 \ No newline at end of file diff --git a/开发者文档/02-Ops领域/03-安保业务核心链路.md b/开发者文档/02-Ops领域/03-安保业务核心链路.md index 5b532e9..24524ba 100644 --- a/开发者文档/02-Ops领域/03-安保业务核心链路.md +++ b/开发者文档/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% 得到响应。 \ No newline at end of file