docs(changelog): mp下单页满团提示-报价补容量余量字段 (#3288/PR#3289)

changelogs/2026-06/01_fix_mp_quote_capacity_fields.md

@@ -0,0 +1,45 @@
+# 【小程序】下单页满团提示:C端实时报价新增班期容量余量字段
+
+> **类型**: 后端补字段(供前端做满团提示)
+> **服务**: hl-product-service-v2
+> **日期**: 2026-06-01
+> **影响范围**: `POST /mp/product/{id}/quote`(C端报价,出行信息弹窗 / 订单确认页)
+> **归属**: 后端已改(PR #3289 → dev,已同步 dev-v3)
+> **状态**: 已部署测试服并验证通过
+> **关联工单**: #3288
+> **需前端配合**: ⚠️ 是
+
+---
+
+## 一、问题
+
+下单流程(填写出行信息弹窗 / 订单确认页)能选择**超过班期剩余名额/库存**的人数并进到支付页,无任何提示。例:班期最大人数 26、线下报名人数 24 → 余名额仅 2,却可选成人 3 + 儿童 1 = 4 人到支付页(点支付才被后端 503 拦)。
+
+## 二、后端改动
+
+`POST /mp/product/{id}/quote` 的响应 `MpQuoteResultVO` 新增 4 字段(**仅 GROUP/小蒙马且请求带 `batchId` 时有值,CORE/CUSTOM 为 null**):
+
+| 字段 | 含义 |
+|------|------|
+| `maxParticipants` | 最大参与人数(0/空=不限) |
+| `remainParticipants` | 剩余可报名名额(= 最大人数 − 已报名人数含线下;`null`=不限) |
+| `remainStock` | 剩余房间库存(= 最大房间 − 有效订单含线下占位;`null`=不限) |
+| `capacityEnough` | 本次报价人数是否在剩余容量内(`true`=够位可下单,`false`=超员/售罄) |
+
+`capacityEnough` 计算:请求总人数(成人+儿童+小童+幼童) ≤ `remainParticipants`(不限恒真) **且** `remainStock` 非 0(房间未售罄)。
+
+> 价格字段不变;硬拦截仍在下单(超员 503109 / 房间不足 503106)。本次只是把**余量数据**给到前端做软提示。
+
+## 三、前端需要做(mmg)
+
+出行信息弹窗 + 订单确认页,基于报价返回的上述字段:
+1. **人数步进器封顶**:成人/儿童等总人数不允许超过 `remainParticipants`(为 null 时不限),`+` 到上限置灰。
+2. **超员/售罄提示**:`capacityEnough=false` 时提示「仅剩 N 个名额」/「该班期已满」,并**禁用「支付订金/支付」按钮**。
+3. 建议在展示「剩余 N 个名额」时用 `remainParticipants`;`remainStock` 可用于房间数选择封顶。
+
+## 四、测试服实测
+
+问题班期(最大人数 26 / 线下报名 24 → 余名额 2;最大房间 10 / 线下占位 9 → 余房 1):
+- 成人 3 + 儿童 1 = 4 人 → `capacityEnough=false`,`remainParticipants=2`,`remainStock=1`,`maxParticipants=26` ✓
+- 成人 4 → false ✓;成人 2(=余 2)→ true ✓;成人 1 → true ✓
+- 价格 `grandTotal` 正常返回(报价不受影响)