60 行
3.5 KiB
Markdown
60 行
3.5 KiB
Markdown
---
|
||
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 与补救 PR #5945 已合并 dev-v3 并部署测试服。fleets/fleetTeamIds 仅控制 fleets[] 展示行，grandTotal 恒为全车队合计；vehicles[] 补 actualAmount；整车队仅有费用时，非空 vehicleId 也按核单快照生成车辆明细，null vehicleId 只计入车队/全局合计。测试服只读健康返回 4 行且 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`；补救 PR `#5945`，squash merge `54db3fb9`。
|
||
- 主修 fresh 编译：763 个生产源、286 个测试源；补救 fresh 编译：765 个生产源、294 个测试源。
|
||
- 主修对账定向 29/29；补救 ReconciliationQueryServiceTest 27/27；ArchTest 13/13、spotless 均通过。
|
||
- Deploy Panel 主修任务 `20eca2f2`、补救任务 `86a6d76a` 均成功。
|
||
- 测试服 9443 网关主修实测：全量/旧 fleets/新 fleetTeamIds 三视图分别返回 4/1/1 行，grandTotal 六字段完全一致。
|
||
- 补救部署后只读健康复测：返回 4 行，grandTotal 为 estimated/payable `245993.06`、actual `0.00`、diff `-245993.06`、totalDays `298`、totalOrderCount `67`。测试服当前没有 actual 费用，纯费用车队下钻守恒由 fresh 单测覆盖，未为验收制造业务数据。
|
||
- 空筛选终审补救：PR `#5946`（merge `ddcecac6`）修复 null-only/blank-only 被误判成显式筛选；PR `#5947`（merge `29df4ddc`）补齐 `fleetTeamIds=[null]` 时回退有效 `fleets` 编码。定向测试 30/30、spotless 通过，Deploy Panel `00e42151` 成功；网关 `fleetTeamIds=` 实测 code 200、fleets=4、grandTotal 六字段不变。
|