hl-api-changelog/changelogs/2026-05/30_feat_group_offline_participants_count.md

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

类型: 后端行为增强(新增字段 + 满团口径) 服务: 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 ✓