fix(产品报价): 比例定金漏算单房差修复(测试服已部署验证) (HL #2994/PR #2995)

changelogs/2026-05/25_fix_deposit_ratio_include_single_room_surcharge.md

@@ -0,0 +1,57 @@
+# fix(产品报价): 比例定金漏算单房差修复(定金值变化,接口契约不变,前端无需改动)
+
+> **类型**: fix(后端计算修正,接口字段/结构不变)
+> **关联 PR/Issue**: PR #2995 (Closes #2994)
+> **日期**: 2026-05-25
+> **影响范围**: 所有「按比例收定金」且触发单房差的产品报价/下单
+> **接收方**: mmg(知会即可) + QA
+> **前端**: **无需改动**(depositAmount/balanceAmount 字段名与结构不变,仅取值修正)
+
+---
+
+## 🎯 背景
+
+核心产品按比例(如 10%)收定金时,定金漏算了单房差。
+
+示例(成人价4000 + 儿童价3000 + 单房差1000 = 总价8000,定金比例10%):
+
+- 修复前:定金 = (8000 - 1000) × 10% = **700**(错误,基数减掉了单房差)
+- 修复后:定金 = 8000 × 10% = **800**(正确,客户实付全款含单房差)
+
+---
+
+## 🔧 根因
+
+比例定金计算原先故意从基数中减掉单房差(代码注释标 D2,源自 PR #1901),与客户实付全款的口径不符。三处比例定金计算中只有一处已含单房差,另两处减掉了,行为不一致。本次统一为「比例定金按含单房差的总价计算」。
+
+---
+
+## ✅ 接口契约不变
+
+| 接口 | 字段 | 变化 |
+|------|------|------|
+| `POST /mp/product/{id}/quote` | `depositAmount` / `balanceAmount` | 字段不变,**取值修正(定金变大、尾款变小)** |
+| 下单接口(订单 `depositAmount`) | `depositAmount` | 同上 |
+
+**前端无需任何改动**。仅注意:比例定金 + 单房差场景下,展示的定金金额会比之前略高(原先少算了单房差对应的那部分定金),尾款相应减少,总价不变。
+
+---
+
+## ✅ 后端验证(测试服 e2e,真实产品 id=2056944461216100353)
+
+请求:date=2026-06-15,1成人+1儿童,定金比例 10%
+
+```
+GET  /internal/product/{id}/simple-quote   → totalPrice=8000.00, depositAmount=800.00  ✓ (订单创建链路)
+POST /internal/mp/product/{id}/quote       → grandTotal=8000.00, depositAmount=800.00, balanceAmount=7200.00  ✓
+```
+
+修复前同场景定金为 700,现已修正为 800。单元测试 90 用例全绿。
+
+---
+
+## ⚠️ 不受影响
+
+- 固定金额/人定金模式不受影响(仍按定金人头计,幼童不计定金)
+- 全款模式不受影响
+- 不触发单房差(成人数 ≠ 1)的场景不受影响