wucaixing-backend/docs/DriverVehicleBindingApi.md

# 驾驶员车辆绑定改动说明

## 1. 本次改动概览

本次后端围绕驾驶员与车辆绑定，调整并新增以下能力：

1. 三检流程未完成时，禁止进行车辆换绑操作。
2. 三检流程未完成时，禁止新增出车检查。
3. 新增驾驶员自助切换默认车辆接口，允许当前登录驾驶员在自己已绑定车辆之间切换 `vehicleId`。
4. 新增查询接口：返回指定驾驶员已绑定车辆列表，以及所在公司仍可绑定的车辆列表。
5. 新增查询接口：仅返回指定驾驶员已绑定车辆列表。
6. 新增覆盖式批量绑定接口：前端传驾驶员ID和车辆ID串，后端先清空该驾驶员原有绑定，再绑定最新车辆列表。
7. 新增追加式批量绑定接口：前端传驾驶员ID和车辆ID串，后端保留该驾驶员已有绑定，仅追加绑定新车辆。
8. 驾驶员表保留单值字段 `vehicleId` 作为默认车辆ID。
9. 驾驶员表新增字段 `vehicleIds`，用于存储已绑定车辆ID集合，多个以英文逗号分隔。

## 2. 三检限制规则

### 2.1 换绑限制

- 生效范围：
  - 驾驶员编辑接口触发换绑时
  - 车辆编辑接口修改当前绑定驾驶员时
- 限制规则：
  - 若车辆当前存在未完成三检流程，则禁止换绑
- 提示文案：
  - `当前车辆三检流程未完成，不可进行换绑操作`

### 2.2 默认车辆切换限制

- 生效范围：
  - 当前登录驾驶员调用默认车辆切换接口时
- 限制规则：
  - 仅允许切换到当前驾驶员自己已绑定的车辆
  - 切换前要求当前默认车辆对应三检流程已完成
- 提示文案：
  - 非本人车辆：`驾驶员只能切换属于自己的车辆`
  - 当前车未完成三检：`当前车辆三检流程未完成，不可切换车辆`

### 2.3 新增出车检查限制

- 生效范围：
  - 新增车辆进出场检查接口
- 限制规则：
  - 若车辆当前存在未完成三检流程，则不能新增出车检查
- 提示文案：
  - `当前车辆三检流程未完成，不能新增出车检查`

### 2.4 未完成三检流程判定

- 判定口径：
  - 查询车辆最新一条三检记录
  - 仅当最新记录满足以下两个条件时，才视为已完成：
    - `inspectPhase = 3`
    - `flowStatus` 为 `APPROVED` 或 `REJECTED`
- 其他情况均视为三检流程未完成

## 3. 查询驾驶员绑定车辆选项接口

### 3.1 接口信息

- 路径：`GET /driverManagement/driver/bindingVehicleOptions`
- 入参：
  - `companyId`：公司ID
  - `driverId`：驾驶员ID

### 3.2 返回结构

返回 `data` 包含两个列表：

- `boundVehicleList`：该驾驶员已绑定车辆列表
- `bindableVehicleList`：该公司还可以绑定的车辆列表

列表项字段如下：

- `vehicleId`：车辆ID
- `plateNumber`：车牌号
- `currentDriverId`：当前绑定驾驶员ID
- `currentDriverName`：当前绑定驾驶员姓名
- `vehicleType`：车辆类型

### 3.3 查询规则

- 已绑定车辆：
  - 查询当前公司全部未删除车辆
  - 取 `currentDriver` 中包含当前 `driverId` 的车辆
- 可绑定车辆：
  - 当前公司
  - 未删除
  - `vehicleStatus = 1`
  - `operationStatus = 1`
  - `currentDriver` 为空

## 4. 驾驶员批量绑定车辆接口

### 4.1 接口信息

- 路径：`POST /driverManagement/driver/batchBindVehicles`
- 请求体：

```json
{
  "driverId": "abc123",
  "vehicleIds": "1001,1002,1003"
}
```

### 4.2 参数说明

- `driverId`：必填，驾驶员ID
- `vehicleIds`：
  - 可为空
  - 多个车辆ID使用英文逗号分隔
  - 若为空，表示清空该驾驶员当前绑定车辆

### 4.3 业务规则

接口执行过程如下：

1. 校验驾驶员是否存在。
2. 根据驾驶员所属公司校验目标车辆是否存在且归属当前公司。
3. 若原绑定车辆或目标绑定车辆存在未完成三检流程，则禁止批量绑定。
4. 先将该驾驶员从原已绑定车辆中解绑。
5. 再将目标车辆批量绑定到当前驾驶员。
6. 同步回写驾驶员表中的：
   - `vehicleId`：默认车辆ID，取当前绑定车辆中的主车辆
   - `vehicleIds`：全部绑定车辆ID集合
   - `plateNumber`：默认车辆对应车牌号
7. 同步处理受影响的其他驾驶员车辆关系。

### 4.4 返回结果

- 成功：返回通用成功响应
- 失败：抛出业务异常并返回对应提示

## 5. 查询驾驶员已绑定车辆列表接口

### 5.1 接口信息

