hl-api-changelog/changelogs-v2/2026-06/48_4601_订单调整记录金额字段返字符串_终止onsiteBalance拒负_知悉-管理后台.md

订单调整记录金额字段统一返字符串 + 终止接口 onsiteBalance 拒负（知悉）

模块：订单调整记录 / 终止行程（管理后台） 类型：出参金额序列化对齐 + 入参校验加固（PR #4601 已合 dev-v3 + 测试服实测）· 知悉/防御类，前端一般无需改动 关联工单：无（2026-06-28 每日代码审查批量收口，via workflow） 日期：2026-06-28

背景

每日代码审查发现今日新增的「订单调整记录」(#4540) 与「终止行程 onsite_balance」(#4581) 有两处契约细节需对齐项目惯例，已修复。均为「按惯例本就该如此」的对齐/加固，前端若已按惯例处理则无需改动。

变更 1（GET /v3/admin/order/{id}/adjustment-record）出参金额按惯例返字符串

调整记录的金额字段补 @JsonSerialize(ToStringSerializer)，与项目所有金额字段（如 OrderBasicVO.balanceAmount）口径一致，以 JSON 字符串返回（如 "1000.00" 而非数字 1000.0）：

• balanceBefore（调整前应付尾款）
• balanceAfter（调整后应付尾款）
• 每个 items[].amountDelta（本项声明价差）

前端解析这三个字段请按字符串处理（与其余金额字段一致）。

变更 2（POST /v3/admin/order/{id}/terminate）入参 onsiteBalance 拒绝负数

onsiteBalance（现场实收尾款）补非负校验：传负数将返 400 现场实收尾款不能为负。现场实收语义不应为负，前端正常不会传负，此为后端防御性加固。（注：adjustAmount 人工调整额仍允许负，不受影响。）

测试服实测

• POST /v3/admin/order/{id}/terminate 传 onsiteBalance:-1 → 400 现场实收尾款不能为负；传 500 → 过校验走业务（正常）。
• GET /v3/admin/order/{id}/adjustment-record 端点 200 正常（现网无调整记录数据，金额字符串口径由注解保证、与既有金额字段同款）。