fix(mp-quote): /mp/product/{id}/quote 单房差 singleRoomDiff 按需返回(仅成人=1) — 通知前端 (#3190)

changelogs/2026-05/28_fix_mp_quote_single_room_diff_conditional.md

@@ -0,0 +1,42 @@
+# 【前端】小程序报价 /mp/product/{id}/quote: 单房差 singleRoomDiff 改为按需返回
+
+> **类型**: 后端接口契约调整(fix,后端已改并部署测试服验证通过)
+> **服务**: hl-product-service-v2
+> **日期**: 2026-05-28
+> **影响范围**: 小程序「产品报价」`POST /mp/product/{id}/quote` 返回体的 `singleRoomDiff` 字段
+> **归属**: 后端已修(PR #3190 → dev,#3191 同步 dev-v3),本条同步契约变化给前端(mmg)
+> **状态**: 已部署测试服并验证通过,前端可直接联调
+
+---
+
+## 一、问题
+
+`/mp/product/{id}/quote` 之前**不论几个成人,`singleRoomDiff` 都返回配置值**(如 500),导致小程序在 2 人及以上时也展示单房差。
+
+业务规则:**单房差只在「成人=1」(单人成行)时收取**。该规则是后端硬编码(`PricingRuleHelper`,触发条件不可配置;可配置的只是单房差金额)。价格本身(`grandTotal`)一直是对的,只有展示字段 `singleRoomDiff` 没对齐。
+
+## 二、改动(后端已完成)
+
+`singleRoomDiff` 现在**仅在本次实际收取(成人=1)时返回配置值,其余人数返回 `null`**:
+
+| 字段 | 调整前 | 调整后 |
+|------|--------|--------|
+| `singleRoomDiff` | 永远返回配置值(如 500) | 成人=1 → 返回 500;成人≠1 → **null** |
+| `singleRoomSurcharge` | 本次实际加价(成人=1 为值,否则 0) | 不变 |
+| `grandTotal` | 已正确(仅成人=1 含单房差) | 不变 |
+
+> 仅作用于 C端 `/mp/product/{id}/quote`;admin / 内部 Feign / 订单侧不变。
+
+## 三、前端建议
+
+- 单房差展示直接按 `singleRoomDiff != null` 判断即可(成人≠1 时为 null,不展示)。
+- 如需「实际加价金额」用于价格明细,以 `singleRoomSurcharge` 为准(成人≠1 恒为 0)。
+
+## 四、测试服实测(产品 2045345825172639746,单房差配置=500,日期 2026-05-28)
+
+| 请求 | singleRoomDiff | singleRoomSurcharge | grandTotal |
+|------|----------------|---------------------|------------|
+| 成人=2 | **null** | 0 | 6.0 |
+| 成人=1 | 500.0 | 500.0 | 503.0 |
+| 成人=1 + 儿童=1 | 500.0 | 500.0 | 506.0 |
+| 成人=3 | **null** | 0 | 9.0 |