diff --git a/changelogs-v2/2026-09/15_7669_v3审计快照核单日志补齐需求归属-修复-管理后台.md b/changelogs-v2/2026-09/15_7669_v3审计快照核单日志补齐需求归属-修复-管理后台.md new file mode 100644 index 00000000..d2277157 --- /dev/null +++ b/changelogs-v2/2026-09/15_7669_v3审计快照核单日志补齐需求归属-修复-管理后台.md @@ -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> 以及 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": [""], + "planServiceDates": ["2026-10-25", "2026-10-30"], + "planTopologyFingerprint": null +} +~~~ + +### 2. v3 双需求摘要 + +TRAVEL 与 TRANSFER 并存、费用明细覆盖两条需求时: + +~~~json +{ + "itemCount": 4, + "totalAmount": 1313, + "snapshotType": "DAILY", + "requirementIds": ["", ""], + "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": [""], + "planServiceDates": ["2026-10-25", "2026-10-30"], + "planTopologyFingerprint": null + }, + "afterValue": { + "itemCount": 2, + "totalAmount": 510.0, + "snapshotType": "DAILY", + "requirementIds": [""], + "planServiceDates": ["2026-10-25", "2026-10-30"], + "planTopologyFingerprint": null + } +} +~~~ + +### 4. 纯 v1 / v2 历史日志 + +纯旧版本日志仍返回原字段,字段和值均不改写: + +~~~json +{ + "itemCount": 2, + "totalAmount": 510.0, + "snapshotType": "DAILY", + "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 同字段归一均有自动化测试。