aiot-platform-cloud/.ralph/fix_plan.md

Ralph Fix Plan - 保洁巡检模块

需求文档

参考: docs/物业服务AIoT平台-保洁服务模块.md（模块二：巡检小程序后端）

High Priority

1. 数据库表 + DO + Mapper ✅

• 创建 ops_inspection_template 表及 SQL（巡检检查项模板）
• 创建 ops_inspection_record 表及 SQL（巡检主记录）
• 创建 ops_inspection_record_item 表及 SQL（巡检明细）
• 创建对应 DO 类: OpsInspectionTemplateDO, OpsInspectionRecordDO, OpsInspectionRecordItemDO
• 创建对应 Mapper: OpsInspectionTemplateMapper, OpsInspectionRecordMapper, OpsInspectionRecordItemMapper
• SQL: sql/mysql/aiot_ops_inspection.sql
• DO: environment-biz/dal/dataobject/inspection/
• Mapper: environment-biz/dal/mysql/inspection/

2. 巡检模板 CRUD（管理后台配置检查项） ✅

• InspectionTemplateService 接口 + Impl（增删改查，按 function_type 查询）
• InspectionTemplateController（管理端 REST API）
• 请求/响应 VO 类

3. 获取动态表单接口 ✅

• GET /admin-api/ops/inspection/template/list-by-area
  • 入参: area_id + detected_beacons（蓝牙指纹数组）
  • 逻辑: area_id → 查 ops_bus_area 获取 function_type → 查 ops_inspection_template 加载检查项
  • 返回: 检查项列表

4. 蓝牙位置校验逻辑 ✅

• InspectionLocationService（位置校验服务）
  • 入参: area_id + detected_beacons
  • 查询 ops_area_device_relation 获取该区域绑定的信标列表
  • 匹配算法: 至少1个绑定信标匹配，且 RSSI > 阈值
  • 返回: 校验通过/失败
• InspectionController + verify-location 端点
• DetectedBeaconVO, LocationVerifyResultVO

Medium Priority

5. 提交巡检结果接口

• POST /admin-api/ops/inspection/submit
  • 入参: area_id, is_location_exception, items[{template_id, is_passed, remark}]
  • 逻辑:
    1. 保存 ops_inspection_record 主记录
    2. 批量保存 ops_inspection_record_item 明细
    3. 判定 result_status: 任意一项 is_passed=false → 不合格
    4. 不合格时触发异步归属判定
• InspectionRecordService 接口 + Impl
• InspectionController（巡检提交 REST API）

6. 归属判定异步逻辑

• InspectionAttributionService（归属判定服务）
  • 以巡检提交时间为基点，回溯该区域上一个 COMPLETED 工单
  • 获取保洁员实际停留时长 T_stay（来自 ops_order.actual_duration 或工单扩展）
  • 获取区域标准时长 clean_threshold（来自 ops_bus_area.standard_duration）
  • 判定:
    • T_stay >= clean_threshold → attribution_result=2（突发状况），不扣分
    • T_stay < clean_threshold → attribution_result=1（个人责任），扣信用分
  • 更新 ops_inspection_record 的 attribution_result, last_order_id, stay_duration

7. 整改工单自动创建

• 不合格巡检触发创建整改派单
  • 调用现有 OpsOrderService / OrderLifecycleManager 创建工单
  • source_type = INSPECTION
  • 关联 generated_order_id 回写到 ops_inspection_record
  • 对接工单引擎的优先级和派单逻辑

Low Priority

• 巡检记录查询接口（分页、按区域/时间筛选）
• 巡检统计接口（合格率、不合格热点区域）

Completed

• 需求分析与表结构设计
• Task 1: 数据库表 + DO + Mapper（3表、3DO、3Mapper）
• Task 2: 巡检模板 CRUD（Service + Impl + Controller + VOs）
• Task 3: 获取动态表单接口（list-by-area，area_id → function_type → template 查询链路）
• Task 4: 蓝牙位置校验（InspectionLocationService + verify-location 端点）

Notes

• 巡检是保洁业务线内的子功能，代码放 viewsh-module-environment-biz
• 复用 ops_area_device_relation 做蓝牙信标校验，不新建 iot_device_location
• 复用 ops_bus_area.standard_duration 作为 clean_threshold，不新建 ops_rule_config
• Controller 放在 ops-server 模块的 controller/admin/inspection/ 下
• 遵循现有 CleanOrderService 的编码模式