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

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

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<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`，响应（节选）：
+```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 且勾稽对账一致）。