From 7beff1b6156632ab5a794d43ade6ea1699d71c67 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 18 Mar 2026 17:28:25 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=B0=8F=E8=92=99=E9=A9=AC=E5=9B=A2?= =?UTF-8?q?=E6=9C=9F=E6=88=BF=E9=97=B4=E5=BA=93=E5=AD=98=E7=AE=A1=E7=90=86?= =?UTF-8?q?=20-=20=E8=AF=A6=E7=BB=86=E5=89=8D=E7=AB=AF=E5=AF=B9=E6=8E=A5?= =?UTF-8?q?=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 替换自动生成的简略变更记录，提供完整的接口定义、请求/响应示例、 校验规则、前端实现建议和数据库变更说明。 Co-Authored-By: Claude Opus 4.6 --- .../2026-03/2026-03-18_1716_6aff568_feat.md | 74 ----- .../2026-03-18_group_room_inventory.md | 255 ++++++++++++++++++ 2 files changed, 255 insertions(+), 74 deletions(-) delete mode 100644 changelogs/2026-03/2026-03-18_1716_6aff568_feat.md create mode 100644 changelogs/2026-03/2026-03-18_group_room_inventory.md diff --git a/changelogs/2026-03/2026-03-18_1716_6aff568_feat.md b/changelogs/2026-03/2026-03-18_1716_6aff568_feat.md deleted file mode 100644 index 25fb329..0000000 --- a/changelogs/2026-03/2026-03-18_1716_6aff568_feat.md +++ /dev/null @@ -1,74 +0,0 @@ -# 接口变更记录 — 2026-03-18 17:16 - -> **提交** `6aff568` · **作者** wx · **时间** 2026-03-18 17:16:16 +0800 -> -> feat: 小蒙马团期增加房间库存管理（下单扣减、取消恢复） - -## 变更总览 - -- **产品服务** - - InternalProduct (改2) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### ✏️ `POST` /internal/product/batch/{batchId}/enroll — 报名入团（内部） - -- 参数: batchId(Long) → batchId(Long), roomCount(int) - -### ✏️ `POST` /internal/product/batch/{batchId}/unenroll — 退出报名（内部） - -- 参数: batchId(Long) → batchId(Long), roomCount(int) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ GroupBatchCalendarVO - - - 🆕 `maxRooms` (`Integer`) — 总房间数 - - 🆕 `bookedRooms` (`Integer`) — 已预订房间数 - - 🆕 `remainingRooms` (`Integer`) — 剩余房间数 - -#### ✏️ GroupBatchCreateRequest - - - 🆕 `maxRooms` (`int`) — 总房间数（下单时扣减房间库存） - -#### ✏️ GroupBatchUpdateRequest - - - 🆕 `maxRooms` (`Integer`) — 总房间数（不能低于已预订房间数） - -#### ✏️ GroupTourBatchVO - - - 🆕 `maxRooms` (`Integer`) — 总房间数 - - 🆕 `bookedRooms` (`Integer`) — 已预订房间数 - - 🆕 `remainingRooms` (`Integer`) — 剩余房间数 - -
-📁 全部变更文件 (点击展开) - -``` -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/GroupBatchUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/GroupTourBatch.java -M hl-product-service/src/main/java/com/hulalv/product/mapper/GroupTourBatchMapper.java -M hl-product-service/src/main/java/com/hulalv/product/service/GroupTourBatchService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/GroupBatchCalendarVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/GroupTourBatchVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/GroupTourBatchServiceTest.java -``` -
\ No newline at end of file diff --git a/changelogs/2026-03/2026-03-18_group_room_inventory.md b/changelogs/2026-03/2026-03-18_group_room_inventory.md new file mode 100644 index 0000000..947f449 --- /dev/null +++ b/changelogs/2026-03/2026-03-18_group_room_inventory.md @@ -0,0 +1,255 @@ +# 小蒙马（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 | 已结束 | 行程结束 |