67 行
2.5 KiB
Markdown
67 行
2.5 KiB
Markdown
# 微信小程序 · 订单详情尾款金额（balanceAmount）计算口径统一
|
||
|
||
- **变更日期**: 2026-04-23
|
||
- **PR**: #1306
|
||
- **端**: 微信小程序（管理端同步生效）
|
||
- **影响面**: 订单详情页尾款金额展示 + 下单流程 `paymentType` 回填
|
||
- **兼容性**: **前端零改动**；已付款的订单 balanceAmount 语义更严谨、更广泛
|
||
|
||
---
|
||
|
||
## 变化一：订单详情 `balanceAmount` 字段适用范围扩大 + 公式统一
|
||
|
||
### 以前
|
||
|
||
只在订金订单（`paymentType=DEPOSIT`）且 `depositAmount` 非空时返回 `balanceAmount`。全款订单（`paymentType=FULL`）**不返回该字段**（或为 null）。
|
||
|
||
### 现在
|
||
|
||
**所有订单**都返回 `balanceAmount`，统一口径：
|
||
|
||
```
|
||
balanceAmount = max(0, totalPrice - discountAmount + surchargeAmount - paidAmount)
|
||
```
|
||
|
||
- `paidAmount`：已支付金额（订金支付后 = 订金金额；尾款已付 = 全款）
|
||
- 永远 ≥ 0（不会出现负数）
|
||
- 全款订单 paidAmount=0 时 balance = totalPrice（未付）；paidAmount=totalPrice 时 balance = 0（已付清）
|
||
|
||
### 前端接入影响
|
||
|
||
- **原先用 `paymentType===DEPOSIT` 判断才读 `balanceAmount` 的逻辑可以保留**，仍然工作
|
||
- 如果想给全款订单也展示「待支付金额」，直接读 `balanceAmount` 即可
|
||
- "待支付金额 = 0" 代表订单已付清（可用于隐藏支付按钮）
|
||
|
||
---
|
||
|
||
## 变化二：下单时 `paymentType` 不再被 quote 覆盖为 `FULL`
|
||
|
||
### 以前
|
||
|
||
CORE 产品下单时，如果 quote 接口没返回 `paymentType`，后端会强制把订单 `paymentType` 设为 `FULL`，覆盖产品快照里的默认值。
|
||
|
||
### 现在
|
||
|
||
quote 返回 `paymentType` 非空 → 使用 quote 的值；quote 返回 null → **保留产品快照里的默认值**（`setProductInfoOnOrder` 阶段已设好）。
|
||
|
||
### 前端接入影响
|
||
|
||
- 下单后拿到的订单 `paymentType`（详情接口）会**更准确地反映产品本身的支付模式**（FULL / DEPOSIT）
|
||
- 原来因为这个覆盖逻辑导致 DEPOSIT 订金订单被错写成 FULL 的情况，不会再发生
|
||
|
||
---
|
||
|
||
## 不影响范围
|
||
|
||
- 下单请求体（`/mp/order/create`）**零变化**
|
||
- 订金/尾款金额（`depositAmount / depositRatio`）**零变化**
|
||
- 管理端订单详情 `balanceAmount` 逻辑**本次同步生效**（口径一致）
|
||
- 历史订单不回迁数据，但下次读详情时按新公式现算，**立即生效**
|
||
|
||
---
|
||
|
||
## 相关
|
||
|
||
- PR：[wx/HL#1306](https://git.1814.love:8443/wx/HL/pulls/1306)
|
||
- 部署：`hl-order-service-v2`（8094）
|