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