diff --git a/changelogs-v2/2026-07/86_5160_一名司机多辆常驻车-修改接口-前端待处理-管理后台.md b/changelogs-v2/2026-07/86_5160_一名司机多辆常驻车-修改接口-前端待处理-管理后台.md new file mode 100644 index 0000000..8cfeedd --- /dev/null +++ b/changelogs-v2/2026-07/86_5160_一名司机多辆常驻车-修改接口-前端待处理-管理后台.md @@ -0,0 +1,124 @@ +# 【前端待处理·管理后台】#5160 一名司机可绑定多辆常驻车 + +> **服务**: `hl-fleet-service` +> **Issue**: [wx/HL#5160](https://git.1814.love:8443/wx/HL/issues/5160) +> **PR**: [wx/HL#5164](https://git.1814.love:8443/wx/HL/pulls/5164) +> **日期**: 2026-07-22 +> **影响范围**: 管理后台司机档案、车辆档案与车务派单候选 + +--- + +## 关键变化 + +- 常驻关系调整为“一辆车至多一名常驻司机,一名司机可常驻多辆车”。常驻关系仍以 `fleet_vehicle.primary_driver_id` 为权威,与实际派单关系相互独立。 +- 新增司机侧常驻车辆全集替换接口;空数组表示全部解绑。接口会先校验全部目标车辆,任一车辆已被其他司机占用时整单失败,不产生部分写入。 +- 旧单车接口和旧单车响应字段继续保留。旧接口等价于把全集替换为单元素或空集合;旧响应字段固定取按车辆 ID 升序后的第一辆。 +- `onlyResidentUnbound` 司机筛选参数兼容保留但不再生效,因为司机不再存在“已被一辆车占用”的状态。车辆侧“仅无常驻司机车辆”筛选仍有效。 + +## 接口清单 + +| # | 方法 | 路径 | 变更 | +|---|---|---|---| +| 1 | `PUT` | `/admin/fleet/drivers/{driverId}/resident-vehicles` | 新增:全量替换司机常驻车辆集合 | +| 2 | `PUT` | `/admin/fleet/drivers/{driverId}/resident-vehicle` | 保留:旧单车契约,内部按全集替换执行 | +| 3 | `GET` | `/admin/fleet/drivers/{driverId}` | 新增 `residentVehicles[]` | +| 4 | `GET` | `/admin/fleet/drivers` | 列表项新增 `residentVehicles[]`;`onlyResidentUnbound` 废弃 | +| 5 | `POST` | `/admin/fleet/assignments/candidates` | 司机候选与已选司机回显新增完整常驻车辆集合 | +| 6 | 车辆新增/编辑/导入 | 既有车辆档案接口 | 同一司机已常驻其他车辆时不再返回 `605022` | + +## 1. 全量替换常驻车辆 + +`PUT /admin/fleet/drivers/{driverId}/resident-vehicles` + +请求体: + +```json +{ + "vehicleIds": [ + "2079857985374363650", + "2079857985697308674", + "2079857985848320002" + ] +} +``` + +| 字段 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---| +| `vehicleIds` | `string[]` | ✅ | 最多 100 个 | 目标全集;`[]` 表示全部解绑;雪花 ID 必须按字符串处理 | + +成功响应: + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +错误行为: + +- 司机不存在:`600205` +- 任一车辆不存在:`600110` +- 任一目标车辆属于其他常驻司机:`605023` +- 缺少 `vehicleIds` 或超过 100 个:`400` + +## 2. 司机详情与列表 + +详情和分页列表项新增: + +```json +{ + "residentVehiclePlate": "蒙A-T1557", + "residentVehicles": [ + { + "vehicleId": "2079857985374363650", + "plate": "蒙A-T1557", + "modelName": "丰田普拉多", + "vehicleTypeId": "..." + }, + { + "vehicleId": "2079857985697308674", + "plate": "蒙A-U1557", + "modelName": "丰田汉兰达", + "vehicleTypeId": "..." + } + ] +} +``` + +`residentVehicles` 恒按 `vehicleId` 升序;无常驻车辆时为 `[]`。兼容字段 `residentVehiclePlate` 取第一项车牌,无数据时为 `null`。 + +## 3. 派单候选 + +`POST /admin/fleet/assignments/candidates`: + +- `data.drivers.records[].residentVehicles[]` 新增全部 `{ vehicleId, plate }`;旧 `residentVehicleId` / `residentVehiclePlate` 取第一项。 +- `data.selectedDriverResidentVehicles[]` 新增已选司机的全部车辆候选快照;旧 `selectedDriverResidentVehicle` 取第一项。 +- 所选车辆命中司机常驻集合中的任意一辆,均视为常驻匹配,不触发跨常驻确认。 +- `driverKeyword` 可命中该司机任意常驻车牌。 + +## 不影响范围 + +- 每辆车仍只有一个 `primaryDriverId`,车辆侧选择常驻司机仍是单选。 +- 实际订单派车不修改常驻关系;跨常驻车辆派单规则继续有效。 +- 旧接口、旧单车字段与 H5 单车续签契约继续可用。 +- 本次只提供后端契约,不直接修改 `hl-ui`。 + +## 验收清单 + +- [ ] 司机编辑可提交多辆车辆的 `vehicleIds` 全集,保存后详情回显相同集合。 +- [ ] 空数组可全部解绑;重复提交相同集合幂等成功。 +- [ ] 目标车辆被其他司机占用时整单失败,原绑定保持不变。 +- [ ] 车辆档案可把同一司机设为多辆车的常驻司机。 +- [ ] 派单选择司机的任一常驻车辆都显示常驻匹配,其他车辆仍按跨常驻规则提示。 +- [ ] 所有雪花 ID 保持字符串处理。 + +## 测试环境验证 + +2026-07-22 经测试网关 `https://api.test.1814.love:9443` 验证: + +- `PUT /admin/fleet/drivers/2079857983403024385/resident-vehicles` 提交 3 个车辆 ID → `code=200`。 +- `GET /admin/fleet/drivers/2079857983403024385` → `residentVehicles` 按 ID 升序返回 3 项,兼容字段 `residentVehiclePlate=蒙A-T1557`。 +- 分别读取 3 辆车辆详情,`primaryDriverId` 均为 `2079857983403024385`,`primaryDriverName=朝鲁门`: + - `蒙A-T1557` / 丰田普拉多 + - `蒙A-U1557` / 丰田汉兰达 + - `蒙A-V1557` / 丰田兰德酷路泽 +- 测试环境部署任务:`1485774a`,`hl-fleet-service` 从 `dev-v3` 部署成功。 +- 后端验证:定向 527 个测试通过;`spotless:check` 通过;最新 `dev-v3` 基线执行 `mvn -pl hl-fleet-service -am verify` 通过。