diff --git a/changelogs-v2/2026-06/24_4321_财务详情新增应收总额payableAmount-修改接口-管理后台.md b/changelogs-v2/2026-06/24_4321_财务详情新增应收总额payableAmount-修改接口-管理后台.md new file mode 100644 index 0000000..4e4d137 --- /dev/null +++ b/changelogs-v2/2026-06/24_4321_财务详情新增应收总额payableAmount-修改接口-管理后台.md @@ -0,0 +1,169 @@ +# 财务详情新增「应收总额」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`:`{ 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`,响应(节选): +```json +{ "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: +```json +{ "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`: +```json +{ "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:https://git.1814.love:8443/wx/HL/issues/4321 +- PR:https://git.1814.love:8443/wx/HL/pulls/4322 +- 后端负责人:腰苏图 +- 已部署测试服并网关实调验证通过(finance/详情头部/列表 三接口均返 payableAmount 且勾稽对账一致)。