# 微信小程序 · 订单详情尾款金额（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）