# 已取消(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）。