# 【前端对接·管理后台】派单看板筛选参数兼容与定制师展示名

> 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`、定制师字段。