From 28c627b8e13559bb3c224ca36f9499876bd8f611 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 28 Jun 2026 23:58:08 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20#4601=20=E8=B0=83?= =?UTF-8?q?=E6=95=B4=E8=AE=B0=E5=BD=95=E9=87=91=E9=A2=9D=E8=BF=94=E5=AD=97?= =?UTF-8?q?=E7=AC=A6=E4=B8=B2+=E7=BB=88=E6=AD=A2onsiteBalance=E6=8B=92?= =?UTF-8?q?=E8=B4=9F(=E7=9F=A5=E6=82=89)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...段返字符串_终止onsiteBalance拒负_知悉-管理后台.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 changelogs-v2/2026-06/48_4601_订单调整记录金额字段返字符串_终止onsiteBalance拒负_知悉-管理后台.md diff --git a/changelogs-v2/2026-06/48_4601_订单调整记录金额字段返字符串_终止onsiteBalance拒负_知悉-管理后台.md b/changelogs-v2/2026-06/48_4601_订单调整记录金额字段返字符串_终止onsiteBalance拒负_知悉-管理后台.md new file mode 100644 index 0000000..53cb722 --- /dev/null +++ b/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 正常（现网无调整记录数据，金额字符串口径由注解保证、与既有金额字段同款）。