changelog-filename-gate / validate (push) Successful in 1s

详情

修改原因：管理后台已完成 #5282 年度月度订单统计消费，需要收口前端消费状态。

修改内容：将 frontend_status 更新为 implemented，关联前端提交 7d0589d6，并同步更新状态说明。

实际验证：source 测试 46 项通过，文件名、frontmatter、路径别名及差异空白检查全部通过。

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

2026-07-27 16:18:18 +08:00

4.6 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base, generated

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

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

4.6 KiB 原始文件 Blame 文件历史 Unescape Escape