yaosutu 45e2af81f8 docs(changelog): 财务详情新增应收总额 payableAmount 字段双端管理后台 (#4321 )

财务Tab/订单详情头部/订单列表 3 个 admin 接口出参各新增 payableAmount(应收总额)派生字段。

2026-06-24 10:32:39 +08:00

5.8 KiB

原始文件 Blame 文件历史

财务详情新增「应收总额」payableAmount 字段（管理后台）

端类型：管理后台
变更类型：修改接口（3 个接口出参各新增 1 字段）
关联 Issue：#4321　PR：#4322
日期：2026-06-24

① 接口背景

订单财务此前只返回订单总价 totalAmount（= 产品原价，未扣优惠、未加增项），从总价直接到「待收尾款」中间缺一个承接节点，导致「订单总价 / 增加费用 / 优惠费用 / 待收尾款」勾稽链看着对不上。

本次新增派生字段 payableAmount（应收总额），补齐勾稽链：

订单总价 totalAmount
+ 增加费用 surchargeAmount
− 优惠费用 discountAmount
─────────────────────────
= 应收总额 payableAmount      ← 本次新增
− 已付 paidAmount
− 已退 refundAmount
─────────────────────────
= 待收尾款 balanceAmount

payableAmount 是后端实时算出的派生值（不落库），与既有 balanceAmount 口径完全一致，老订单自动对上。

② 变更清单

#	方法	路径	变更
1	GET	`/v3/admin/order/{id}/finance`	出参 FinanceVO 新增 `payableAmount`
2	GET	`/v3/admin/order/{id}`	出参 `data.main`（OrderMainVO）新增 `payableAmount`
3	GET	`/v3/admin/order/list`（别名 `/v3/admin/order`）	出参列表项 OrderListItemRespVO 新增 `payableAmount`

统一响应包装 Result<T>：{ code, message, data, success }，code=200 为成功。

仅新增字段，无入参变化、无字段删除/改名、无枚举变化。前端可按需取用，不取不影响既有逻辑。

③ 接口详情

1. 财务 Tab　`GET /v3/admin/order/{id}/finance`

出参 FinanceVO 新增 payableAmount。其余字段不变。

2. 订单详情头部　`GET /v3/admin/order/{id}`

出参 data.main（OrderMainVO）新增 payableAmount。其余字段不变。

3. 订单列表　`GET /v3/admin/order/list`

出参每个列表项（OrderListItemRespVO）新增 payableAmount。其余字段不变。

④ 入参

无变化（本次仅出参新增字段）。

⑤ 出参

新增字段（3 个接口一致）：

字段	类型	说明
payableAmount	string(decimal)	应收总额 = 订单总价 + 增加费用 − 优惠费用（≥0，字符串化防精度丢失）

与之关联的既有字段（口径参考，本次不变）：

字段	类型	说明
totalAmount	string(decimal)	订单总价（产品原价，未扣优惠/未加增项）
surchargeAmount	string(decimal)	增加费用汇总（仅 FinanceVO 有）
discountAmount	string(decimal)	优惠费用汇总（仅 FinanceVO 有）
paidAmount	string(decimal)	已付金额
refundAmount	string(decimal)	已退金额（仅 FinanceVO 有）
balanceAmount	string(decimal)	待收尾款 = 应收总额 − 已付 − 已退（≥0）

注：详情头部 main 与订单列表项不含 surchargeAmount/discountAmount 明细字段，但 payableAmount 已是含增减项后的应收净额，可直接展示。

⑥ 枚举 / 数据字典

无。

⑦ 错误码

无新增（查询接口正常返回 200）。

⑧ 示例

典型：财务 Tab（原价 3105 / 优惠 150 / 无增项 / 未支付）

请求 GET /v3/admin/order/2068235251926114306/finance，响应（节选）：

{ "code":200, "success":true, "data": {
  "totalAmount":"3105.00",
  "surchargeAmount":"0.00",
  "discountAmount":"150.00",
  "payableAmount":"2955.00",
  "paidAmount":"0.00",
  "refundAmount":"0.00",
  "balanceAmount":"2955.00"
} }

校验：payableAmount 2955 = 3105 + 0 − 150；balanceAmount 2955 = 2955 − 0 − 0。

边界：含增项 + 优惠 + 部分已付

原价 3105 / 增项 300 / 优惠 350 / 已付 1000：

{ "totalAmount":"3105.00", "surchargeAmount":"300.00", "discountAmount":"350.00",
  "payableAmount":"3055.00", "paidAmount":"1000.00", "refundAmount":"0.00", "balanceAmount":"2055.00" }

payableAmount 3055 = 3105 + 300 − 350；balanceAmount 2055 = 3055 − 1000 − 0。

订单列表

请求 GET /v3/admin/order/list?pageNo=1&pageSize=1：

{ "code":200, "data": { "records":[ { "totalAmount":"503.00", "payableAmount":"503.00", "balanceAmount":"0.00" } ] } }

⑨ 业务边界

payableAmount 是后端实时派生（不落库），任意时刻 = totalAmount + surchargeAmount − discountAmount，最小为 0。
与 balanceAmount 关系恒为：balanceAmount = payableAmount − paidAmount − refundAmount（≥0）。
增减项/优惠变化后，刷新接口即得到最新 payableAmount，无需前端自算。

⑩ 修改前后对比

	修改前	修改后
财务/详情/列表出参	只有 totalAmount（原价）、balanceAmount（待收）	新增 payableAmount（应收总额），勾稽链闭合
前端展示成交净额	需前端自己用总价+增项−优惠计算	直接取后端 payableAmount

⑪ 影响评估 / 回滚

非破坏性：仅新增出参字段，不删不改既有字段，前端零改动即兼容；需要展示「应收总额/成交价」时取用本字段。
回滚：后端回滚 PR #4322（字段消失，其余不变）。

⑫ 注意事项

金额字段均为字符串，前端按字符串处理防精度丢失。
payableAmount 已含增减项，前端不要再二次加减增项/优惠（会重复计算）。

⑬ 关联 / 联系人

Issue：wx/HL#4321
PR：wx/HL#4322
后端负责人：腰苏图
已部署测试服并网关实调验证通过（finance/详情头部/列表三接口均返 payableAmount 且勾稽对账一致）。

5.8 KiB 原始文件 Blame 文件历史 Unescape Escape