154 行
5.0 KiB
Markdown
154 行
5.0 KiB
Markdown
# 【前端对接·管理后台】派单看板筛选参数兼容与定制师展示名
|
||
|
||
> 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)、[wx/HL#4850](https://git.1814.love:8443/wx/HL/pulls/4850)
|
||
> 服务: `hl-fleet-service`
|
||
> 日期: 2026-07-08
|
||
> 影响范围: 车务派单看板、派单详情、车务工作台摘要
|
||
|
||
## 1. 结论
|
||
|
||
- 后端已兼容前端 v2.1 当前真实传参：`statuses/typeKeys/startDate/endDate/keyword`。
|
||
- `startDate/endDate` 已在 Web query 绑定层验证，不会再因 `LocalDate` 转换返回 400。
|
||
- 老字段仍保留：`vehicleTypeKeys/startDayFrom/startDayTo/driverName`，前端无需回改已有代码。
|
||
- `statuses=unassigned` 会返回普通待派车和急待派车；`statuses=holding` 会返回普通配车中和配车中超时。
|
||
- 精确派生态仍可单独传：`unassigned_urgent`、`holding_urgent`。
|
||
- 派单列表和详情新增定制师展示字段：`consultantName`、`consultantDisplayName`；旧字段 `plannerName` 不变。
|
||
|
||
## 2. 派单看板列表
|
||
|
||
```http
|
||
GET /admin/fleet/board/orders
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
前端当前传参示例：
|
||
|
||
```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 <token>
|
||
```
|
||
|
||
新增字段与列表一致：
|
||
|
||
```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 个用例通过。
|
||
- `BoardControllerTest` 覆盖前端真实 GET query：`statuses/typeKeys/startDate/endDate/keyword`。
|
||
- `hl-fleet-service -am test` 通过。
|
||
- `hl-fleet-service -am verify` 通过，1363 个测试、ArchUnit、Spotless 全部成功。
|
||
- 覆盖点：前端别名参数、基础态包含派生态、`all` 不筛选、车型大类别名、司机 `keyword`、定制师字段。
|