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