hl-api-changelog/changelogs-v2/2026-07/24_4751_车务矩阵派单统计与订单字段-修改接口-管理后台.md

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

Issue: wx/HL#4751 PR: wx/HL#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

响应片段：

{
  "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

响应片段：

{
  "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

响应片段：

{
  "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

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