# 【管理后台 + 小程序】小蒙马新增「线下报名人数」,计入已报名人数与人数满团

> **类型**: 后端行为增强(新增字段 + 满团口径)
> **服务**: hl-product-service-v2
> **日期**: 2026-05-30
> **影响范围**: 班期编辑 / 班期展示 / 人数满团判定
> **归属**: 后端已改(PR #3282 → dev,已同步 dev-v3)
> **状态**: 已部署测试服并验证通过
> **关联工单**: #3281(承接 #3279)

---

## 一、背景

此前「线下占位」`manualOrderCount` 只是**房数**(占房间维度),「已报名人数」只算线上聚合订单人数。现新增「线下报名人数」,使线下一笔预订既占房也占人,与线上口径对齐。

## 二、新增字段 `manualParticipantCount`(线下报名人数)

- **班期编辑**(`POST/PUT /admin/product/item/{id}/schedule`,ScheduleSaveReqVO):新增可填项 `manualParticipantCount`(运营手动线下报名真实人数,默认 0,不能为负;为负返回错误码 `410205`)。
- **已报名人数 = 线上聚合订单人数 + 线下报名人数**。
- **人数满团**:`remainParticipants = 最大参与人数 - 已报名人数(含线下)`;线下报名人数也能把班期顶到 `FULL`。
- 与 `manualOrderCount`(线下占位房数,占房间维度)对称:线下一笔预订,房用 `manualOrderCount`、人用 `manualParticipantCount`。

### 响应新增/变化字段

| 接口 | VO | 字段 |
|------|-----|------|
| `GET /admin/product/item/{id}/schedule/list` | ScheduleRespVO | 新增 `manualParticipantCount`;`enrolledPeople` 现含线下 |
| `GET /admin/product/item/{id}/pricing-calendar` | UnifiedPricingCalendarItemVO | `enrolledPeople`/`remainStock` 口径不变,人数维度已含线下 |
| `GET /mp/product/{id}/schedules` | MpScheduleRespVO | 新增 `manualParticipantCount`;`enrolledCount`(已报名人数)现含线下 |

## 三、小程序展示「已报名人数」(建议前端补展示)

后端数据已齐备,小程序班期可直接展示:
- `enrolledCount` = 已报名人数(线上 + 线下)
- `maxParticipants` = 最大参与人数(0/空=不限)
- `remainParticipants` = 剩余名额(不限时 null)

> 建议 mmg 在班期卡片展示「已报名 X 人 / 共 Y 人」或「剩余 N 个名额」。`batchStatus=FULL` 时显示「已满」(房间或人数任一满都会是 FULL)。

## 四、兼容性

- `manualParticipantCount` 为 0/null = 无线下报名人数,行为与上一版(PR #3280)完全一致,**向后兼容零影响**。
- 顺带修正了上一版遗留的 Swagger 注释(maxParticipants 现已卡满团与下单;remainParticipants 现返回真实剩余名额)。

## 五、测试服实测

班期 maxParticipants=30、maxRooms=0(房间不限)、线上0单:
- 线下报名人数=7 → 已报名人数 enrolledPeople=7、remainParticipants=23 ✓
- 线下报名人数=30(=上限)→ remainParticipants=0、`batchStatus=FULL`(纯线下报名顶满团)✓
- 复原线下=0 → remainParticipants=30、ENROLLING ✓
