From 747510fe083fcbbbf96893abdb9443fd30ad1549 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 13 Aug 2026 00:38:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(fleet):=20=E5=8F=91=E5=B8=83#5929=E5=AF=B9?= =?UTF-8?q?=E8=B4=A6=E8=81=9A=E5=90=88=E5=A5=91=E7=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- ...仅控制展示行且全量合计恒定-修改接口-管理后台.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 changelogs-v2/2026-08/13_5929_车费对账筛选仅控制展示行且全量合计恒定-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/13_5929_车费对账筛选仅控制展示行且全量合计恒定-修改接口-管理后台.md b/changelogs-v2/2026-08/13_5929_车费对账筛选仅控制展示行且全量合计恒定-修改接口-管理后台.md new file mode 100644 index 0000000..f967495 --- /dev/null +++ b/changelogs-v2/2026-08/13_5929_车费对账筛选仅控制展示行且全量合计恒定-修改接口-管理后台.md @@ -0,0 +1,57 @@ +--- +schema: "hl-changelog/v2" +ticket: "5929" +title: "车费对账车队筛选仅控制展示行且全量合计恒定" +consumer: "admin" +change_type: "修改接口" +author: "wx(GIT)" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "pending" +target_release: "v2.1" +verified_at: "2026-08-13" +updated_at: "2026-08-13" +status_note: "后端 PR #5944 已合并 dev-v3 并部署测试服。fleets/fleetTeamIds 仅控制 fleets[] 展示行，grandTotal 恒为全车队合计；vehicles[] 补 actualAmount，fee-only 行从核单快照回显车辆信息。测试服三视图 4/1/1 行且 grandTotal 六字段完全一致。" +base: "dev-v3" +--- + +# 车费对账车队筛选与全量合计口径对齐（#5929） + +## 变更接口 + +| 方法 | 路径 | 变化 | +|---|---|---| +| `GET` | `/admin/fleet/reconciliation/cars` | 修正筛选与合计语义，补齐车辆实际金额契约 | +| `GET` | `/admin/fleet/reconciliation/export/cars` | 保持 active prep 导出语义，不导出仅有费用的车辆占位行 | + +## 请求参数 + +- `fleetTeamIds[]`：新版车队 ID 分组展示维度，传入后优先于 `fleets`。 +- `fleets[]`：旧版车队稳定编码兼容参数。 +- 两者都只控制响应 `fleets[]` 返回哪些车队行，不过滤顶部 `grandTotal` 的聚合数据。 + +## 响应变化 + +- `grandTotal` 始终统计期间内全部车队、全部 active prep 和全部核单费用，不随车队展示筛选变化。 +- `vehicles[].actualAmount` 明确为该车辆核单实际费用合计，金额字符串。 +- 有核单费用但无 active prep 的 fee-only 车辆仍进入对应车队明细： + - 车牌、车型、座位优先使用核单费用快照； + - 快照缺失时车型/座位回退车辆现值； + - 已删除车辆也不会丢失已有快照身份。 +- `vehicleId=null` 的无归属费用计入车队/全局实际合计，但不伪造车辆明细。 + +## 前端适配 + +- 折叠或筛选车队时，顶部 KPI 仍显示全车队总计，不应再按当前展示行自行重算。 +- 车辆实际结算列读取 `vehicles[].actualAmount`。 +- fee-only 行的 `days/orderCount/estimated/payable` 可为 0，但 `actualAmount` 可大于 0，应正常展示。 + +## 验证证据 + +- PR `#5944`，squash merge `7df9b66f`。 +- fresh 编译：763 个生产源、286 个测试源。 +- 对账定向 29/29、ArchTest 13/13、spotless 通过。 +- Deploy Panel 任务 `20eca2f2` 成功。 +- 测试服 9443 网关实测：全量/旧 fleets/新 fleetTeamIds 三视图分别返回 4/1/1 行；`estimated/payable/actual/diff/totalDays/totalOrderCount` 六字段完全一致。