From 0ef33be11d2c7c43fdcfcbe8d8ad9e27463a88da Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 30 May 2026 12:28:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=B0=8F=E8=92=99=E9=A9=AC?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=E7=BA=BF=E4=B8=8B=E6=8A=A5=E5=90=8D=E4=BA=BA?= =?UTF-8?q?=E6=95=B0=E8=AE=A1=E5=85=A5=E5=B7=B2=E6=8A=A5=E5=90=8D=E4=B8=8E?= =?UTF-8?q?=E4=BA=BA=E6=95=B0=E6=BB=A1=E5=9B=A2=20(#3281/PR#3282)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...0_feat_group_offline_participants_count.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 changelogs/2026-05/30_feat_group_offline_participants_count.md diff --git a/changelogs/2026-05/30_feat_group_offline_participants_count.md b/changelogs/2026-05/30_feat_group_offline_participants_count.md new file mode 100644 index 0000000..5c7a953 --- /dev/null +++ b/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 ✓