wx/hl-api-changelog

派生 0

文件

T

Mimingguang 489ed1df0c

changelog-filename-gate / validate (push) Failing after 3s

详情

chore(changelog): #7669 核单日志归属字段前端判 not_required(通用渲染天然兼容)

2026-09-15 12:21:04 +08:00

6.6 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7669	v3 审计快照核单日志补齐车辆费用摘要需求归属	admin	wx(GIT)	修复	deployed	verified	not_required	mmg			2026-09-15	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 需按本文兼容规则消费。前端判 not_required(mmg 2026-09-15):全仓唯一消费 settlement/logs 的 SettlementLogTab.vue 对 changeItems 走通用渲染(对象 JSON 原文直出,一行一 changeItem),从不解析 requirementId/requirementIds 为业务字段,版本矩阵天然满足;混合 diff 由后端归一两侧键,前端无双行矛盾可能;雪花 ID 无数值化。无业务改动,frontend_ref 留空。	2026-09-15	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 单需求摘要

{
  "itemCount": 2,
  "totalAmount": 510.0,
  "snapshotType": "DAILY",
  "requirementIds": ["<requirementId>"],
  "planServiceDates": ["2026-10-25", "2026-10-30"],
  "planTopologyFingerprint": null
}

2. v3 双需求摘要

TRAVEL 与 TRANSFER 并存、费用明细覆盖两条需求时：

{
  "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 的单值归属转换成单元素数组，使两侧字段名和类型一致：

{
  "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 历史日志

纯旧版本日志仍返回原字段，字段和值均不改写：

{
  "itemCount": 2,
  "totalAmount": 510.0,
  "snapshotType": "DAILY",
  "requirementId": "<requirementId>",
  "planServiceDates": ["2026-10-25", "2026-10-30"],
  "planTopologyFingerprint": null
}

三、前端兼容建议

只在 field == "vehicleFeeSummary" 时应用本规则。
摘要存在 requirementIds 时按 string[] 读取和展示完整集合。
摘要只有 requirementId 时按旧格式读取；可在前端内部归一成零或一个元素的数组。
一条 changeItems 记录只渲染一处“需求归属”差异；不要同时按两个 JSON 属性各生成一条变化。
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 同字段归一均有自动化测试。

6.6 KiB 原始文件 Blame 文件历史 Unescape Escape