wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs/2026-03/2026-03-18_group_room_inventory.md
API Changelog Bot 7beff1b615 feat: 小蒙马团期房间库存管理 - 详细前端对接指南 
替换自动生成的简略变更记录，提供完整的接口定义、请求/响应示例、
校验规则、前端实现建议和数据库变更说明。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-18 17:28:25 +08:00

256 行
8.1 KiB
Markdown
原始文件 Blame 文件历史

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# 小蒙马（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） |
### 请求示例
```json
{
"batchName": "7月20日第1批",
"departureDate": "2026-07-20",
"enrollmentDeadline": "2026-07-15",
"maxParticipants": 30,
"maxRooms": 15,
"adultsPerRoom": 2,
"minParticipants": 10,
"remark": "暑期特别批次",
"sortOrder": 0
}
```
### 响应示例
```json
{
"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 | 剩余房间数 |
### 响应示例（批次列表中的一条）
```json
{
"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间"。
---
## 数据库变更
```sql
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 | 已结束 | 行程结束 |
在新工单中引用 查看 Git Blame 复制永久链接