# inspectiontask 模块逻辑说明

## 1. 模块定位

`inspectiontask` 是一个围绕“定时生成巡检任务、人工录入巡检结果、扫码记录留痕”的业务模块。它把巡检计划、巡检单、二维码、扫码记录四类能力串成一条闭环。

核心目标有三个：

1. 维护巡检计划，并通过 Quartz 定时触发。
2. 生成巡检单，支持人工补录、编辑、导出、删除。
3. 记录二维码与扫码行为，作为巡检现场的辅助台账。

## 2. 模块拆分

### 2.1 定时巡检任务

对应类：

- `TimingTaskController`
- `TimingTaskService`
- `TimingTaskServiceImpl`
- `TimingTaskScheduler`
- `TimingTaskJob`
- `QuartzConfig`

职责：

- 维护巡检计划。
- 计算首次执行时间和下次执行时间。
- 把巡检计划注册到 Quartz。
- 到点后自动生成巡检任务。

### 2.2 巡检任务记录

对应类：

- `InspectionTaskController`
- `InspectionTaskService`
- `InspectionTaskServiceImpl`

职责：

- 查询巡检任务列表。
- 查看某个定时任务下的巡检记录。
- 批量新增或编辑巡检任务。
- 删除巡检任务及其关联附件。

### 2.3 二维码管理

对应类：

- `QrCodeController`
- `QrCodeService`
- `QrCodeServiceImpl`

职责：

- 维护二维码基础信息。
- 提供列表、增改、删除能力。

### 2.4 扫码记录管理

对应类：

- `QrCodeScanRecordController`
- `QrCodeScanRecordService`
- `QrCodeScanRecordServiceImpl`

职责：

- 记录二维码扫码行为。
- 关联二维码信息与附件信息。
- 支持列表、增改、删除。

## 3. 主业务流程

### 3.1 定时任务创建与启停

前端通过 `POST /timingTask/addOrEditTimingTask` 创建或修改巡检计划。

后端处理顺序是：

1. 复制请求数据到 `TimingTask`。
2. 根据选择的设备列表补齐任务名称、区域、设备串等信息。
3. 计算首次执行时间。
4. 保存到数据库。
5. 同步 Quartz 调度状态。

如果后续调用 `POST /timingTask/changeEnable`：

1. 先更新数据库里的启用状态。
2. 再重新注册或刷新 Quartz 触发器。
3. 启用时恢复执行，禁用时暂停执行。

删除时会先删除数据库记录，再从 Quartz 中取消对应任务。

### 3.2 定时生成巡检单

Quartz 到点后触发 `TimingTaskJob`。

执行逻辑是：

1. 通过任务 ID 读取当前巡检计划。
2. 如果任务已禁用，直接退出。
3. 解析该任务绑定的设备列表。
4. 按设备逐个生成巡检单。
5. 按设备数量决定生成次数。
6. 写入 `inspection_task`。
7. 更新该定时任务的最后执行时间和下次执行时间。

这一步是模块的核心自动化入口。

### 3.3 巡检单人工录入与异常联动

前端通过 `POST /inspectionTask/addOrEditInspectionTask` 批量提交巡检单。

后端逻辑是：

1. 逐条保存或更新巡检单。
2. 若巡检结果为异常，则按区域收集异常任务。
3. 同一批提交里，同一区域只保留一条异常记录用于后续生成维修单。
4. 在当天范围内，如果该区域已经存在待维修单，则跳过，避免重复生成。
5. 如果不存在，则自动创建一条维修单。

因此，这个模块不仅保存巡检结果，还承担“巡检异常 -> 自动生成维修任务”的联动职责。

### 3.4 巡检单列表展示

巡检单列表接口会做一次“按定时任务聚合”的整理，而不是简单返回数据库原始行。

聚合逻辑大致是：

1. 按定时任务 ID 归组。
2. 同一组里只返回一条代表记录。
3. 合并任务名称、巡检人、备注、地点、频率等展示信息。
4. 合并该组下的附件列表。
5. 按定时任务和创建时间排序后分页返回。

