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