# 待收尾款 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/详情/列表）。
