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

Issue: wx/HL#4845
PR: wx/HL#4849、wx/HL#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. 派单看板列表

GET /admin/fleet/board/orders
Authorization: Bearer <token>

前端当前传参示例：

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` / 空	不筛选状态

响应示例：

{
  "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. 派单看板详情

GET /admin/fleet/board/orders/2074724409473458177
Authorization: Bearer <token>

新增字段与列表一致：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "id": "HL20260703142715457",
    "orderId": "2074724409473458177",
    "customerName": "乐瑶",
    "plannerName": "张三",
    "consultantName": "张三",
    "consultantDisplayName": "张三",
    "transport": {
      "pickupRequired": true,
      "batches": []
    }
  }
}

说明：

三个字段当前同值，来源是订单创建时的定制师展示名快照。
展示名来源口径是企微名优先；没有企微名时回退用户名。
plannerName 继续保留，避免破坏旧页面。

4. 本次后端验证

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

5.0 KiB 原始文件 Blame 文件历史 Unescape Escape

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

1. 结论

2. 派单看板列表

3. 派单看板详情

4. 本次后端验证

5.0 KiB

原始文件 Blame 文件历史