---
schema: "hl-changelog/v2"
ticket: "5282"
title: "矩阵年度月度订单统计"
consumer: "admin"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "hl-ui-pi"
frontend_ref: "7d0589d6"
target_release: ""
verified_at: ""
status_note: "管理后台已由提交 7d0589d6 完成年度月度订单统计消费并通过验证"
updated_at: "2026-07-27"
base: "dev-v3"
generated: "2026-07-27T10:04:56+08:00"
---

# 矩阵年度月度订单统计

> 后端契约已部署并经测试网关验证；`frontend_status` 独立反映管理端交付状态。

## 关联

- Issue: #5282
- PR: wx/HL#5286

## 变更接口

### `GET /admin/fleet/matrix/month-counts`

一次查询指定年份的矩阵月度订单状态统计，统计口径与 `GET /admin/fleet/matrix/grid` 的 `statusCounts` 一致。

请求参数：

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `year` | query | `Integer` | 是 | 沿用矩阵 `YearMonth` 校验，越界返回 `605010` |
| `season` | query | `String` | 否 | 不传或空白时按 `active` 处理 |
| `fleetTeamIds` | query | `Long[]` | 否 | 可重复参数；空数组表示不过滤车队 |
| `typeKeys` | query | `String[]` | 否 | 可重复参数；空数组表示不过滤车型 |

响应 `data`：

```json
{
  "year": 2026,
  "months": [
    {
      "month": 1,
      "statusCounts": {
        "totalAssignments": 0,
        "unassignedAssignments": 0,
        "assignedAssignments": 0,
        "totalOrders": 0,
        "unassignedOrders": 0,
        "partialOrders": 0,
        "assignedOrders": 0
      }
    }
  ]
}
```

- `months` 固定返回 12 项，按 `month=1..12` 升序；无订单月份不省略，各计数字段为 `0`。
- 一条跨月派车记录按实际服务日期覆盖的月份分别计数；已取消、已关闭订单沿用矩阵现有口径排除。
- 年份越界沿用矩阵业务错误码 `605010`；缺失必填参数沿用统一参数校验响应。

## 契约影响文件

- `hl-fleet-service/src/main/java/com/hulalv/fleet/matrix/controller/MatrixController.java`
- `hl-fleet-service/src/main/java/com/hulalv/fleet/matrix/vo/MatrixMonthCountsReqVO.java`
- `hl-fleet-service/src/main/java/com/hulalv/fleet/matrix/vo/MatrixMonthCountsRespVO.java`
- `hl-fleet-service/src/test/java/com/hulalv/fleet/matrix/controller/MatrixControllerTest.java`

## 前端/调用方动作

- 车务矩阵页面按当前年份、赛季、车队和车型筛选请求本接口。
- 月份选择器读取对应月份的 `statusCounts.totalAssignments`；有效零值显示 `0`，请求尚未完成或失败显示 `--`。
- 跨年切换时按目标年份加载；可按筛选键缓存结果，筛选变化后重新获取。
- 数组查询参数必须使用重复 key（Axios `paramsSerializer` 的 `indexes` 设为 `null`），不要发送带下标的参数名。

## 兼容性与路由

- 新增 GET 路径，不修改既有路径、请求参数、响应字段、枚举或错误码，对既有消费者向后兼容。
- 网关已有 `Path=/admin/fleet/**` 路由覆盖，无需新增网关配置。
- 无 internal Feign 或 shared Java 契约变更。

## 验证证据

- 后端定向测试：`MatrixServiceTest,MatrixControllerTest` 共 39 项通过，覆盖固定 12 月零值、跨月、终态排除、筛选、数组绑定、JSON 和与 grid 的统计守恒。
- 后端完整门禁：`mvn -pl hl-fleet-service -am verify` 通过（2434 tests，0 failures/errors，1 skipped）；Fleet Spotless 626 文件通过。
- 测试部署：PR `wx/HL#5286` 合入 `dev-v3`，Deploy Panel 任务 `57a121a0` 成功，8087/8187 双实例健康。
- 测试网关：2026 年返回固定 12 项且字段与派单/订单守恒通过；2099 年固定 12 项且全部计数为 `0`。脱敏证据：`C:/Users/Administrator/AppData/Local/hl-workflow/evidence/5282/gateway-month-counts.json`。
- DB 地面真相：`not_verified`；现有只读探针的数据源安全守卫拒绝本地地址，未绕过门禁。零值另由 2099 网关实测与 Service 测试覆盖。
- 管理端本地实现：全量 Vitest 125 文件 / 1160 项通过；生产构建、ESLint 通过；6 个改动文件 Prettier 检查通过。因前端分支尚未推送/发布，frontmatter 仍保持 `frontend_status: pending`。
- OpenAPI diff：`not_configured`。当前仓库仅提供 Swagger 2，且本机未配置 `oasdiff`；已人工核对路径、方法、参数、响应、空态、错误码、网关与消费者，未伪报自动 diff 通过。
- 人工契约证据：`C:/Users/Administrator/AppData/Local/hl-workflow/evidence/5282/contract-review.md`。