diff --git a/changelogs-v2/2026-07/47_4845_派单看板筛选参数兼容与定制师展示名-管理后台.md b/changelogs-v2/2026-07/47_4845_派单看板筛选参数兼容与定制师展示名-管理后台.md new file mode 100644 index 0000000..ed5801d --- /dev/null +++ b/changelogs-v2/2026-07/47_4845_派单看板筛选参数兼容与定制师展示名-管理后台.md @@ -0,0 +1,152 @@ +# 【前端对接·管理后台】派单看板筛选参数兼容与定制师展示名 + +> Issue: [wx/HL#4845](https://git.1814.love:8443/wx/HL/issues/4845) +> PR: [wx/HL#4849](https://git.1814.love:8443/wx/HL/pulls/4849) +> 服务: `hl-fleet-service` +> 日期: 2026-07-08 +> 影响范围: 车务派单看板、派单详情、车务工作台摘要 + +## 1. 结论 + +- 后端已兼容前端 v2.1 当前真实传参:`statuses/typeKeys/startDate/endDate/keyword`。 +- 老字段仍保留:`vehicleTypeKeys/startDayFrom/startDayTo/driverName`,前端无需回改已有代码。 +- `statuses=unassigned` 会返回普通待派车和急待派车;`statuses=holding` 会返回普通配车中和配车中超时。 +- 精确派生态仍可单独传:`unassigned_urgent`、`holding_urgent`。 +- 派单列表和详情新增定制师展示字段:`consultantName`、`consultantDisplayName`;旧字段 `plannerName` 不变。 + +## 2. 派单看板列表 + +```http +GET /admin/fleet/board/orders +Authorization: Bearer +``` + +前端当前传参示例: + +```http +GET /admin/fleet/board/orders?page=1&pageSize=10&statuses=unassigned&typeKeys=suv&startDate=2026-07-01&endDate=2026-07-31&keyword=王 +``` + +兼容参数: + +| 前端现用字段 | 旧字段 | 类型 | 说明 | +|--------------|--------|------|------| +| `statuses` | `statuses` | string[] | 状态多选,重复 query key 传数组。 | +| `status` | - | string | 单值状态别名,也支持逗号分隔。 | +| `typeKeys` | `vehicleTypeKeys` | string[] | 车型大类多选,`suv/mpv/bus/sedan`。 | +| `startDate` | `startDayFrom` | date | 行程区间筛选起,未传旧字段时生效。 | +| `endDate` | `startDayTo` | date | 行程区间筛选止,未传旧字段时生效。 | +| `keyword` | `driverName` | string | 司机姓名模糊搜索,未传旧字段时生效。 | + +状态筛选口径: + +| 入参 | 返回 | +|------|------| +| `unassigned` / `待派车` | `unassigned` + `unassigned_urgent` | +| `unassigned_urgent` | 仅急待派车 | +| `holding` / `配车中` | `holding` + `holding_urgent` | +| `holding_urgent` | 仅配车中超时 | +| `assigned` | 已派车 | +| `change_requested` | 换车请求 | +| `canceled` | 已取消 | +| `completed` | 已完结 | +| `all` / 空 | 不筛选状态 | + +响应示例: + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "page": 1, + "pageSize": 10, + "total": 108, + "records": [ + { + "id": "HL20260703142715457", + "orderId": "2074724409473458177", + "customerName": "乐瑶", + "productName": "测试核心产品-单档-固定订金", + "headcount": 5, + "startDate": "2026-07-23", + "endDate": "2026-07-25", + "assignmentStatus": "unassigned_urgent", + "urgentBadge": "急", + "plannerName": "张三", + "consultantName": "张三", + "consultantDisplayName": "张三", + "customerNote": "需要接送机", + "requiredVehicles": [ + { + "vehicleType": "suv", + "categoryLabel": "SUV", + "seats": 7, + "count": 1 + } + ], + "unreadMessageCount": 0 + } + ] + } +} +``` + +前端处理建议: + +- 展示定制师优先读 `consultantDisplayName`,兼容回退 `consultantName || plannerName`。 +- 继续用当前 `paramsSerializer: { indexes: null }`,数组序列化为 `statuses=unassigned&statuses=assigned`。 +- `statuses=unassigned` 不要在前端额外补 `unassigned_urgent`,后端已经包含。 + +## 3. 派单看板详情 + +```http +GET /admin/fleet/board/orders/2074724409473458177 +Authorization: Bearer +``` + +新增字段与列表一致: + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "id": "HL20260703142715457", + "orderId": "2074724409473458177", + "customerName": "乐瑶", + "plannerName": "张三", + "consultantName": "张三", + "consultantDisplayName": "张三", + "transport": { + "pickupRequired": true, + "batches": [] + } + } +} +``` + +说明: + +- 三个字段当前同值,来源是订单创建时的定制师展示名快照。 +- 展示名来源口径是企微名优先;没有企微名时回退用户名。 +- `plannerName` 继续保留,避免破坏旧页面。 + +## 4. 本次后端验证 + +```bash +mvn -pl hl-fleet-service -am -Dtest=BoardOrderServiceTest -DfailIfNoTests=false test +mvn -pl hl-fleet-service spotless:check +mvn -pl hl-fleet-service -am -DfailIfNoTests=false test +mvn -pl hl-fleet-service -am verify +``` + +验证结果: + +- `BoardOrderServiceTest` 23 个用例通过。 +- `hl-fleet-service -am test` 通过。 +- `hl-fleet-service -am verify` 通过,1362 个测试、ArchUnit、Spotless 全部成功。 +- 覆盖点:前端别名参数、基础态包含派生态、`all` 不筛选、车型大类别名、司机 `keyword`、定制师字段。 +