houqin-java/docs/02-功能清单-小程序端/03-巡检相关功能.md

# 巡检相关功能

> 模块编码：inspection
> 端侧：小程序
> 关联文档：01-模块划分.md §3.2、02-功能清单-小程序端.md §3、03-业务流转逻辑-小程序端.md §3、05-接口规范.md §9.2、06-项目技术要求.md §4.4&5.4

## 功能概览

| 项目 | 说明 |
|------|------|
| 菜单名称 | 巡检相关功能 |
| 子菜单 | 今日巡检任务、蓝牙强制打卡、巡检执行、异常上报、巡检历史、异常数据补录 |
| 功能编号 | MP-I-01 ~ MP-I-06 |
| 权限编码 | inspection:plan:* / inspection:task:* 等 |

## 页面清单

### 页面1：今日巡检任务列表

- **页面路径**：`/pages/inspection/today-tasks`
- **页面元素**：
  - 今日任务统计（待执行/已完成/异常）
  - 任务列表
  - 下拉刷新
- **查询条件**：无（自动加载当日任务）
- **列表字段**：
  | 字段 | 说明 |
  |------|------|
  | 任务名称 | 巡检计划名称 |
  | 巡检区域 | 区域名称 |
  | 计划时间 | 开始~结束时间 |
  | 任务状态 | 待执行/进行中/已完成/异常 |
  | 蓝牙打卡状态 | 未打卡/已打卡 |
  | 异常数量 | 异常项数量（红色标记） |
- **界面布局**：
  - 顶部：统计卡片（待执行/已完成/异常 三列数字）
  - 中部：任务卡片列表
    - 卡片顶部：任务名称 + 状态标签
    - 卡片中部：巡检区域 + 计划时间
    - 卡片底部：蓝牙打卡状态 + 异常数量
  - 底部：无更多数据提示
- **操作按钮**：
  | 按钮 | 权限 | 说明 |
  |------|------|------|
  | 开始巡检 | inspection:task:view | 跳转巡检执行页 |
  | 查看详情 | inspection:task:view | 已完成的任务查看详情 |

### 页面2：蓝牙打卡页

- **页面路径**：`/pages/inspection/bluetooth-checkin`
- **页面元素**：
  - 蓝牙扫描动画
  - 当前扫描状态提示
  - 检测到的Beacon列表（如多个）
  - 打卡结果提示
  - 补录入口
- **界面布局**：
  - 顶部：蓝牙扫描状态（扫描动画 + 文字提示）
  - 中部：Beacon信息展示
    - Beacon名称
    - UUID
    - 信号强度（RSSI）
    - 连接状态
  - 底部：打卡结果 + 重试/补录按钮
- **操作按钮**：
  | 按钮 | 权限 | 说明 |
  |------|------|------|
  | 重新扫描 | — | 蓝牙扫描超时后可重试（最多3次） |
  | 进入补录模式 | — | 蓝牙无法连接时，进入补录模式 |

### 页面3：巡检执行页

- **页面路径**：`/pages/inspection/execute`
- **页面元素**：
  - 巡检清单列表（逐项检查）
  - 每项检查项：正常/异常选择
  - 异常项附加信息（拍照+严重等级+描述）
  - 打卡状态指示
  - 进度指示（已检查/总数）
- **查询条件**：无
- **列表字段**：
  | 字段 | 说明 |
  |------|------|
  | 检查项序号 | 序号标识 |
  | 检查项名称 | 巡检清单项 |
  | 检查结果 | 正常(绿)/异常(红)/未检查(灰) |
  | 严重等级 | 异常时显示：一般/较重/严重 |
- **界面布局**：
  - 顶部：进度条（已检查/总数）+ 蓝牙连接状态指示
  - 中部：检查项列表
    - 每项：序号 + 名称 + 正常/异常切换
    - 异常项展开：严重等级选择 + 描述输入 + 拍照上传
  - 底部：提交巡检结果按钮
- **操作按钮**：
  | 按钮 | 权限 | 说明 |
  |------|------|------|
  | 标记正常 | — | 当前项标记为正常 |
  | 标记异常 | — | 当前项标记为异常，展开附加信息 |
  | 拍照上传 | — | 异常项拍照（蓝牙策略=REQUIRED时须在蓝牙连接下拍照） |
  | 一键生成报修 | — | 异常项可直接生成报修工单（数据写入报修模块） |
  | 提交巡检结果 | inspection:task:view | 提交巡检记录 |

### 页面4：异常上报页

- **页面路径**：`/pages/inspection/report-abnormal`
- **页面元素**：
  - 异常描述（多行文本，必填）
  - 严重等级选择（一般/较重/严重）
  - 照片上传（最多9张，含水印时间定位）
  - 是否生成报修工单（开关）
  - 报修类型选择（生成工单时）
- **界面布局**：
  - 顶部：严重等级选择（三档按钮）
  - 中部：异常描述输入 + 照片上传网格
  - 下部：生成报修工单开关 + 报修类型选择
  - 底部：提交上报按钮
- **操作按钮**：
  | 按钮 | 权限 | 说明 |
  |------|------|------|
  | 拍照上传 | — | 拍摄异常照片 |
  | 提交上报 | — | 上报异常，如选择生成工单则同时创建报修工单 |

### 页面5：巡检历史列表

- **页面路径**：`/pages/inspection/history`
- **页面元素**：
  - 日期选择器（按月切换）
  - 巡检记录列表
  - 下拉刷新 + 上拉加载
- **查询条件**：
  | 条件 | 类型 | 说明 |
  |------|------|------|
  | 月份 | 月份选择器 | 按月筛选巡检记录 |
