---
frontend_status: "implemented"
frontend_owner: "hl-ui-codex"
frontend_ref: "mmg/hl-ui@b309f1672f4587d11aa6b8e86d0dd4ba043274d1"
updated_at: "2026-07-25T03:11:01.515Z"
---
# 【前端待处理·管理后台】#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` 通过。