From 328ee7b6baaa5aa38df7116fbaf3e0f59a8ce7a1 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 27 Apr 2026 14:09:25 +0800
Subject: [PATCH] =?UTF-8?q?docs(order-v2):=20Breaking=20-=20PR=20#1320=20?=
 =?UTF-8?q?=E5=88=A0=E9=99=A4=E8=AE=A2=E5=8D=95=E8=AF=A6=E6=83=85=20pendin?=
 =?UTF-8?q?gUpgradeAmount=20=E5=AD=97=E6=AE=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...order-v2_pending-upgrade-amount-removed.md | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 changelogs/2026-04/27_breaking_order-v2_pending-upgrade-amount-removed.md

diff --git a/changelogs/2026-04/27_breaking_order-v2_pending-upgrade-amount-removed.md b/changelogs/2026-04/27_breaking_order-v2_pending-upgrade-amount-removed.md
new file mode 100644
index 0000000..ff8c201
--- /dev/null
+++ b/changelogs/2026-04/27_breaking_order-v2_pending-upgrade-amount-removed.md
@@ -0,0 +1,51 @@
+# ⚠️ Breaking: 订单详情响应硬删 `pendingUpgradeAmount` 字段
+
+**日期**: 2026-04-27
+**PR**: #1320 (T+2 周收尾, 主 PR #1318)
+**类型**: Breaking — 字段从响应中移除
+**影响端**: 管理后台 (admin) + 微信小程序 (mp)
+
+---
+
+## 影响接口
+
+- `GET /admin/orders/{id}`(订单详情 - 管理端)
+- `GET /mp/orders/{id}`(订单详情 - 小程序端)
+
+两个接口的响应顶层 `OrderDetailVO` **不再返回** `pendingUpgradeAmount` 字段。
+
+## 字段含义(已废弃)
+
+```
+"pendingUpgradeAmount": "0.00"   // 待确认差价总额(配房/配车升级未确认)
+```
+
+主 PR #1318 (2026-04-23) 上线 V2 流程后, 差价已归并入 `OrderDiscount`(负) / `OrderSurcharge`(正), 该字段值已恒为 `0.00`(兼容字段)。今天 (T+2 周) 完成硬删。
+
+## 前端动作
+
+### 必须 ✅
+- 移除任何对响应 `pendingUpgradeAmount` 字段的读取与渲染代码(`undefined` 不会触发渲染异常,但属于死代码)
+
+### 建议 (如确实需要差价) ✅
+- 走订单优惠/增项明细字段 — 各自带 `confirmed` 状态:
+  - `discounts: [{ amount, confirmed, sourceType, ...}]`
+  - `surcharges: [{ amount, confirmed, sourceType, ...}]`
+- 用 `surchargeAmount` 字段(已确认增项总额)代替原"待确认差价"用途时,需注意语义已变为**已确认**
+
+## 不受影响的字段(保留)
+
+- `OrderDetailVO.discountAmount`(优惠总额)
+- `OrderDetailVO.surchargeAmount`(增项总额)
+- `OrderDetailVO.depositAmount` / `depositRatio`(订金)
+- 其它金额字段全部不动
+
+## 部署时机
+
+- dev 已合并 (`af55ee62`), 测试服部署后立即生效
+- 正式服将在测试服稳定 ≥ 24h 后部署
+
+## 关联
+
+- 主 PR #1318 (订单内部流程 V2, 已合并 2026-04-23)
+- 后端 changelog: `hl-backend-changelog/changelogs/2026-04/2026-04-27_order-v2_t2-cleanup-pending-upgrade-amount-and-dict-hard-delete.md`