From 9965b110fb9feda3644efd739ff62f40c4e192fc Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Wed, 24 Jun 2026 14:37:43 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=BE=85=E6=94=B6=E5=B0=BE?=
 =?UTF-8?q?=E6=AC=BE=20balanceAmount=20=E9=80=80=E6=AC=BE=E5=8F=A3?=
 =?UTF-8?q?=E5=BE=84=E4=BF=AE=E6=AD=A3=20+=20=E8=AF=A6=E6=83=85=E5=A4=B4?=
 =?UTF-8?q?=E9=83=A8/=E5=88=97=E8=A1=A8=E8=A1=A5=20refundAmount=20?=
 =?UTF-8?q?=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0=20(#4333)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

balanceAmount 修正(有退款订单数值变大,无退款不变)+ main/list 新增 refundAmount。
---
 ...��符号修正+列表头部补已退款-修改接口-管理后台.md | 146 ++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 changelogs-v2/2026-06/24_4333_待收尾款退款符号修正+列表头部补已退款-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-06/24_4333_待收尾款退款符号修正+列表头部补已退款-修改接口-管理后台.md b/changelogs-v2/2026-06/24_4333_待收尾款退款符号修正+列表头部补已退款-修改接口-管理后台.md
new file mode 100644
index 0000000..59bcb23
--- /dev/null
+++ b/changelogs-v2/2026-06/24_4333_待收尾款退款符号修正+列表头部补已退款-修改接口-管理后台.md
@@ -0,0 +1,146 @@
+# 待收尾款 balanceAmount 退款口径修正 + 详情头部/列表补 refundAmount（管理后台）
+
+- 端类型：管理后台
+- 变更类型：修改接口（balanceAmount 语义修正 ⚠️数值会变 + 2 接口出参新增 refundAmount）
+- 关联 Issue：#4333　PR：#4334
+- 日期：2026-06-24
+
+---
+
+## ① 接口背景
+
+修复「待收尾款」`balanceAmount` 在**有退款订单上算错**的 bug，并补齐「已退款」字段。
+
+此前 `balanceAmount` 把已退款金额**多减了一次**：order_main 的 `paidAmount`（已付）是毛累计、退款不回减，`refundedAmount`（已退）是另一个毛累计，二者独立。商家实际净收 = 已付 − 已退。但旧公式 `应收 − 已付 − 已退` 等于把退款反向减了，导致有退款订单的待收尾款偏小（误差 = 2×退款额）。
+
+**修正后口径**：
+```
+待收尾款 balanceAmount = 应收总额 − 净已付
+                      = payableAmount − (paidAmount − refundAmount)
+                      = totalAmount + surchargeAmount − discountAmount − paidAmount + refundAmount   （≥0）
+```
+
+> 无退款订单（refundAmount=0）`balanceAmount` **数值不变**；仅有退款订单会变大（修正为正确值）。
+
+---
+
+## ② 变更清单
+
+| # | 方法 | 路径 | 变更 |
+|---|---|---|---|
+| 1 | GET | `/v3/admin/order/{id}/finance` | `balanceAmount` 口径修正（⚠️有退款订单数值变大）|
+| 2 | GET | `/v3/admin/order/{id}` | `data.main`：`balanceAmount` 口径修正 + **新增 `refundAmount`** |
+| 3 | GET | `/v3/admin/order/list`（别名 `/v3/admin/order`）| 列表项：`balanceAmount` 口径修正 + **新增 `refundAmount`** |
+
+> finance 接口此前已有 `refundAmount`，本次仅口径修正；详情头部 main 与列表项本次新增 `refundAmount`。
+
+统一响应包装 `Result<T>`：`{ code, message, data, success }`，`code=200` 为成功。
+
+---
+
+## ③ 接口详情
+
+3 个接口的「待收尾款」`balanceAmount` 统一改为「应收 − 净已付（已付 − 已退）」口径。详情头部、订单列表新增 `refundAmount`（已退款金额），供财务明细展示「已退款」行，使「应收 − 已付 + 已退 = 待收」可见链闭合。
+
+---
+
+## ④ 入参
+
+无变化。
+
+---
+
+## ⑤ 出参
+
+| 字段 | 类型 | 说明 | 本次 |
+|---|---|---|---|
+| balanceAmount | string(decimal) | 待收尾款 = 应收 − 已付 + 已退（≥0）| **口径修正**（有退款订单数值变大）|
+| refundAmount | string(decimal) | 已退款金额（= order_main.refunded_amount）| 详情头部/列表 **新增**（finance 已有）|
+
+关联既有字段（口径参考，不变）：
+| 字段 | 说明 |
+|---|---|
+| totalAmount | 订单总价（产品原价）|
+| payableAmount | 应收总额 = 总价 + 增项 − 优惠 |
+| paidAmount | 已付金额（毛累计，退款不回减）|
+
+---
+
+## ⑥ 枚举 / 数据字典
+
+无。
+
+---
+
+## ⑦ 错误码
+
+无。
+
+---
+
+## ⑧ 示例
+
+### 典型：付定金后又全额退款（净已付 0）
+订单原价 3105 / 优惠 300 / 应收 2805 / 付定金 500 / 全退 500：
+```json
+{ "code":200, "data": {
+  "totalAmount":"3105.00", "discountAmount":"300.00", "surchargeAmount":"0.00",
+  "payableAmount":"2805.00", "paidAmount":"500.00", "refundAmount":"500.00",
+  "balanceAmount":"2805.00"
+} }
+```
+校验：balanceAmount 2805 = 2805 − (500 − 500)。客户净付 0，仍欠全额。
+（修正前此单 balanceAmount 错误返回 1805。）
+
+### 边界：部分退款
+应收 6010 / 已付 1000 / 已退 300：
+```json
+{ "payableAmount":"6010.00", "paidAmount":"1000.00", "refundAmount":"300.00", "balanceAmount":"5310.00" }
+```
+balanceAmount 5310 = 6010 − (1000 − 300)。
+
+### 无退款（不受影响）
+应收 2805 / 已付 0 / 已退 0：`balanceAmount`=2805（与修正前一致）。
+
+---
+
+## ⑨ 业务边界
+
+- `balanceAmount` 派生（不落库），= payableAmount − paidAmount + refundAmount，最小 0。
+- `paidAmount` 是毛累计已付（退款不会减少它），`refundAmount` 是毛累计已退，净已付 = 二者之差。
+- 财务明细建议展示：订单总价 → −优惠 → 应收总额 → −已付 → +已退 → 待收尾款。
+
+---
+
+## ⑩ 修改前后对比
+
+| | 修改前 | 修改后 |
+|---|---|---|
+| balanceAmount（有退款单）| 应收 − 已付 − 已退（退款被多减，偏小）| 应收 − 已付 + 已退（正确）|
+| balanceAmount（无退款单）| 应收 − 已付 | 不变 |
+| 详情头部/列表 refundAmount | 无 | 新增 |
+| 示例单 2068651577349992450 | 1805（错）| 2805（对）|
+
+---
+
+## ⑪ 影响评估 / 回滚
+
+- **⚠️ 数值变化（非破坏字段结构）**：**有退款订单**的 `balanceAmount` 返回值会变大（这是修正，旧值是错的）；无退款订单不变。前端财务/列表展示的待收尾款会随之更新，无需改字段，但需知悉数值口径已修正。
+- 详情头部/列表新增 `refundAmount` 为非破坏新增，前端按需取用展示「已退款」行。
+- 回滚：后端回滚 PR #4334。
+
+---
+
+## ⑫ 注意事项
+
+- 金额字段均为字符串，前端按字符串处理防精度丢失。
+- 财务明细的「待收尾款」= 应收 − 已付 + 已退；展示「已退款」行时金额取 `refundAmount`。
+
+---
+
+## ⑬ 关联 / 联系人
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/4333
+- PR：https://git.1814.love:8443/wx/HL/pulls/4334
+- 后端负责人：腰苏图
+- 已部署测试服并网关实调验证通过（36 单恒等式校验全过，含 4 单有退款；示例单 balanceAmount 1805→2805，refundAmount=500 出现在 finance/详情/列表）。