changelogs-v2/2026-07/27_5282_矩阵年度月度订单统计-新增接口-管理后台.md

@@ -0,0 +1,99 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5282"
+title: "矩阵年度月度订单统计"
+consumer: "admin"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端已合并并部署测试环境，网关契约验收通过；管理端消费仍按 pending 独立跟踪"
+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`。