From 61e5fe6968941e19e806b4c07756b6e03a4cb4aa Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sat, 9 May 2026 10:06:30 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20admin=20=E8=AE=A2=E5=8D=95=E8=AF=A6?=
 =?UTF-8?q?=E6=83=85=E6=8E=A5=E5=8F=A3=E6=9A=B4=E9=9C=B2=E5=8D=95=E6=88=BF?=
 =?UTF-8?q?=E5=B7=AE=E9=87=91=E9=A2=9D=E5=AD=97=E6=AE=B5=20(PR=20#1904)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ...dmin_order_detail_single_room_surcharge.md | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 changelogs/2026-05/09_feat_admin_order_detail_single_room_surcharge.md

diff --git a/changelogs/2026-05/09_feat_admin_order_detail_single_room_surcharge.md b/changelogs/2026-05/09_feat_admin_order_detail_single_room_surcharge.md
new file mode 100644
index 0000000..c0ea176
--- /dev/null
+++ b/changelogs/2026-05/09_feat_admin_order_detail_single_room_surcharge.md
@@ -0,0 +1,98 @@
+# admin 订单详情接口暴露单房差金额字段
+
+> **服务**: hl-order-service-v2(8094)
+> **PR**: #1904 (Refs #1900)
+> **日期**: 2026-05-09
+> **影响范围**: 管理端订单详情页
+
+---
+
+## ⚠️ 关键变化
+
+**admin 订单详情接口** `GET /admin/order/{orderId}` **新增**响应字段 `singleRoomSurcharge`(`BigDecimal`,`@Nullable`)。
+
+PR #1901 实现单房差功能后,只有 mp 端订单详情(`MpOrderDetailVO.priceBreakdown.items`)展示了"单房差"行,**管理端订单详情**(`OrderDetailVO`)看不到单房差金额(只读 totalPrice/surchargeAmount/discountAmount 汇总)。本 PR 补上 admin 端字段。
+
+---
+
+## 一、变更接口
+
+| # | 接口 | 方法 | 路径 | 变更 |
+|---|------|------|------|------|
+| 1 | 管理端订单详情 | GET | `/admin/order/{orderId}` | 响应 +1 字段 `singleRoomSurcharge: BigDecimal` |
+
+## 二、字段语义
+
+| 场景 | `singleRoomSurcharge` 值 |
+|------|---------|
+| 下单时 `adultCount==1` 且产品/班期配了单房差 | 该单房差金额(>0,如 `200.00`) |
+| 下单时 `adultCount>=2` 不触发单房差 | `null` |
+| 老订单(PR #1901 上线前下的)`priceBreakdown` JSON 缺字段 | `null` |
+| 老订单 `priceBreakdown=null` | `null` |
+| `priceBreakdown` JSON 含字段但值为 0 | `null`(零值不展示,与 mp 端口径对齐) |
+
+**口径**:与 mp 端 `MpOrderDetailVO.priceBreakdown.items` 中"单房差"行的展示口径完全对齐(>0 才视为有效),通过 `MpOrderDetailAssembler.parseSingleRoomSurcharge` 复用解析能力,**单一来源**。
+
+## 三、响应示例
+
+**有单房差订单**:
+
+```json
+{
+  "code": 200,
+  "data": {
+    "orderId": "2052xxxxxxxxxxxxx",
+    "totalPrice": 4180.00,
+    "surchargeAmount": null,
+    "singleRoomSurcharge": 200.00,
+    "depositAmount": 398.00,
+    ...
+  }
+}
+```
+
+**老订单 / 不触发场景**:
+
+```json
+{
+  "code": 200,
+  "data": {
+    "orderId": "2052xxxxxxxxxxxxx",
+    "totalPrice": 1500.00,
+    "surchargeAmount": null,
+    "singleRoomSurcharge": null,
+    ...
+  }
+}
+```
+
+## 四、前端改动建议(mmg 管理端)
+
+订单详情页**金额构成区域**(目前展示总价 / 优惠 / 附加费 / 订金)新增一行:
+
+```
+单房差: ¥200.00     (仅当 singleRoomSurcharge > 0 / 非 null 时展示)
+```
+
+- `null` → 整行隐藏(老订单 / 不触发场景)
+- `>0` → 展示,金额格式 `¥XXX.XX`
+
+文案/位置可参考既有"附加费"行(`surchargeAmount`)样式,但二者**不互通**(单房差不进 surchargeAmount,语义独立)。
+
+## 五、向后兼容
+
+- 老 admin 前端不读 `singleRoomSurcharge` → 字段被忽略,不报错
+- 老订单 `priceBreakdown` JSON 缺字段 → 接口返 `null`,前端按 `null` 隐藏
+- mp 端订单详情**完全不变**(本 PR 不动 mp 端)
+
+## 六、测试覆盖
+
+- `OrderDetailQueryServiceTest` +3 用例(JSON 含字段 / 缺字段 / null)
+- `MpOrderDetailAssemblerTest` +4 用例(parseSingleRoomSurcharge: null/空/缺字段/=0/>0)
+- 测试服已部署 dev:`GET /admin/order/{老订单id}` 返 `singleRoomSurcharge: null` 验证字段路径打通(图省略,字段已在 RespVO keys 里)
+
+## 七、@mmg 关注点
+
+1. 管理端订单详情页金额区加"单房差"行(条件展示)
+2. 字段命名与 mp 端 `priceBreakdown.items` 中 label="单房差" 行的 amount 对齐
+3. 老订单字段为 null 时整行隐藏