yaosutu 9965b110fb docs(changelog): 待收尾款 balanceAmount 退款口径修正 + 详情头部/列表补 refundAmount 管理后台 (#4333 )

balanceAmount 修正(有退款订单数值变大,无退款不变)+ main/list 新增 refundAmount。

2026-06-24 14:37:43 +08:00

5.5 KiB

原始文件 Blame 文件历史

待收尾款 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：

{ "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：

{ "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：wx/HL#4333
PR：wx/HL#4334
后端负责人：腰苏图
已部署测试服并网关实调验证通过（36 单恒等式校验全过，含 4 单有退款；示例单 balanceAmount 1805→2805，refundAmount=500 出现在 finance/详情/列表）。

5.5 KiB 原始文件 Blame 文件历史 Unescape Escape