- **列表字段**：
  | 字段 | 说明 |
  |------|------|
  | 巡检日期 | 日期时间 |
  | 巡检区域 | 区域名称 |
  | 打卡方式 | 蓝牙/手动/补录 |
  | 检查项总数 | 总计 |
  | 异常数 | 异常项数量 |
  | 状态 | 正常/异常 |
- **界面布局**：
  - 顶部：月份选择器
  - 中部：巡检记录卡片列表
    - 卡片顶部：日期 + 状态标签
    - 卡片中部：区域 + 打卡方式
    - 卡片底部：检查项总数 + 异常数
- **操作按钮**：
  | 按钮 | 权限 | 说明 |
  |------|------|------|
  | 查看详情 | inspection:task:view | 查看巡检记录详情 |

### 页面6：异常数据补录页

- **页面路径**：`/pages/inspection/supplement`
- **页面元素**：
  - 补录原因选择（下拉：蓝牙失灵/定位失败/系统异常/其他）
  - 补录说明（多行文本，必填）
  - 证明材料上传（照片，最多3张）
  - 巡检记录补录表单
    - 巡检时间（手动选择）
    - 巡检区域
    - 检查项结果（逐项填写）
- **界面布局**：
  - 顶部：补录原因选择 + 说明
  - 中部：证明材料上传
  - 下部：巡检记录补录表单
  - 底部：提交补录申请按钮
- **操作按钮**：
  | 按钮 | 权限 | 说明 |
  |------|------|------|
  | 提交补录申请 | — | 提交后等待主管审核 |

## 需求追溯

| 功能点编号 | 功能名称 | 文档来源 | 后续服务 | 关联功能 |
|------------|----------|----------|----------|----------|
| MP-I-01 | 今日巡检任务 | 02-小程序端 §3 | 查看任务→开始巡检→蓝牙打卡 | 巡检计划（Web端） |
| MP-I-02 | 蓝牙强制打卡 | 02-小程序端 §3 | 打卡成功→记录check_type=BLUETOOTH→开始巡检 | 蓝牙策略配置 |
| MP-I-03 | 巡检执行 | 02-小程序端 §3 | 逐项检查→记录正常/异常→提交 | 巡检计划清单 |
| MP-I-04 | 异常上报 | 02-小程序端 §3 | 上报→可一键生成报修工单→通知主管 | 在线报修（报修工单） |
| MP-I-05 | 巡检历史 | 02-小程序端 §3 | 查看个人历史巡检记录 | 统计报表 |
| MP-I-06 | 异常数据补录 | 02-小程序端 §3 | 提交补录→主管审核→审核通过后数据生效 | 补录审核（Web+小程序） |

## 业务规则

1. **蓝牙策略规则**（06-项目技术要求.md §4.4）：
   - 策略=REQUIRED（强制蓝牙）：
     - 必须连接蓝牙Beacon后才可打卡
     - 拍照也须在蓝牙连接状态下进行
     - 蓝牙扫描超时3秒，重试3次
     - 未检测到蓝牙 → 提示"未检测到蓝牙信号" → 可重试或进入补录模式
     - 打卡记录 `check_type=BLUETOOTH`
   - 策略=OPTIONAL（非强制蓝牙）：
     - 用户选择打卡方式：蓝牙打卡或手动打卡
     - 手动打卡：`check_type=MANUAL`

2. **蓝牙连接判定**（06-项目技术要求.md §5.4）：
   - **不判断距离，只要成功连接蓝牙设备即可打卡**
   - 信号阈值：RSSI > -70dBm（可配置，仅用于判定是否能建立连接）
   - 扫描超时：3秒
   - 重试次数：3次

3. **蓝牙策略查询**（03-业务流转逻辑-小程序端 §3）：
   - 数据来源：`GET /system/bluetooth-policy → inspection_check_in`（打卡策略）
   - 数据来源：`GET /system/bluetooth-policy → inspection_photo`（拍照策略）

4. **异常上报关联报修**（03-业务流转逻辑-小程序端 §3）：
   - 异常上报时可一键生成报修工单
   - 数据写入报修模块（INSPECTION_ABNORMAL事件 → repair模块消费）

5. **补录数据规则**（06-项目技术要求.md §4.5）：
   - 补录数据必须标记 `is_supplement=true`
   - 补录原因必填
   - 需主管审核（Web+小程序均可审核）

6. **数据权限**（01-模块划分.md §1.3）：
   - 巡检人员：仅本人巡检数据
   - 主管：本班组巡检数据

## 状态流转

### 巡检任务状态流转

```
待执行 ──[蓝牙打卡]──▶ 进行中 ──[逐项检查]──▶ 已完成
  │                      │
  │                      └──[发现异常]──▶ 异常（可一键报修）
  │
  └──[蓝牙失败]──▶ 补录模式 ──[手动填写]──▶ 待审核 ──[主管通过]──▶ 已完成
                                                            └──[主管驳回]──▶ 已驳回
```

### 蓝牙打卡流程

```
开始打卡
    │
查询蓝牙策略（inspection_check_in）
    │
┌───策略=REQUIRED───┐
│  自动扫描蓝牙Beacon  │
│      │              │
│  ┌──检测到Beacon──┐  ┌──未检测到──┐
│  │ 连接蓝牙        │  │ 提示未检测  │
│  │ 连接成功→打卡   │  │ 重试/补录   │
│  │ check_type=    │  └────────────┘
│  │ BLUETOOTH      │
│  └────────────────┘
└────────────────────┘
    │
┌───策略=OPTIONAL───┐
│  选择打卡方式      │
│  ┌蓝牙打卡─手动打卡┐│
│  │BLUETOOTH MANUAL││
│  └────────────────┘│
└────────────────────┘
```