docs(changelog): publish #7669 vehicle fee audit ownership
changelog-filename-gate / validate (push) Failing after 2s
changelog-filename-gate / validate (push) Failing after 2s
这个提交包含在：
API Changelog Bot
@@ -0,0 +1,166 @@
|
|||||||
|
---
|
||||||
|
schema: "hl-changelog/v2"
|
||||||
|
ticket: "7669"
|
||||||
|
title: "v3 审计快照核单日志补齐车辆费用摘要需求归属"
|
||||||
|
consumer: "admin"
|
||||||
|
author: "wx(GIT)"
|
||||||
|
change_type: "修复"
|
||||||
|
backend_status: "deployed"
|
||||||
|
gateway_status: "verified"
|
||||||
|
frontend_status: "pending"
|
||||||
|
frontend_owner: "mmg"
|
||||||
|
frontend_ref: ""
|
||||||
|
target_release: ""
|
||||||
|
verified_at: "2026-09-15"
|
||||||
|
status_note: "GET /v3/admin/order/{orderId}/settlement/logs 路径和顶层响应不变；changeItems 中 field=vehicleFeeSummary 的 JsonNode 动态结构补齐需求归属。纯 v1/v2 摘要逐字段不变，仍为 requirementId；纯 v3 摘要为完整 requirementIds；混合 v2→v3 日志把两侧统一成 requirementIds 数组，避免前端渲染两条互斥变更。只有 hl.order.settlement.vehicle-fee-audit-v3-write-enabled=true 后新写入的 v3 日志才出现新结构；测试环境验证后已恢复缺省 false。前端 mmg 需按本文兼容规则消费。"
|
||||||
|
updated_at: "2026-09-15"
|
||||||
|
base: "dev-v3"
|
||||||
|
---
|
||||||
|
|
||||||
|
# v3 审计快照核单日志补齐车辆费用摘要需求归属（修复）
|
||||||
|
|
||||||
|
> **服务**: hl-order-service-v3
|
||||||
|
> **PR**: #7729
|
||||||
|
> **Issue**: #7669（Refs #7439）
|
||||||
|
> **日期**: 2026-09-15
|
||||||
|
> **影响范围**: 管理后台核单操作日志中 vehicleFeeSummary 的动态 JSON；无新端点、无路由变化、无 DDL、无新增错误码
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚠️ 关键变化
|
||||||
|
|
||||||
|
🔴 **前端需要更新车辆费用摘要的归属读取规则。**
|
||||||
|
|
||||||
|
GET /v3/admin/order/{orderId}/settlement/logs 的路径、分页参数、顶层 Result<PageResult<...>> 以及 changeItems[] 外层字段均不变。变化仅发生在：
|
||||||
|
|
||||||
|
- changeItems[].field == "vehicleFeeSummary"
|
||||||
|
- 且日志由 v3 快照生成，或同一条 diff 的任一侧为 v3
|
||||||
|
- 此时摘要中的需求归属字段为 requirementIds: string[]
|
||||||
|
|
||||||
|
新字段返回该车辆费用快照覆盖的**全部需求 ID**，按确定性顺序去重；不再把双需求单压成单值或 null。
|
||||||
|
|
||||||
|
### 版本兼容矩阵
|
||||||
|
|
||||||
|
| before / after 快照 | 两侧摘要归属字段 | 前端读取口径 |
|
||||||
|
|---|---|---|
|
||||||
|
| 纯 v1 / v2 | requirementId: string 或 null | 保持旧逻辑，响应逐字段兼容 |
|
||||||
|
| 纯 v3 | requirementIds: string[] | 读取完整数组 |
|
||||||
|
| v2 → v3 混合 diff | 两侧都为 requirementIds: string[] | v2 单值归一为单元素数组；按同一字段比较 |
|
||||||
|
|
||||||
|
**不要**在混合 diff 中把 requirementId 与 requirementIds 当成两个独立业务字段渲染，否则会出现“旧归属消失 + 新归属新增”两条互相矛盾的变化。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、接口清单
|
||||||
|
|
||||||
|
| 接口 | 方法 | 路径 | 变更类型 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 查询核单操作日志 | GET | /v3/admin/order/{orderId}/settlement/logs | 动态响应字段修复；外层契约不变 |
|
||||||
|
|
||||||
|
常用分页参数：current=1&pageSize=20，其中 pageSize 最大为 20。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 二、响应结构变化
|
||||||
|
|
||||||
|
### 1. v3 单需求摘要
|
||||||
|
|
||||||
|
~~~json
|
||||||
|
{
|
||||||
|
"itemCount": 2,
|
||||||
|
"totalAmount": 510.0,
|
||||||
|
"snapshotType": "DAILY",
|
||||||
|
"requirementIds": ["<requirementId>"],
|
||||||
|
"planServiceDates": ["2026-10-25", "2026-10-30"],
|
||||||
|
"planTopologyFingerprint": null
|
||||||
|
}
|
||||||
|
~~~
|
||||||
|
|
||||||
|
### 2. v3 双需求摘要
|
||||||
|
|
||||||
|
TRAVEL 与 TRANSFER 并存、费用明细覆盖两条需求时：
|
||||||
|
|
||||||
|
~~~json
|
||||||
|
{
|
||||||
|
"itemCount": 4,
|
||||||
|
"totalAmount": 1313,
|
||||||
|
"snapshotType": "DAILY",
|
||||||
|
"requirementIds": ["<travelRequirementId>", "<transferRequirementId>"],
|
||||||
|
"planServiceDates": ["2026-10-26", "2026-10-27", "2026-10-28", "2026-10-31"],
|
||||||
|
"planTopologyFingerprint": null
|
||||||
|
}
|
||||||
|
~~~
|
||||||
|
|
||||||
|
### 3. v2 → v3 混合 diff
|
||||||
|
|
||||||
|
后端会在生成同一条 vehicleFeeSummary 改动项时，把 v2 的单值归属转换成单元素数组，使两侧字段名和类型一致：
|
||||||
|
|
||||||
|
~~~json
|
||||||
|
{
|
||||||
|
"field": "vehicleFeeSummary",
|
||||||
|
"fieldName": "车辆费用摘要",
|
||||||
|
"beforeValue": {
|
||||||
|
"itemCount": 2,
|
||||||
|
"totalAmount": 500.0,
|
||||||
|
"snapshotType": "DAILY",
|
||||||
|
"requirementIds": ["<requirementId>"],
|
||||||
|
"planServiceDates": ["2026-10-25", "2026-10-30"],
|
||||||
|
"planTopologyFingerprint": null
|
||||||
|
},
|
||||||
|
"afterValue": {
|
||||||
|
"itemCount": 2,
|
||||||
|
"totalAmount": 510.0,
|
||||||
|
"snapshotType": "DAILY",
|
||||||
|
"requirementIds": ["<requirementId>"],
|
||||||
|
"planServiceDates": ["2026-10-25", "2026-10-30"],
|
||||||
|
"planTopologyFingerprint": null
|
||||||
|
}
|
||||||
|
}
|
||||||
|
~~~
|
||||||
|
|
||||||
|
### 4. 纯 v1 / v2 历史日志
|
||||||
|
|
||||||
|
纯旧版本日志仍返回原字段，字段和值均不改写：
|
||||||
|
|
||||||
|
~~~json
|
||||||
|
{
|
||||||
|
"itemCount": 2,
|
||||||
|
"totalAmount": 510.0,
|
||||||
|
"snapshotType": "DAILY",
|
||||||
|
"requirementId": "<requirementId>",
|
||||||
|
"planServiceDates": ["2026-10-25", "2026-10-30"],
|
||||||
|
"planTopologyFingerprint": null
|
||||||
|
}
|
||||||
|
~~~
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、前端兼容建议
|
||||||
|
|
||||||
|
1. 只在 field == "vehicleFeeSummary" 时应用本规则。
|
||||||
|
2. 摘要存在 requirementIds 时按 string[] 读取和展示完整集合。
|
||||||
|
3. 摘要只有 requirementId 时按旧格式读取；可在前端内部归一成零或一个元素的数组。
|
||||||
|
4. 一条 changeItems 记录只渲染一处“需求归属”差异；不要同时按两个 JSON 属性各生成一条变化。
|
||||||
|
5. ID 是雪花 ID，保持字符串处理，禁止转 JavaScript Number。
|
||||||
|
|
||||||
|
该接口的 beforeValue/afterValue 在 Java VO 中是 JsonNode，Swagger 只描述动态节点，无法表达本文嵌套版本矩阵；当前 OpenAPI 自动 diff lane 未配置，以本 changelog 为前端交接真本。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、生效与回滚条件
|
||||||
|
|
||||||
|
- **生效条件**：Nacos hl.order.settlement.vehicle-fee-audit-v3-write-enabled=true 后，**新写入**的 v3 车辆费用审计日志使用新摘要结构。
|
||||||
|
- 历史纯 v1/v2 日志不会被批量改写，仍返回 requirementId。
|
||||||
|
- 测试环境已临时打开开关完成网关验证，并恢复原始配置（缺省 false）；是否再次开闸由后端发布流程决定。
|
||||||
|
- hl.order.settlement.fleet-empty-write-enabled 与本次摘要读取契约无绑定，本次测试中始终保持缺省 false。
|
||||||
|
- 回滚后端或关闭 v3 写开关只影响后续写入；前端必须继续保留 v1/v2 兼容读取。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、验证结果
|
||||||
|
|
||||||
|
- 测试部署：hl-order-service-v3 dev-v3 816b1b522 0/N ok。
|
||||||
|
- 网关：hl-gateway dev-v3 83c1b1743 57/N ok；无路由变更。
|
||||||
|
- 经测试网关验证单需求、双需求 v3 摘要，requirementIds 与 order_settlement_vehicle_fee.requirement_id 集合完全一致。
|
||||||
|
- 实测 change_items 大小分别为 675 bytes、807 bytes，均远低于 64 KiB。
|
||||||
|
- 1000 明细极限用例生成的 changeItems 低于 64 KiB；v1/v2 golden、v2→v3 同字段归一均有自动化测试。
|
||||||
在新工单中引用
屏蔽一个用户