hl-api-changelog/changelogs-v2/2026-06/26_4432_4457_取消单财务口径应收待收归零-修改接口-管理后台.md

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

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

{
  "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 / 未支付：

{
  "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）。