hl-api-changelog/changelogs/2026-03/2026-03-18_group_room_inventory.md

小蒙马（GROUP）团期房间库存管理 - 前端对接指南

日期: 2026-03-18 后端状态: ✅ 已完成，测试环境已部署 涉及模块: 拼团批次管理、小蒙马下单

---

功能说明

小蒙马（GROUP）团期新增房间库存管理功能：

核心变更：

1. 创建团期时必须设置总房间数（maxRooms）
2. 用户/管理员下单时，系统自动扣减房间库存
3. 房间不足时，下单直接报错"房间不足，剩余X间，需要Y间"
4. 订单取消/退款/超时/散团，系统自动恢复房间库存
5. 团期列表、日历、详情均返回房间相关信息

并发安全：使用MySQL乐观锁（WHERE booked_rooms + count <= max_rooms），防止超卖。

---

变更接口清单

#	接口	方法	路径	变更类型	说明
1	创建主批次	POST	/admin/product/item/{productId}/group-batch	请求新增字段	新增必填参数 maxRooms
2	创建子批次(溢出)	POST	/admin/product/item/group-batch/{parentBatchId}/sub	请求新增字段	同上
3	更新批次	PUT	/admin/product/item/group-batch/{batchId}	请求新增字段	新增可选参数 maxRooms
4	批次列表(树形)	GET	/admin/product/item/{productId}/group-batches	响应新增字段	VO新增3个房间字段
5	批次详情	GET	/admin/product/item/group-batch/{batchId}	响应新增字段	同上
6	团期日历(C端)	GET	/internal/product/{productId}/batches/calendar	响应新增字段	日历VO新增3个房间字段
7	GROUP报价	GET	/admin/product/item/{productId}/group-quote	无变更	-

---

接口 1：创建主批次（请求新增字段）

使用场景：管理员在拼团批次管理页面创建新团期时，需要额外填写"总房间数"。

POST /admin/product/item/{productId}/group-batch

请求参数

参数	类型	必填	说明
batchName	String	✅	批次名称，如"7月20日第1批"
departureDate	String(date)	✅	出发日期，如"2026-07-20"
enrollmentDeadline	String(date)	✅	报名截止日期，必须早于出发日期
maxParticipants	Integer	✅	最大参团人数（≥1）
maxRooms	Integer	✅ 新增必填	总房间数（≥1），下单时扣减，取消时恢复
adultsPerRoom	Integer	否	每间房入住成人数（默认2，用于计算单房差）
minParticipants	Integer	否	最低成团人数（默认0=不限制）
remark	String	否	备注说明
sortOrder	Integer	否	排序序号（默认0）

请求示例

{
  "batchName": "7月20日第1批",
  "departureDate": "2026-07-20",
  "enrollmentDeadline": "2026-07-15",
  "maxParticipants": 30,
  "maxRooms": 15,
  "adultsPerRoom": 2,
  "minParticipants": 10,
  "remark": "暑期特别批次",
  "sortOrder": 0
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "batchId": "2030139162007318530",
    "productId": "2030106351179280385",
    "parentBatchId": null,
    "batchNo": "B2026072033",
    "batchLabel": "1",
    "batchName": "7月20日第1批",
    "departureDate": "2026-07-20",
    "endDate": "2026-07-26",
    "enrollmentDeadline": "2026-07-15",
    "minParticipants": 10,
    "maxParticipants": 30,
    "enrolledCount": 0,
    "adultsPerRoom": 2,
    "maxRooms": 15,
    "bookedRooms": 0,
    "remainingRooms": 15,
    "batchStatus": "PENDING",
    "sortOrder": 0,
    "remark": "暑期特别批次",
    "createBy": "2025607151170445314",
    "createTime": "2026-03-18T17:16:00",
    "updateTime": "2026-03-18T17:16:00",
    "remainingSlots": 30,
    "subBatches": []
  }
}

---

接口 3：更新批次（请求新增字段）

使用场景：管理员修改团期信息时，可调整总房间数（不能低于已预订数）。

