feat(changelog): 取消单财务口径修正 — payableAmount/balanceAmount 对 CANCELLED 订单固定归零（PR#4432+#4457）
- 涉及接口：GET /v3/admin/order/list、GET /v3/admin/order/{id}、GET /v3/admin/order/{id}/finance
- 仅 orderStatus=CANCELLED 订单受影响；非取消单口径不变
- payableAmount(应收总额)：取消=合同作废=应收消灭，固定0
- balanceAmount(待收尾款)：取消终态无待收，固定0
- totalAmount/paidAmount/refundAmount 历史台账保留不变
- 关联 Issue #4431/#4456，PR #4432/#4457
这个提交包含在：
yaosutu
父节点
037b82eaaa
当前提交
93aac89a3e
@ -0,0 +1,267 @@
|
|||||||
|
# 已取消(CANCELLED)订单「应收总额 payableAmount」与「待收尾款 balanceAmount」归零修正（管理后台）
|
||||||
|
|
||||||
|
- 端类型：管理后台
|
||||||
|
- 变更类型：修改接口（取值口径修正，字段签名不变；⚠️仅 CANCELLED 订单数值变化）
|
||||||
|
- 关联 Issue：#4431（待收归零）、#4456（应收归零） PR：#4432、#4457
|
||||||
|
- 日期：2026-06-26
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ① 接口背景
|
||||||
|
|
||||||
|
订单取消（`orderStatus=CANCELLED`）是终态——合同终止、未来不再有任何应收。但此前 `payableAmount`（应收总额）和 `balanceAmount`（待收尾款）对取消单仍按正常公式派生，导致出现：
|
||||||
|
|
||||||
|
- **应收非 0**：取消单还显示「应收 3105 元」，财务误以为应该催款。
|
||||||
|
- **待收异常大**：退款不回减已付金额（paidAmount 是毛累计），取消+退款单会被算出「待收 ≈ 整单额」，财务以为欠款待催。
|
||||||
|
|
||||||
|
两次修正：
|
||||||
|
1. **PR #4432**（`balanceAmount` 归零）：取消单待收尾款固定为 0，不再按公式派生。原因：合同终止后无待收，且旧公式在「取消+已退款」场景下把退款反算为欠款，严重误导财务。
|
||||||
|
2. **PR #4457**（`payableAmount` 归零）：取消单应收总额固定为 0。原因：取消=合同作废=应收关系消灭，无应收；同时补齐财务勾稽链，避免「应收非零、待收为零」自相矛盾（见下方勾稽链说明）。
|
||||||
|
|
||||||
|
**修正后取消单勾稽链（完全闭合）**：
|
||||||
|
|
||||||
|
```
|
||||||
|
payableAmount（应收总额）= 0 ← 本次固定
|
||||||
|
paidAmount（已付） = 历史值（不变，台账保留）
|
||||||
|
refundAmount（已退） = 历史值（不变，台账保留）
|
||||||
|
totalAmount（订单总价） = 历史值（不变，产品原价快照）
|
||||||
|
balanceAmount（待收尾款） = 0 ← 本次固定
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ② 变更清单
|
||||||
|
|
||||||
|
| # | 方法 | 路径 | 变更 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 1 | GET | `/v3/admin/order/list`（别名 `/v3/admin/order`） | 列表项 OrderListItemRespVO：`payableAmount`、`balanceAmount` 对 CANCELLED 订单固定返回 `"0"` |
|
||||||
|
| 2 | GET | `/v3/admin/order/{id}` | 出参 `data.main`（OrderMainVO）：`payableAmount`、`balanceAmount` 对 CANCELLED 订单固定返回 `"0"` |
|
||||||
|
| 3 | GET | `/v3/admin/order/{id}/finance` | 出参 FinanceVO：`payableAmount`、`balanceAmount` 对 CANCELLED 订单固定返回 `"0"` |
|
||||||
|
|
||||||
|
> 统一响应包装 `Result<T>`：`{ code, message, data, success }`，`code=200` 为成功。
|
||||||
|
>
|
||||||
|
> **仅 `orderStatus=CANCELLED` 的订单受影响**；非取消单的任何字段均不变。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ③ 接口详情
|
||||||
|
|
||||||
|
### 1. 订单列表 `GET /v3/admin/order/list`
|
||||||
|
|
||||||
|
- 认证：Bearer JWT（管理后台）
|
||||||
|
- 幂等：是（纯查询）
|
||||||
|
- 限流：无特殊限制
|
||||||
|
- 使用场景：订单列表页每行展示「应收总额/待收尾款」财务列；取消单固定显示 0，不再误导催款。
|
||||||
|
|
||||||
|
### 2. 订单详情头部 `GET /v3/admin/order/{id}`
|
||||||
|
|
||||||
|
- 认证：Bearer JWT（管理后台）
|
||||||
|
- 幂等：是（纯查询）
|
||||||
|
- 限流：无特殊限制
|
||||||
|
- 使用场景：订单详情页顶部财务摘要区；取消单显示「应收 0 / 待收 0」传达已结清语义。
|
||||||
|
|
||||||
|
### 3. 财务 Tab `GET /v3/admin/order/{id}/finance`
|
||||||
|
|
||||||
|
- 认证：Bearer JWT（管理后台）
|
||||||
|
- 幂等：是（纯查询）
|
||||||
|
- 限流：无特殊限制
|
||||||
|
- 使用场景：订单详情财务 Tab 完整明细；取消单勾稽链展示为「应收 0 / 已付 X / 已退 X / 待收 0」。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ④ 入参
|
||||||
|
|
||||||
|
无变化（3 个接口入参均未改动）。
|
||||||
|
|
||||||
|
### 财务 Tab 路径参数（参考）
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| id | long(string) | 是 | 订单 ID（雪花 ID，路径参数）|
|
||||||
|
|
||||||
|
### 订单列表查询参数（节选，参考）
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| pageNo | integer | 是 | 页码（从 1 开始）|
|
||||||
|
| pageSize | integer | 是 | 每页条数 |
|
||||||
|
| orderStatus | string | 否 | 按状态筛选（传 `CANCELLED` 可只看取消单）|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑤ 出参
|
||||||
|
|
||||||
|
### 口径修正字段（3 个接口统一）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 本次变化 | 修正后语义 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| payableAmount | string(decimal) | **取消单固定返回 `"0"`** | CANCELLED=0；其余=总价+增项−优惠（≥0）|
|
||||||
|
| balanceAmount | string(decimal) | **取消单固定返回 `"0"`** | CANCELLED=0；其余=应收−已付+已退（≥0）|
|
||||||
|
|
||||||
|
### 不变字段（台账保留，历史值不清零）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| totalAmount | string(decimal) | 订单总价（产品原价快照）—— 取消单保留原价，不变 |
|
||||||
|
| paidAmount | string(decimal) | 历史已付金额（毛累计）—— 取消单保留历史值，不变 |
|
||||||
|
| refundAmount | string(decimal) | 历史已退金额（毛累计）—— 取消单保留历史值，不变 |
|
||||||
|
| surchargeAmount | string(decimal) | 增加费用汇总（仅 FinanceVO）—— 不变 |
|
||||||
|
| discountAmount | string(decimal) | 优惠费用汇总（仅 FinanceVO）—— 不变 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑥ 枚举 / 数据字典
|
||||||
|
|
||||||
|
涉及订单状态枚举（参考，用于理解受影响范围）：
|
||||||
|
|
||||||
|
| 枚举值 | 中文标签 | 受本次修正影响？ |
|
||||||
|
|---|---|---|
|
||||||
|
| CANCELLED | 已取消 | **是**（payableAmount/balanceAmount 固定为 0）|
|
||||||
|
| PENDING | 待支付 | 否 |
|
||||||
|
| PAID | 已支付 | 否 |
|
||||||
|
| IN_PROGRESS | 出行中 | 否 |
|
||||||
|
| COMPLETED | 已完成 | 否 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑦ 错误码
|
||||||
|
|
||||||
|
无新增（查询接口正常返回 code=200）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑧ 示例
|
||||||
|
|
||||||
|
### 8.1 典型：取消单财务 Tab（应收/待收归零后）
|
||||||
|
|
||||||
|
订单已取消，原价 3105 / 优惠 0 / 从未支付：
|
||||||
|
|
||||||
|
请求 `GET /v3/admin/order/2068235251926114306/finance`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"totalAmount": "3105.00",
|
||||||
|
"surchargeAmount": "0.00",
|
||||||
|
"discountAmount": "0.00",
|
||||||
|
"payableAmount": "0",
|
||||||
|
"paidAmount": "0.00",
|
||||||
|
"refundAmount": "0.00",
|
||||||
|
"balanceAmount": "0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
校验：取消单 payableAmount=0、balanceAmount=0；totalAmount=3105 保留历史原价。
|
||||||
|
|
||||||
|
### 8.2 边界：取消+已退款单（最能体现修正价值的场景）
|
||||||
|
|
||||||
|
订单已取消，原价 3105 / 优惠 0 / 已付定金 800 / 全退 800：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"totalAmount": "3105.00",
|
||||||
|
"surchargeAmount": "0.00",
|
||||||
|
"discountAmount": "0.00",
|
||||||
|
"payableAmount": "0",
|
||||||
|
"paidAmount": "800.00",
|
||||||
|
"refundAmount": "800.00",
|
||||||
|
"balanceAmount": "0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
修正前：balanceAmount 旧公式 = 3105 − 800 + 800 = 3105（误报"欠款 3105"）；修正后固定 0，财务不会再误判催款。
|
||||||
|
|
||||||
|
### 8.3 正常单对比（非 CANCELLED，不受影响）
|
||||||
|
|
||||||
|
订单状态 PENDING，原价 3105 / 优惠 150 / 未支付：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"totalAmount": "3105.00",
|
||||||
|
"surchargeAmount": "0.00",
|
||||||
|
"discountAmount": "150.00",
|
||||||
|
"payableAmount": "2955.00",
|
||||||
|
"paidAmount": "0.00",
|
||||||
|
"refundAmount": "0.00",
|
||||||
|
"balanceAmount": "2955.00"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
非 CANCELLED 订单的口径与此前完全一致，payableAmount/balanceAmount 按公式正常派生，**不受本次修正影响**。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑨ 业务边界
|
||||||
|
|
||||||
|
**适用（本次修正生效）**：
|
||||||
|
- `orderStatus=CANCELLED` 的订单，全部接口的 payableAmount 和 balanceAmount 均固定返回 `"0"`。
|
||||||
|
- 无论取消前是否有支付/退款记录，payableAmount 和 balanceAmount 均为 0。
|
||||||
|
|
||||||
|
**不适用（口径不变）**：
|
||||||
|
- `orderStatus≠CANCELLED` 的全部订单——应收/待收仍按原有公式派生，不受本次改动影响。
|
||||||
|
|
||||||
|
**特殊边界**：
|
||||||
|
- 历史台账字段（`totalAmount` / `paidAmount` / `refundAmount`）对取消单**保留历史值不清零**，供财务审计追溯。
|
||||||
|
- 取消单的 `totalAmount` 仍是产品原价快照，不代表"应收"，前端展示时注意语义区分（原价 vs 应收）。
|
||||||
|
- 若取消后再发起退款（极少数场景），`refundAmount` 会更新历史值，但 `payableAmount` 和 `balanceAmount` 仍固定为 0。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑩ 修改前后对比
|
||||||
|
|
||||||
|
### 字段级对比（仅 CANCELLED 订单）
|
||||||
|
|
||||||
|
| 字段 | 修改前 | 修改后 |
|
||||||
|
|---|---|---|
|
||||||
|
| payableAmount | 按公式派生（总价+增项−优惠，可能非零）| **固定 `"0"`** |
|
||||||
|
| balanceAmount | 按公式派生（应收−已付+已退，可能非零）| **固定 `"0"`** |
|
||||||
|
| totalAmount | 不变 | 不变（历史原价保留）|
|
||||||
|
| paidAmount | 不变 | 不变（历史已付保留）|
|
||||||
|
| refundAmount | 不变 | 不变（历史已退保留）|
|
||||||
|
|
||||||
|
### 行为级对比
|
||||||
|
|
||||||
|
| 场景 | 修改前 | 修改后 |
|
||||||
|
|---|---|---|
|
||||||
|
| 取消未付单 | payableAmount=3105（误，无应收关系）| payableAmount=0（正确）|
|
||||||
|
| 取消+全退单 | balanceAmount=3105（误，误报欠款）| balanceAmount=0（正确）|
|
||||||
|
| 财务勾稽链 | 取消单「应收非零+待收非零」自相矛盾 | 取消单「应收 0 / 待收 0」完全闭合 |
|
||||||
|
| 非取消单 | — | 完全不变 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑪ 影响评估 / 回滚
|
||||||
|
|
||||||
|
**破坏兼容性评估**：
|
||||||
|
- 字段签名不变（字段名/类型均未变），结构兼容。
|
||||||
|
- 但 **CANCELLED 订单的 `payableAmount` 和 `balanceAmount` 数值会从「旧算法值」变为 `"0"`**，属于语义修正，前端展示数字会变化。
|
||||||
|
- 如果前端有针对取消单 `payableAmount`/`balanceAmount` 做非零判断（如「若待收>0 显示催款按钮」），取消单的该判断会自动消除——这是预期行为。
|
||||||
|
|
||||||
|
**前端同步上线**：无需前端改代码，接口数值自动修正，前端渲染字段取值即可。建议前端同步告知财务人员：「已取消订单的应收和待收均为 0，是修正后的正确值」。
|
||||||
|
|
||||||
|
**回滚方案**：
|
||||||
|
- 后端回滚 PR #4432（balanceAmount 归零逻辑）+ PR #4457（payableAmount 归零逻辑）即可恢复旧算法。
|
||||||
|
- 3 个接口均为无状态查询，回滚零风险，不涉及数据写入。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑫ 注意事项
|
||||||
|
|
||||||
|
- 金额字段均为**字符串（string/decimal）**，前端按字符串处理，勿做 JS number 精度运算。
|
||||||
|
- 取消单的 `totalAmount`（订单总价/产品原价）仍是历史快照非零值，它代表「产品曾经值多少钱」，不代表「还需要收多少钱」——如需展示「原价」用 `totalAmount`，展示「待收」用 `balanceAmount`（取消单固定 0）。
|
||||||
|
- 已取消订单在财务口径上：应收 0、待收 0，历史已付/已退保留台账，前端展示时注意区分「原价 vs 应收 vs 已付 vs 已退」四个语义。
|
||||||
|
- 本次修正**仅影响 `orderStatus=CANCELLED`** 的订单，与其他状态的计算逻辑完全隔离。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑬ 关联 / 联系人
|
||||||
|
|
||||||
|
- Issue（待收归零）：https://git.1814.love:8443/wx/HL/issues/4431
|
||||||
|
- PR（待收归零）：https://git.1814.love:8443/wx/HL/pulls/4432
|
||||||
|
- Issue（应收归零）：https://git.1814.love:8443/wx/HL/issues/4456
|
||||||
|
- PR（应收归零）：https://git.1814.love:8443/wx/HL/pulls/4457
|
||||||
|
- 后端负责人：腰苏图
|
||||||
|
- 已合并至 dev-v3，测试服部署后可用取消单实调验证（finance/详情头部/列表 三接口取消单 payableAmount=0、balanceAmount=0）。
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户