71b931226c
所有检测均成功
changelog-filename-gate / validate (push) Successful in 1s
修改原因：管理后台已完成 #5282 年度月度订单统计消费，需要收口前端消费状态。 修改内容：将 frontend_status 更新为 implemented，关联前端提交 7d0589d6，并同步更新状态说明。 实际验证：source 测试 46 项通过，文件名、frontmatter、路径别名及差异空白检查全部通过。 对应 changelog：changelogs-v2/2026-07/27_5282_矩阵年度月度订单统计-新增接口-管理后台.md
100 行
4.6 KiB
Markdown
100 行
4.6 KiB
Markdown
---
|
||
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`。
|