293 lines
8.6 KiB
Markdown
293 lines
8.6 KiB
Markdown
# 驾驶员车辆绑定改动说明
|
||
|
||
## 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;
|
||
```
|