From bddb2226041b87ba821711438f8d4fd65703c8e0 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 5 Jul 2026 17:46:42 +0800 Subject: [PATCH] docs(fleet): matrix dispatch contract stats --- ...矩阵派单统计与订单字段-修改接口-管理后台.md | 180 ++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 changelogs-v2/2026-07/24_4751_车务矩阵派单统计与订单字段-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/24_4751_车务矩阵派单统计与订单字段-修改接口-管理后台.md b/changelogs-v2/2026-07/24_4751_车务矩阵派单统计与订单字段-修改接口-管理后台.md new file mode 100644 index 0000000..75c82d7 --- /dev/null +++ b/changelogs-v2/2026-07/24_4751_车务矩阵派单统计与订单字段-修改接口-管理后台.md @@ -0,0 +1,180 @@ +# 【修改接口·管理后台】车务矩阵派单补齐统计与订单字段 + +> **Issue**: [wx/HL#4751](https://git.1814.love:8443/wx/HL/issues/4751) +> **PR**: [wx/HL#4752](https://git.1814.love:8443/wx/HL/pulls/4752) +> **服务**: hl-fleet-service +> **日期**: 2026-07-05 +> **影响范围**: 管理后台车务管理 / 矩阵派单 `/fleet/matrix` + +--- + +## 1. 关键变化 + +- `GET /admin/fleet/matrix/grid` 新增 `statusCounts` 与 `unassignedWindowCount`，直接支撑页面顶部「全部/未派/已派」和「打开未派订单窗口」数量。 +- `grid / unassigned-orders / day-orders` 均新增： + - `orderNumericId`：订单数值 ID，雪花 ID 字符串序列化，打开订单详情/后续操作请用它。 + - `orderNo`：订单号展示字段。 + - `startDate` / `endDate`：原始服务日期，不受月内裁剪影响。 +- 兼容说明：原字段 `orderId` **保持旧语义不变**，仍是订单号字符串，不要当数值订单 ID 使用。 + +--- + +## 2. 变更接口 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 矩阵主数据 | GET | `/admin/fleet/matrix/grid` | 响应新增字段 | 新增顶部统计；assignment 新增订单数值 ID、订单号、原始日期 | +| 2 | 未派订单清单 | GET | `/admin/fleet/matrix/unassigned-orders` | 响应新增字段 | 新增订单数值 ID、订单号、原始日期 | +| 3 | 当天订单清单 | GET | `/admin/fleet/matrix/day-orders` | 响应新增字段 | 新增订单数值 ID、订单号、原始日期 | + +--- + +## 3. `GET /admin/fleet/matrix/grid` + +响应 VO：`MatrixGridRespVO` + +### 3.1 顶层新增字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `statusCounts` | object | 当前 `year/month/fleets/typeKeys/season` 过滤口径下的状态统计；`status` tab 本身不参与统计裁剪 | +| `unassignedWindowCount` | number | 未派订单窗口数量，去重订单数；一单多车多未派行只计 1 单 | + +`statusCounts` 字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `totalAssignments` | number | 有效派单行数合计，`unassignedAssignments + assignedAssignments` | +| `unassignedAssignments` | number | 未派派单行数，`assignment_status=unassigned` | +| `assignedAssignments` | number | 已派派单行数，`assignment_status=holding/assigned` | +| `totalOrders` | number | 去重订单数合计，`unassignedOrders + assignedOrders` | +| `unassignedOrders` | number | 含至少一个未派项的去重订单数；部分已派订单也计入 | +| `partialOrders` | number | 既有已派项也有未派项的去重订单数，是 `unassignedOrders` 的子集 | +| `assignedOrders` | number | 全部派单项均已派的去重订单数 | + +建议页面取数口径： + +| 页面位置 | 建议字段 | +|----------|----------| +| tab「全部/未派/已派」如按甘特条/派单行计数 | `totalAssignments / unassignedAssignments / assignedAssignments` | +| 顶部订单去重统计 | `totalOrders / unassignedOrders / assignedOrders`，如需展示部分已派可读取 `partialOrders` | +| 「打开未派订单窗口 · N」 | `unassignedWindowCount` | + +### 3.2 `vehicles[].assignments[]` 新增字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `orderNumericId` | string | 订单数值 ID，雪花 ID 字符串序列化 | +| `orderNo` | string | 订单号，展示用 | +| `startDate` | string | 原始服务开始日期，格式 `YYYY-MM-DD` | +| `endDate` | string | 原始服务结束日期，格式 `YYYY-MM-DD` | + +响应片段： + +```json +{ + "statusCounts": { + "totalAssignments": 21, + "unassignedAssignments": 10, + "assignedAssignments": 11, + "totalOrders": 16, + "unassignedOrders": 5, + "partialOrders": 2, + "assignedOrders": 11 + }, + "unassignedWindowCount": 5, + "vehicles": [ + { + "id": "100", + "assignments": [ + { + "id": "9001", + "orderId": "26-0501", + "orderNumericId": "2049000000000000001", + "orderNo": "26-0501", + "startDay": 1, + "endDay": 6, + "startDate": "2026-05-01", + "endDate": "2026-05-06" + } + ] + } + ] +} +``` + +--- + +## 4. `GET /admin/fleet/matrix/unassigned-orders` + +响应 VO：`List` + +新增字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `orderNumericId` | string | 订单数值 ID，雪花 ID 字符串序列化 | +| `orderNo` | string | 订单号，展示用 | +| `startDate` | string | 原始服务开始日期，格式 `YYYY-MM-DD` | +| `endDate` | string | 原始服务结束日期，格式 `YYYY-MM-DD` | + +响应片段： + +```json +{ + "orderId": "26-0503", + "orderNumericId": "2049000000000000003", + "orderNo": "26-0503", + "assignmentId": "9003", + "startDay": 6, + "endDay": 11, + "startDate": "2026-05-06", + "endDate": "2026-05-11", + "assignmentStatus": "unassigned_urgent" +} +``` + +--- + +## 5. `GET /admin/fleet/matrix/day-orders` + +响应 VO：`List` + +新增字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `orderNumericId` | string | 订单数值 ID，雪花 ID 字符串序列化 | +| `orderNo` | string | 订单号，展示用 | +| `startDate` | string | 原始服务开始日期，格式 `YYYY-MM-DD` | +| `endDate` | string | 原始服务结束日期，格式 `YYYY-MM-DD` | + +响应片段： + +```json +{ + "orderId": "26-0501", + "orderNumericId": "2049000000000000001", + "orderNo": "26-0501", + "startDate": "2026-05-01", + "endDate": "2026-05-06", + "dayInTrip": 4, + "totalDays": 6, + "orderAssignStatus": "partial", + "assignments": [] +} +``` + +--- + +## 6. 验证状态 + +- `mvn -pl hl-fleet-service -am -Dtest=MatrixServiceTest -DfailIfNoTests=false test`：通过，`MatrixServiceTest` 14 个用例全绿。 +- `mvn -pl hl-fleet-service spotless:check`：通过。 +- `mvn -pl hl-fleet-service -am -DfailIfNoTests=false test`：未全绿，失败集中在既有 Redis lock 相关集成测试： + - `DriverCrudIntegrationTest` + - `DriverPendingReviewIntegrationTest` + - `H5OnboardIntegrationTest` + - `VehicleCrudIntegrationTest` + +这些失败点不经过矩阵派单接口代码路径。