# 车辆三检模块改动说明

## 1. 本次改动

本次对车辆三检模块新增了以下能力：

1. 新增字段 `rejectReason`，表示审核不通过原因。
2. 新增批量审核接口，管理员可以一键审核多条不同的车辆三检内容。

## 2. 字段变更

### 2.1 新增字段

- 字段名：`rejectReason`
- 含义：审核不通过原因
- 生效场景：仅在审核不通过时有值

### 2.2 使用规则

- 当审核通过时：
  - 后端自动将 `rejectReason` 置空
- 当审核不通过时：
  - 前端需要传入 `rejectReason`
  - 若未传，后端会返回业务异常：
    - `审核不通过时，不通过原因不能为空`

### 2.3 数据库说明

车辆三检表需要新增字段：

```sql
ALTER TABLE hot_vehicle_three_inspect
ADD COLUMN reject_reason varchar(500) NULL COMMENT '审核不通过原因';
```

## 3. 单条审核接口调整

### 3.1 接口信息

- 路径：`POST /securityManagement/vehicleThreeInspect/audit`

### 3.2 新增请求字段

- `rejectReason`：审核不通过原因

### 3.3 审核规则

- 当前仍以 `hasHiddenDanger` 作为是否通过的判断依据：
  - `hasHiddenDanger = 0`：审核通过
  - `hasHiddenDanger = 1`：审核不通过
- 审核不通过时必须传 `rejectReason`
- 审核通过时 `rejectReason` 不入库

## 4. 批量审核接口

### 4.1 接口信息

- 路径：`POST /securityManagement/vehicleThreeInspect/batchAudit`
- 说明：管理员可一次性审核多条不同三检记录

### 4.2 请求体

```json
{
  "auditItems": [
    {
      "id": 101,
      "taskId": "task_001",
      "auditTime": "2026-05-22 10:00:00",
      "hasHiddenDanger": 0,
      "auditResult": "审核通过",
      "auditorSignImgUrl": "12345"
    },
    {
      "id": 102,
      "taskId": "task_002",
      "auditTime": "2026-05-22 10:05:00",
      "hasHiddenDanger": 1,
      "auditResult": "发现问题需整改",
      "rejectReason": "轮胎磨损超标",
      "auditorSignImgUrl": "12345"
    }
  ]
}
```

### 4.3 请求字段说明

批量项沿用单条审核字段，核心包括：

- `id`：三检记录ID
- `taskId`：流程任务ID
- `auditTime`：审核时间
- `hasHiddenDanger`：是否存在隐患
- `auditResult`：审核结论
- `rejectReason`：审核不通过原因
- `auditorSignImgUrl`：审核人签名

### 4.4 处理规则

接口会逐条执行以下逻辑：

1. 校验三检记录ID和流程任务ID。
2. 校验审核时间不能早于检查时间。
3. 若传了审核签名，则校验签名归属。
4. 根据 `hasHiddenDanger` 处理通过/不通过逻辑。
5. 审核不通过时校验 `rejectReason` 必填。
6. 更新三检记录并推进对应流程任务。

## 5. 影响范围

- 详情接口、列表接口、导出接口会返回 `rejectReason` 字段。
- 审核驳回通知优先展示 `rejectReason`，没有时才回退展示 `auditResult`。

## 6. 三检历史记录接口

### 6.1 新增字段

- `inspectNo`：三检记录编号，规则为 `SJ + 三检创建日期(yyyyMMdd) + 车牌号后3位 + 4位随机数`
- `inspectLocation`：检查地点，出车前、行车中、收车后三个阶段都支持保存

### 6.2 历史列表接口

- 路径：`GET /securityManagement/vehicleThreeInspect/history/list`
- 说明：按 `inspectId` 聚合查询一轮三检历史记录，支持分页

返回核心字段：

- `inspectId`：三检流程ID
- `inspectNo`：三检记录编号
- `plateNumber`：车牌号
- `inspectorName`：检查人
- `startTime`：检查开始时间（出车提交时间）
- `endTime`：检查结束时间（收车提交时间）
- `auditorName`：审核人
- `outInspectLocation`：出车前检查地点
- `drivingInspectLocation`：行车中检查地点
- `backInspectLocation`：收车后检查地点
- `outCheck` / `drivingCheck` / `backCheck`：三个阶段详情

### 6.3 历史详情接口

- 路径：`GET /securityManagement/vehicleThreeInspect/history/{inspectId}`
- 说明：返回指定 `inspectId` 下三个阶段的车辆三检详情

### 6.4 数据库脚本

新增脚本：

- `sql/alter_hot_vehicle_three_inspect_history_fields_20260601.sql`

脚本内容包含：

- 为 `hot_vehicle_three_inspect` 增加 `inspect_no`、`inspect_location` 字段
- 对历史数据回填 `inspect_no`

## 7. 多车辆批量审核接口

### 7.1 可批量审核列表接口

- 路径：`GET /securityManagement/vehicleThreeInspect/multiVehicleBatchAudit/list`
- 说明：分页查询当前登录人员可进行多车辆批量审核的车辆三检列表

