docs(changelog): 小蒙马新增线下报名人数计入已报名与人数满团 (#3281/PR#3282)

changelogs/2026-05/30_feat_group_offline_participants_count.md

@@ -0,0 +1,51 @@
+# 【管理后台 + 小程序】小蒙马新增「线下报名人数」,计入已报名人数与人数满团
+
+> **类型**: 后端行为增强(新增字段 + 满团口径)
+> **服务**: 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 ✓