docs(fleet): 派单看板筛选参数兼容说明

2026-07-08 15:26:44 +08:00 · 2026-07-08 15:26:44 +08:00 · 2a878856b8
--- a/changelogs-v2/2026-07/47_4845_派单看板筛选参数兼容与定制师展示名-管理后台.md
+++ 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 <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 个用例通过。
+- `hl-fleet-service -am test` 通过。
+- `hl-fleet-service -am verify` 通过，1362 个测试、ArchUnit、Spotless 全部成功。
+- 覆盖点：前端别名参数、基础态包含派生态、`all` 不筛选、车型大类别名、司机 `keyword`、定制师字段。
+