### 7.2 查询参数

- `pageNum`：页码
- `pageSize`：每页条数，前端默认 `20`
- `plateNumber`：车牌号，支持筛选
- `companyId`：企业ID，可选；不传时后端默认取当前登录企业

请求示例：

```http
GET /securityManagement/vehicleThreeInspect/multiVehicleBatchAudit/list?pageNum=1&pageSize=20&plateNumber=川A
```

### 7.3 列表筛选规则

后端只会返回同时满足以下条件的三检流程：

1. 当前三检流程已经存在`收车后检查`记录。
2. 当前三检流程下存在`审核人是当前登录账号`的未审核记录。
3. 数据属于当前登录企业。

不满足上述条件的数据不会出现在列表中。

### 7.4 返回字段

后端返回类型为 `HotVehicleThreeInspectSummaryVo`，前端当前主要使用以下字段：

- `inspectId`：三检流程ID
- `vehicleId`：车辆ID
- `plateNumber`：车牌号
- `inspectorName`：检查人姓名
- `auditorName`：审核人姓名
- `startTime`：开始时间
- `endTime`：结束时间
- `outCheck` / `drivingCheck` / `backCheck`：三个阶段详情，查看详情时可直接复用

返回示例：

```json
{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "inspectId": 1001,
      "vehicleId": 501,
      "plateNumber": "川A12345",
      "inspectorName": "张三",
      "auditorName": "李四",
      "startTime": "2026-06-17 08:00:00",
      "endTime": "2026-06-17 18:00:00"
    }
  ],
  "total": 1
}
```

## 8. 多车辆批量审核提交接口

### 8.1 接口信息

- 路径：`POST /securityManagement/vehicleThreeInspect/multiVehicleBatchAudit`
- 说明：对多辆车的车辆三检进行批量审核
- 处理方式：新接口只负责组装批量审核数据，底层仍复用原有 `batchAudit` 和 `doAudit` 逻辑

### 8.2 请求体

```json
{
  "inspectIds": [1001, 1002, 1003],
  "hasHiddenDanger": 1,
  "evaluatorId": 2001,
  "auditTime": "2026-06-17 18:30:00",
  "auditResult": "存在隐患，需整改",
  "rejectReason": "轮胎磨损严重",
  "auditorSignImgUrl": "https://example.com/sign.png"
}
```

### 8.3 请求字段说明

- `inspectIds`：三检流程ID集合，必填
- `hasHiddenDanger`：是否存在隐患，必填；`0=否`、`1=是`
- `evaluatorId`：评估人ID；当 `hasHiddenDanger = 1` 时必填
- `auditTime`：审核时间；不传时后端默认取当前时间
- `auditResult`：审核结论；不传时后端自动生成
- `rejectReason`：审核不通过原因；有隐患时建议传入
- `auditorSignImgUrl`：审核人员签名图片地址，必填

### 8.4 自动生成规则

- 当 `auditTime` 为空时，后端自动使用当前时间。
- 当 `auditResult` 为空时：
  - `hasHiddenDanger = 0`：自动生成 `通过`
  - `hasHiddenDanger = 1` 且传了 `rejectReason`：自动生成 `不通过：{rejectReason}`
  - `hasHiddenDanger = 1` 且未传 `rejectReason`：自动生成 `不通过`

### 8.5 批量审核校验规则

后端会对每个 `inspectId` 依次校验：

1. 三检流程必须存在。
2. 当前流程必须已完成收车检查，否则报错：`{车牌号}尚未完成收车检查，不可批量审核`
3. 当前流程中必须存在`审核人是当前登录人`的未审核数据，否则报错：`{车牌号}没有当前账号可审核的未审核数据`
4. 只有当前登录企业下的数据才会参与组装。
5. 组装后的明细仍会走原有单条审核校验，包括：
   - 流程任务ID不能为空
   - 三检记录ID不能为空
   - 审核时间不能早于检查时间
   - 审核签名校验
   - 流程审批人校验

### 8.6 实际审核范围

每个 `inspectId` 并不是只审核一条数据，而是会自动筛出该三检流程下所有满足以下条件的阶段记录一起审核：

- 审核人等于当前登录账号
- 当前记录尚未审核完成
- 当前记录存在流程任务 `taskId`

因此一次多车辆批量审核，最终可能会展开成多条实际审核明细。

### 8.7 有隐患时的处理

- 当 `hasHiddenDanger = 1` 时，审核流程按不通过处理。
- 流程结束后，会按每一条三检明细分别创建隐患治理数据。
- 如果本次批量审核展开后共有 N 条三检明细，则会生成 N 条隐患治理数据，不会合并成 1 条。

### 8.8 返回结果

成功返回：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": null
}
```

失败时返回业务异常，例如：

- `三检流程ID不能为空`
- `存在隐患时评估人不能为空`
- `未查询到可批量审核的车辆三检数据`
- `{车牌号}尚未完成收车检查，不可批量审核`
- `{车牌号}没有当前账号可审核的未审核数据`