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
• 请求体：

{
  "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 请求体

{
  "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
• 请求体：

{
  "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
• 请求体：

{
  "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
• 脚本内容：

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;