docs(fleet): hand off multiple resident vehicles (#5160)

2026-07-22 17:54:27 +08:00 · 2026-07-22 17:54:27 +08:00 · ab510d7e62
--- a/changelogs-v2/2026-07/86_5160_一名司机多辆常驻车-修改接口-前端待处理-管理后台.md
+++ 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` 通过。