docs(fleet): matrix dispatch contract stats
这个提交包含在：
API Changelog Bot
父节点
e11300080b
当前提交
bddb222604
@ -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<MatrixUnassignedOrderVO>`
|
||||
|
||||
新增字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `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<MatrixDayOrderVO>`
|
||||
|
||||
新增字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `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`
|
||||
|
||||
这些失败点不经过矩阵派单接口代码路径。
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户