104 行
5.1 KiB
Markdown
104 行
5.1 KiB
Markdown
---
|
||
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
|