diff --git a/changelogs-v2/2026-07/27_5282_矩阵年度月度订单统计-新增接口-管理后台.md b/changelogs-v2/2026-07/27_5282_矩阵年度月度订单统计-新增接口-管理后台.md new file mode 100644 index 0000000..ea87737 --- /dev/null +++ b/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`。