# 财务详情新增「应收总额」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 且勾稽对账一致）。