# 【修改接口·管理后台】车务矩阵派单补齐统计与订单字段

> **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`

这些失败点不经过矩阵派单接口代码路径。