---
schema: "hl-changelog/v2"
ticket: "5533"
title: "司机列表新增车型大类/所属车队展示与筛选，详情关联订单补齐接送机/金额/定制师"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "pi-main-session"
frontend_ref: "hl-admin@005ba4cf9151e39aac5bcf4c5e5480411d68264e"
target_release: ""
verified_at: ""
status_note: ""
updated_at: "2026-08-05"
base: "dev-v3"
---

# 车务司机管理：列表车型大类/所属车队展示与筛选 + 详情关联订单字段补齐

> **服务**: hl-fleet-service
> **PR**: #5538
> **Issue**: #5533
> **日期**: 2026-08-05
> **影响范围**: 管理后台司机列表 / 司机详情关联订单区域

## 变更接口

| 接口 | 方法 | 路径 | 变更 |
|---|---|---|---|
| 司机档案分页查询 | GET | `/admin/fleet/drivers/page` | 列表项新增车型大类/所属车队字段；新增 `vehicleTypeKeys`、`teamIds` 筛选参数 |
| 司机档案详情查询 | GET | `/admin/fleet/drivers/（司机ID）` | `relatedOrders[]` 新增接送机地点、日费/总费、定制师字段 |

## 二、响应字段

### 2.1 司机列表 `records[]`（顶层新增）

| 字段 | 类型 | 必填性 | 值 | 说明 |
|---|---|---|---|---|
| `residentVehicleTypeKey` | `String` / null | 否 | `suv2`/`mpv`/`sedan`/`bus` 等 | 权威常驻车辆第一辆的车型大类 key（与派单候选弹窗分类一致）；无常驻车辆为 null |
| `residentVehicleTypeName` | `String` / null | 否 | `SUV系列`/`商务车`/`轿车系列`/`大巴系列` | 车型大类中文名；无常驻车辆为 null |
| `residentTeamId` | `String` / null | 否 | 车队雪花 ID（JSON 字符串） | 权威常驻车辆第一辆的所属车队 ID；无常驻车辆为 null |
| `residentTeamName` | `String` / null | 否 | `合作车队B` | 所属车队名；无常驻车辆为 null |

`residentVehicles[]` 子项同步新增：`vehicleTypeKey`、`vehicleTypeName`、`fleetTeamId`、`fleetTeamName`。

### 2.2 司机列表新增筛选参数

| 参数 | 类型 | 必填性 | 说明 |
|---|---|---|---|
| `vehicleTypeKeys` | `List<String>` | 否 | 车型大类 key 多选过滤（逗号分隔），常驻车辆挂在任一大类下即命中；不传不过滤 |
| `teamIds` | `List<Long>` | 否 | 所属车队 ID 多选过滤，常驻车辆属于任一支车队即命中；不传不过滤 |

### 2.3 司机详情 `relatedOrders[]`（新增）

| 字段 | 类型 | 必填性 | 值 | 说明 |
|---|---|---|---|---|
| `pickupAt` | `String` / null | 否 | `满洲里` | 接机地点（fleet_assignment.pickup_at 快照）；无记录为 null |
| `dropoffAt` | `String` / null | 否 | `满洲里` | 送机地点（fleet_assignment.dropoff_at 快照）；无记录为 null |
| `dailyFee` | `String` / null | 否 | `800.00` | 协议日费（protocol_price 快照，JSON 字符串）；无费用为 null |
| `totalFee` | `String` / null | 否 | `800.00` | 派车组总费（vehicle_fee_total 快照，JSON 字符串）；无费用为 null |
| `customizerName` | `String` / null | 否 | `王骁` | 定制师名（planner_name 快照） |

原有字段（orderId/orderNo/teamNo/customerName/tripStartDate/tripEndDate/destination/orderStatus/vehicleType/licensePlate）不变；`destination` 保留为 pickup/dropoff 兼容拼接。

## 三、兼容性与前端事项

- 全部为向后兼容的响应字段扩展 + 可选筛选参数，不改既有字段语义、分页结构。
- 车型大类 key 以 vehicle_type 表 type_key 为准（与派单候选弹窗分类一致，如 `suv2`），前端筛选值应复用候选弹窗/字典数据源。
- 后端未修改 `mmg/hl-ui`，前端消费状态保持 `pending`。

## 验证证据

- 定向测试 158 项全绿（DriverServiceTest 144 / VehicleResidentReadPortImplTest 7 / DriverMapperPageExcludeTest 3 / DriverRelatedOrderReadPortImplTest 4）；fleet verify 3130 项仅 1 既有基线 flaky 失败（Step2CanonicalSnapshotServiceTest 时间敏感，stash 验证与本次无关），0 Errors；spotless 0 违规。
- 测试环境网关实测：
  - 列表：朝鲁门（suv2/SUV系列/北疆协作车队）、菜单师傅46622（mpv/商务车/自有）、王信（sedan/轿车系列/合作车队A）；无常驻车辆司机全字段 null
  - 筛选：`vehicleTypeKeys=suv2` 3 人、`suv2,mpv` 多选 8 人、`teamIds=合作车队B` 1 人、组合筛选 1 人、不存在大类空结果正确
  - 详情：乌云毕力格 relatedOrders 2 条——pickup/dropoff=满洲里、teamNo=26-4081、status=in_progress、dailyFee=0.00/totalFee=800.00、customizer=王骁、customer=卫予轩

## 五、关联 / 联系人

### 5.1 链接

- **Issue**: [#5533](https://git.1814.love:8443/wx/HL/issues/5533)
- **PR**: [#5538](https://git.1814.love:8443/wx/HL/pulls/5538)
- **Merge commit**: [9215f86ee](https://git.1814.love:8443/wx/HL/commit/9215f86eeccd9e1a1bd17e90ea6d2c1784a4db54)

### 5.2 联系人

- **后端负责人**: @wx

## 关联/联系人

### 链接

- [后端工单 #5533](https://git.1814.love:8443/wx/HL/issues/5533)
- [后端 PR #5538](https://git.1814.love:8443/wx/HL/pulls/5538)
- Merge commit: `9215f86ee6`

### 联系人

- **后端负责人**: @wx