diff --git a/changelogs-v2/2026-08/05_5533_司机列表车型大类与车队展示筛选及关联订单字段-修改接口-管理后台.md b/changelogs-v2/2026-08/05_5533_司机列表车型大类与车队展示筛选及关联订单字段-修改接口-管理后台.md new file mode 100644 index 0000000..2804bf3 --- /dev/null +++ b/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` | 否 | 车型大类 key 多选过滤(逗号分隔),常驻车辆挂在任一大类下即命中;不传不过滤 | +| `teamIds` | `List` | 否 | 所属车队 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