changelog: #5533 司机列表车型大类/车队展示筛选 + 详情关联订单字段（dev-v3，author wx(GIT)）

changelogs-v2/2026-08/05_5533_司机列表车型大类与车队展示筛选及关联订单字段-修改接口-管理后台.md

@@ -0,0 +1,91 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5533"
+title: "司机列表新增车型大类/所属车队展示与筛选，详情关联订单补齐接送机/金额/定制师"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "pending"
+gateway_status: "pending"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+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/{driverId}` | `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