# 【小程序】下单页满团提示: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` 正常返回(报价不受影响)