- 路径：`GET /driverManagement/driver/boundVehicles`
- 入参：
  - `companyId`：公司ID
  - `driverId`：驾驶员ID

### 5.2 返回字段

返回列表项字段如下：

- `vehicleId`：车辆ID
- `plateNumber`：车牌号
- `currentDriverId`：当前绑定驾驶员ID
- `currentDriverName`：当前绑定驾驶员姓名
- `vehicleType`：车辆类型

## 6. 驾驶员切换默认车辆接口

### 6.1 接口信息

- 路径：`POST /driverManagement/driver/switchVehicle`
- 说明：当前登录驾驶员自助切换默认车辆

### 6.2 请求体

```json
{
  "vehicleId": "1002"
}
```

### 6.3 参数说明

- `vehicleId`：必填，目标车辆ID

### 6.4 业务规则

接口执行过程如下：

1. 仅允许驾驶员端已登录用户调用。
2. 根据当前登录信息获取驾驶员，不允许前端指定其他 `driverId`。
3. 校验目标 `vehicleId` 必须存在于当前驾驶员的 `vehicleIds` 中。
4. 校验目标车辆当前 `currentDriver` 仍然包含当前驾驶员，防止脏数据误切换。
5. 若切换前当前默认车辆存在未完成三检流程，则禁止切换。
6. 切换成功后仅更新驾驶员表中的：
   - `vehicleId`：切换后的默认车辆ID
   - `plateNumber`：切换后默认车辆对应车牌号
7. `vehicleIds` 不变，车辆表 `currentDriver` 不变。

### 6.5 返回结果

- 成功：返回通用成功响应
- 失败：抛出业务异常并返回对应提示

## 7. 驾驶员追加批量绑定车辆接口

### 7.1 接口信息

- 路径：`POST /driverManagement/driver/appendBindVehicles`
- 请求体：

```json
{
  "driverId": "abc123",
  "vehicleIds": "1001,1002,1003"
}
```

### 7.2 业务规则

接口执行过程如下：

1. 校验驾驶员是否存在。
2. 根据驾驶员所属公司校验目标车辆是否存在且归属当前公司。
3. 不取消该驾驶员现有绑定车辆。
4. 仅将本次新增传入的车辆追加绑定给当前驾驶员。
5. 若新增车辆当前已绑定其他驾驶员，则转绑到当前驾驶员，并同步受影响驾驶员关系。
6. 若本次新增车辆存在未完成三检流程，则禁止绑定。
7. 同步回写驾驶员表中的：
   - `vehicleId`
   - `vehicleIds`
   - `plateNumber`

## 8. 驾驶员解除绑定接口

### 8.1 接口信息

- 路径：`POST /driverManagement/driver/unbindVehicles`
- 请求体：

```json
{
  "driverId": "abc123",
  "vehicleIds": "1001,1002"
}
```

### 8.2 参数说明

- `driverId`：必填，驾驶员ID
- `vehicleIds`：
  - 可为空
  - 多个车辆ID使用英文逗号分隔
  - 为空时表示清空该驾驶员当前全部绑定车辆
  - 有值时表示仅解绑指定车辆

### 8.3 业务规则

接口执行过程如下：

1. 校验驾驶员是否存在。
2. 根据驾驶员所属公司校验目标车辆是否存在且归属当前公司。
3. 校验传入车辆当前确实绑定在该驾驶员名下，否则禁止解绑。
4. 校验待解绑车辆当前不存在未完成三检流程，否则禁止解绑。
5. 仅执行解绑，不触发换绑逻辑。
6. 从该驾驶员当前绑定关系中移除指定车辆，或清空全部绑定。
7. 同步回写驾驶员表中的：
   - `vehicleId`
   - `vehicleIds`
   - `plateNumber`

## 9. 绑定模型说明

- 当前车辆表实际是一车单人绑定，`currentDriver` 仅保留单个驾驶员ID。
- 驾驶员表支持一个驾驶员绑定多辆车：
  - `vehicleId`：默认车辆ID，单值
  - `vehicleIds`：全部绑定车辆ID集合，多值CSV
  - `plateNumber`：默认车辆对应车牌号，单值
- 因此批量绑定的核心逻辑是：
  - 车辆侧单车只绑定一个驾驶员
  - 驾驶员侧允许关联多辆车
  - 移动端与司机端默认取 `vehicleId` 作为当前车辆

## 10. 数据库脚本

- 脚本文件：`sql/alter_hot_driver_vehicle_ids_20260522.sql`
- 脚本内容：

```sql
ALTER TABLE hot_driver
    ADD COLUMN vehicle_ids VARCHAR(1000) NULL COMMENT '已绑定车辆ID集合，多个以逗号分隔' AFTER vehicle_id;

UPDATE hot_driver
SET vehicle_ids = NULLIF(TRIM(vehicle_id), '')
WHERE vehicle_ids IS NULL
  AND vehicle_id IS NOT NULL;

UPDATE hot_driver
SET vehicle_id = NULLIF(SUBSTRING_INDEX(vehicle_ids, ',', 1), ''),
    plate_number = NULLIF(SUBSTRING_INDEX(plate_number, ',', 1), '');

ALTER TABLE hot_driver
    DROP COLUMN current_page_vehicle_id;
```