docs(changelog-v2): #4601 调整记录金额返字符串+终止onsiteBalance拒负(知悉)

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

@@ -0,0 +1,24 @@
+# 订单调整记录金额字段统一返字符串 + 终止接口 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 正常（现网无调整记录数据，金额字符串口径由注解保证、与既有金额字段同款）。