所以列表页看到的是“业务视角的巡检任务卡片”，不是逐条底层记录。

### 3.5 巡检记录按定时任务查询

`GET /timingTask/recordList/{timingId}` 会查询某个定时任务在当天生成的巡检记录。

这里的范围限定为当天，是为了让页面查看“今日执行情况”更直接。

### 3.6 二维码与扫码记录

二维码模块只负责二维码本身的增删改查。

扫码记录模块负责把扫码行为、扫码人、二维码信息、附件信息串起来：

1. 先分页查扫码记录。
2. 再批量查关联二维码。
3. 再批量查关联附件。
4. 再查附件对应的文件元数据。
5. 最后组装成前端可直接展示的 DTO。

它的角色更像“巡检现场的辅助留痕模块”。

## 4. 调度与时间计算

### 4.1 Quartz 接入方式

`QuartzConfig` 提供了 `SchedulerFactoryBean` 和 `Scheduler`，并通过自定义 JobFactory 支持 Job 内部自动注入 Spring 依赖。

`TimingTaskScheduler` 负责：

- 创建 JobDetail。
- 创建 Trigger。
- 重新调度。
- 暂停、恢复、删除任务。

### 4.2 支持的频率类型

代码里支持的频率类型包括：

- `DAILY`
- `WEEKLY`
- `MONTHLY`
- `QUARTERLY`
- `YEARLY`

时间表达式由服务层和调度层共同解析，最终转换为 Quartz cron。

### 4.3 需要注意的实现细节

1. 服务层和 Job 层都各自实现了一套“下次执行时间”计算逻辑。
2. Job 层执行完后，会直接更新 `timing_task` 的最后执行时间和下次执行时间。
3. 服务层在新增任务时会先计算首次执行时间，但季度类型在当前实现里首次时间计算方法为空，属于一个需要注意的实现缺口。

## 5. 数据与关联关系

这个模块的主要关联关系可以理解为：

- `TimingTask` 是巡检计划。
- `InspectionTask` 是巡检执行记录。
- `QrCode` 是现场二维码台账。
- `QrCodeScanRecord` 是扫码行为记录。
- 巡检异常会联动生成维修单。
- 巡检单和扫码记录都会关联附件资源。

## 6. 对前端的意义

前端对这个模块的使用方式可以概括为：

1. 先维护巡检计划，再由系统自动生成巡检单。
2. 巡检单支持人工补录、编辑、导出、删除。
3. 定时任务支持启用、禁用和重新调度。
4. 巡检异常后，系统会自动补一条维修单，前端需要能及时刷新相关页面。
5. 二维码和扫码记录属于独立的辅助管理页面。

## 7. 接口总览

### 巡检任务

- `GET /inspectionTask/list`
- `POST /inspectionTask/export`
- `POST /inspectionTask/addOrEditInspectionTask`
- `DELETE /inspectionTask/delInspectionTask`

### 定时任务

- `GET /timingTask/list`
- `GET /timingTask/recordList/{timingId}`
- `POST /timingTask/export`
- `POST /timingTask/addOrEditTimingTask`
- `POST /timingTask/changeEnable`
- `DELETE /timingTask/delTimingTask`

### 二维码

- `GET /qrCode/list`
- `POST /qrCode/addOrEditQrCode`
- `DELETE /qrCode/delQrCode`

### 扫码记录

- `GET /qrCodeScanRecord/list`
- `POST /qrCodeScanRecord/addOrEditQrCodeRecord`
- `DELETE /qrCodeScanRecord/delSalesRecord`

## 8. 结论

`inspectiontask` 模块本质上是一条“计划 -> 调度 -> 生成巡检单 -> 录入结果 -> 异常联动维修 -> 留痕查询”的业务链路。  
如果后续要继续拆前后端联调，优先关注三块：定时任务的时间表达式、巡检结果的异常联动、以及巡检列表的聚合展示逻辑。