diff --git a/changelogs-v2/2026-06/26_4432_4457_取消单财务口径应收待收归零-修改接口-管理后台.md b/changelogs-v2/2026-06/26_4432_4457_取消单财务口径应收待收归零-修改接口-管理后台.md new file mode 100644 index 0000000..ae83db6 --- /dev/null +++ b/changelogs-v2/2026-06/26_4432_4457_取消单财务口径应收待收归零-修改接口-管理后台.md @@ -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`:`{ 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)。