docs(changelog): 通知前端 — tier-compare 加 district / 班期 maxRooms 脱钩 / 团期库存模型重构(3 项,均测试服验证通过)

changelogs/2026-05/29_feat_admin_group_batch_maxrooms_decouple.md

@@ -0,0 +1,29 @@
+# 【管理后台】小蒙马班期「最大房间数」与行程脱钩,按团期自由填
+
+> **类型**: 后端行为调整(feat) + 前端回显 BUG
+> **服务**: hl-product-service-v2
+> **日期**: 2026-05-29
+> **影响范围**: 管理后台班期编辑 `POST/PUT /admin/product/item/{id}/schedule` 的 `maxRooms`
+> **归属**: 后端已改(PR #3261 → dev,已同步 dev-v3)
+> **状态**: 已部署测试服并验证通过
+> **关联工单**: #3258
+
+---
+
+> ⚠️ 本条只讲 `maxRooms` 行为。同一「班期编辑表单」本期还有一次**更大的库存模型重构**(删库存上限、新增订单数/线下占位、可报名取 remainStock、班期状态等),**以《小蒙马团期库存模型重构》那篇为准**,本条与其不冲突(maxRooms 仍是容量、按前端传值存)。
+
+## 一、后端变更
+
+班期保存时 `maxRooms`(最大房间数)此前在传 null/0 时会被强行改成行程的房间数(defaultRoomCount),造成与行程耦合。现已**脱钩**:
+
+- 前端传什么存什么;**传 0 存 0(0=不限),不再被行程房间数覆盖**。
+- 不再有"改行程房间数同步班期"的逻辑。
+
+## 二、前端待办(BUG)
+
+- **编辑班期时「最大房间数」要正确回显已存值**(此前实测库里=9 但编辑框显示 1,属前端回显 bug)。
+- 「最大房间数」为自由输入,新建班期默认值由前端决定,不再从行程带值。
+
+## 三、测试服实测
+
+班期保存 `maxRooms=0` 落库 0、`maxRooms=7` 落库 7,均不被行程房间数覆盖。

changelogs/2026-05/29_feat_group_batch_stock_model_refactor.md

@@ -0,0 +1,59 @@
+# 【管理后台+小程序】小蒙马团期库存模型重构(删库存上限·订单数/线下占位·已报名聚合·班期状态)
+
+> **类型**: 后端模型重构(feat,含字段增删)
+> **服务**: hl-product-service-v2 + hl-order-service-v2
+> **日期**: 2026-05-29
+> **影响范围**: 管理后台班期编辑/列表 + 小程序班期列表(下方逐接口列出)
+> **归属**: 后端已改(PR #3267 + #3269 → dev,已同步 dev-v3)
+> **状态**: 已部署测试服并验证通过
+> **关联工单**: #3266
+
+---
+
+## 一、模型总览(前端先理解这套口径)
+
+- **容量只看「最大房间数」`maxRooms`**(0/null=不限)。「最大人数」不再作为限制,人数仅展示。
+- **删除「库存上限」**(原 `productStockLimit`)。
+- **「订单数(消耗)」= 实时线上订单数 + 线下占位数(相加)**;1 单 = 1 房。
+- **库存/可报名 = `maxRooms − 订单数`**,后端实时算、**不落库**。
+- **已报名人数 = 聚合活跃订单总人数**,后端实时算、不落库。
+- 库存=0 不能开启「报名中」;下单占库存、取消/退款释放(后端自动,前端无需处理)。
+
+## 二、管理后台·班期编辑(`POST` / `PUT /admin/product/item/{id}/schedule`,ScheduleSaveReqVO)
+
+**字段调整:**
+- ❌ 移除 `productStockLimit`(库存上限)输入。
+- ➕ 新增 `manualOrderCount`(**线下占位房数**,可空,默认 0,不能为负):用于运营把线下/电话占的房手动占进库存,恒加在实时线上订单之上。
+- `maxRooms`(最大房间数=容量)保留。
+
+**保存校验(后端会拒绝):**
+- `manualOrderCount` 为负 → `code 410203 线下占位数不能为负数`。
+- 若该班期库存已 ≤ 0 却要置/保持「报名中」→ `code 410204 库存不足,无法开启报名中`。
+
+## 三、管理后台·班期列表/回显(`GET /admin/product/item/{id}/schedule/list`,ScheduleRespVO)
+
+- ❌ 移除 `enrolledCount`(旧人数计数器)、`bookedRooms`、`productStockLimit`。
+- ➕ 新增(均后端实时计算,只读):
+  - `manualOrderCount` — 回显线下占位数
+  - `orderCount` — 有效订单数(= 实时线上订单数 + 线下占位)
+  - `enrolledPeople` — 已报名人数(聚合)
+  - `remainStock` — 库存/可报名(= maxRooms − orderCount;**null = 不限**)
+
+## 四、小程序·班期列表(`GET /mp/product/{id}/schedules`,MpScheduleRespVO)
+
+- **返回该产品全部团期(含已出发,仅排除已删除)**,前端按状态展示。
+- 每条 `batchStatus`(前端**只对 `ENROLLING` 放开报名按钮**,其余禁止报名):
+  - `ENROLLING` 报名中(可报名)
+  - `FINISHED` 报名结束(已出发 / 报名截止日已过 / 出发前 1 天)
+  - `FULL` 已满额(售罄)
+  - `CANCELLING` / `CANCELLED` 取消中 / 已取消
+- 字段语义:
+  - `enrolledCount` → 现为**已报名人数(聚合)**
+  - `remainFamilies` → **可报名/库存**(= remainStock;null=不限)。**前端「还可报 X 组」取此字段**。
+  - `remainParticipants` → 恒 `null`(人数不再限制)
+
+## 五、测试服实测
+
+- 加法库存:maxRooms=5、线下占位=2、线上 0 单 → `orderCount=2`、`remainStock=3`、`enrolledPeople=0`。
+- 库存=0 开报名中被拒(410204);线下占位负数被拒(410203)。
+- mp `/schedules` 返回含已出发团期并标 `FINISHED`;售罄标 `FULL`。

changelogs/2026-05/29_feat_mp_tier_compare_add_district.md

@@ -0,0 +1,46 @@
+# 【小程序】档位对比 /mp/product/{id}/tier-compare 住宿项新增「区/县」district 字段
+
+> **类型**: 后端出参新增字段(feat,向后兼容)
+> **服务**: hl-product-service-v2 + hl-resource-service
+> **日期**: 2026-05-29
+> **影响范围**: 小程序端 `GET /mp/product/{id}/tier-compare` 每个住宿项
+> **归属**: 后端已改(PR #3259 → dev,已同步 dev-v3)
+> **状态**: 已部署测试服并验证通过
+> **关联工单**: 无(直接报 BUG)
+
+---
+
+## 一、变更点
+
+档位对比接口的住宿项此前只返回城市 `city`,现在**同时返回区/县 `district`**,与 `city` 并列。
+
+```json
+{
+  "code": 200,
+  "data": {
+    "tiers": [
+      {
+        "tierSeq": 2,
+        "tierName": "豪华",
+        "hotels": [
+          {
+            "dayNumber": 1,
+            "hotelName": "海拉尔首旅京伦酒店",
+            "city": "呼伦贝尔市",
+            "district": "海拉尔区"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 二、前端处理
+
+- `hotels[].district` 为新增字段(区/县),前端可在城市后展示完整地址层级。
+- 当住宿项无关联酒店资源(仅快照)时,`city`/`district` 均为 `null`(与原 `city` 行为一致),前端做空值兜底即可。
+
+## 三、测试服实测
+
+产品 2043696… 豪华档住宿项返回 `city=呼伦贝尔市, district=海拉尔区/额尔古纳市/阿尔山市`,城市+区县均正确。