【前端待处理·管理后台】#5160 一名司机可绑定多辆常驻车

服务: hl-fleet-service Issue: wx/HL#5160 PR: wx/HL#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

请求体：

{
  "vehicleIds": [
    "2079857985374363650",
    "2079857985697308674",
    "2079857985848320002"
  ]
}

字段	类型	必填	约束	说明
`vehicleIds`	`string[]`	✅	最多 100 个	目标全集；`[]` 表示全部解绑；雪花 ID 必须按字符串处理

成功响应：

{ "code": 200, "message": "成功", "data": null, "success": true }

错误行为：

司机不存在：600205
任一车辆不存在：600110
任一目标车辆属于其他常驻司机：605023
缺少 vehicleIds 或超过 100 个：400

2. 司机详情与列表

详情和分页列表项新增：

{
  "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 通过。

5.3 KiB 原始文件 Blame 文件历史 Unescape Escape