PUT /admin/product/item/group-batch/{batchId}

新增请求参数

参数	类型	必填	说明
maxRooms	Integer	否（新增）	总房间数（≥1），不能低于已预订房间数，否则报错

校验规则

• maxRooms 不能低于 bookedRooms，否则返回错误："总房间数不能低于已预订房间数（X）"

---

响应 VO 新增字段（影响接口 4、5、6）

以下3个字段在批次列表、批次详情、团期日历响应中均有返回：

团批次VO（GroupTourBatchVO）— 接口4、5

字段	类型	说明
maxRooms	Integer	总房间数
bookedRooms	Integer	已预订房间数
remainingRooms	Integer	剩余房间数（= maxRooms - bookedRooms）

团期日历VO（GroupBatchCalendarVO）— 接口6

字段	类型	说明
maxRooms	Integer	总房间数
bookedRooms	Integer	已预订房间数
remainingRooms	Integer	剩余房间数

响应示例（批次列表中的一条）

{
  "batchId": "2030139162007318530",
  "batchName": "7月20日第1批",
  "departureDate": "2026-07-20",
  "maxParticipants": 30,
  "enrolledCount": 5,
  "remainingSlots": 25,
  "maxRooms": 15,
  "bookedRooms": 3,
  "remainingRooms": 12,
  "adultsPerRoom": 2,
  "batchStatus": "ENROLLING"
}

---

下单相关变更

下单房间校验

用户/管理员创建GROUP订单时，系统会：

1. 前置检查：根据批次的 remainingRooms 判断房间是否充足
2. 乐观锁扣减：booked_rooms + roomCount <= max_rooms 时才扣减成功
3. 失败提示："房间不足，剩余X间，需要Y间"

取消/退款自动恢复

以下场景自动归还房间：

• 用户主动取消订单
• 管理员取消订单
• 支付超时自动取消
• 团期散团批量取消
• 退款完成

归还逻辑：booked_rooms = booked_rooms - 订单的roomCount

---

前端实现建议

创建/编辑团期表单

在现有表单中新增一行：

┌─────────────────────────────────────────────┐
│  批次名称:  [7月20日第1批        ]           │
│  出发日期:  [2026-07-20  📅]                │
│  报名截止:  [2026-07-15  📅]                │
│  最大人数:  [30          ]                  │
│  总房间数:  [15          ]    ← 新增必填     │
│  每房成人:  [2           ]                  │
│  最低成团:  [10          ]                  │
│  备    注:  [暑期特别批次 ]                  │
└─────────────────────────────────────────────┘

• maxRooms 使用 el-input-number，min=1
• 编辑时需校验：不能低于 bookedRooms（从详情接口获取）

批次列表展示

在现有的"已报名/最大人数"旁边，增加房间信息：

第1批 | 2026-07-20出发 | 报名中
人数: 5/30 (剩余25)  |  房间: 3/15 (剩余12)

小程序端日历

日历接口已返回 remainingRooms，可在日历格子中展示"剩余X间"。

---

数据库变更

ALTER TABLE group_tour_batch
  ADD COLUMN max_rooms INT NOT NULL DEFAULT 0 COMMENT '总房间数',
  ADD COLUMN booked_rooms INT NOT NULL DEFAULT 0 COMMENT '已预订房间数';

已在本地、测试环境执行完毕。历史团期的 max_rooms=0，需要管理员编辑补充。

---

关联字典

字典类型	字典值	中文标签	说明
batch_status	PENDING	待开放	初始状态，不接受报名
batch_status	ENROLLING	报名中	接受报名，可下单
batch_status	CONFIRMED	已成团	达到最低成团人数，仍可报名
batch_status	FULL	已满员	人数达到上限，自动关闭
batch_status	CLOSED	已关闭	管理员手动关闭报名
batch_status	DISBANDED	已解散	散团，触发退款
batch_status	IN_PROGRESS	进行中	出发日当天自动更新
batch_status	FINISHED	已结束	行程结束