165 lines
4.9 KiB
Markdown
165 lines
4.9 KiB
Markdown
# 接口修改清单 - 时段预约整合
|
||
|
||
## 📋 修改概述
|
||
|
||
**目标**：将预约系统统一为只能通过时间段（4个固定时段）来预约，并将预约信息整合到时段信息中。
|
||
|
||
## ✅ 已完成
|
||
|
||
### 1. DTO 模型修改
|
||
- ✅ **`SQTimeSlotDto`** - 添加 `reservations` 字段（该时段内的预约列表）
|
||
- ✅ **`SQTimeSlotReservationDto`** - 新增时段预约信息DTO
|
||
- `reservation_id` - 预约ID
|
||
- `start_time` - 开始时间
|
||
- `end_time` - 结束时间
|
||
- `status` - 预约状态
|
||
- `title` - 组局名称
|
||
- `game_type` - 玩法类型
|
||
|
||
### 2. 房间详情接口修改
|
||
- ✅ **`GetRoomDetail`** - 已修改，将预约信息整合到 `time_slots` 中
|
||
- 每个时段包含该时段内的预约列表
|
||
- 保留 `today_reservations` 字段以保持兼容性（建议前端使用 `time_slots[].reservations`）
|
||
|
||
## 🔧 需要修改的接口
|
||
|
||
### 1. 旧预约接口（需要限制为只能按时段预约）
|
||
|
||
#### 1.1 `AddSQReservation` - 用户预约接口
|
||
**位置**：`SQController.cs` 第 514 行
|
||
|
||
**当前问题**：
|
||
- 允许任意时间段预约（通过 `start_time` 和 `end_time`）
|
||
- 需要改为只能按时段预约
|
||
|
||
**修改方案**：
|
||
- 方案A：废弃此接口，强制使用新的按时段预约接口
|
||
- 方案B：添加时段验证，确保预约时间必须完全匹配某个时段范围
|
||
|
||
**推荐**：方案A（废弃旧接口），因为已有新的按时段预约接口
|
||
|
||
---
|
||
|
||
#### 1.2 `CanCreateSQReservation` - 预约校验接口
|
||
**位置**：`SQController.cs` 第 688 行
|
||
|
||
**当前问题**：
|
||
- 允许任意时间段校验
|
||
- 需要改为只能按时段校验
|
||
|
||
**修改方案**：
|
||
- 方案A：废弃此接口，使用 `ValidateReservationBySlot`
|
||
- 方案B：添加时段验证逻辑
|
||
|
||
**推荐**：方案A（废弃旧接口）
|
||
|
||
---
|
||
|
||
### 2. 按时段预约接口（需要实现）
|
||
|
||
#### 2.1 `CreateReservationBySlot` - 按时段创建预约
|
||
**位置**：`SQReservationsServices.cs` 第 193 行
|
||
|
||
**当前状态**：
|
||
- 接口已定义，但实现为 `NotImplementedException`
|
||
- Controller 层接口缺失
|
||
|
||
**需要完成**：
|
||
1. 实现 `CreateReservationBySlotAsync` 方法
|
||
2. 在 Controller 中添加对应的 HTTP 接口
|
||
3. 根据时段类型计算准确的开始和结束时间
|
||
4. 验证时段是否可预约
|
||
5. 创建预约记录
|
||
|
||
---
|
||
|
||
#### 2.2 `ValidateReservationBySlot` - 按时段校验预约
|
||
**位置**：`SQReservationsServices.cs` 第 198 行
|
||
|
||
**当前状态**：
|
||
- 接口已定义，但实现为 `NotImplementedException`
|
||
- Controller 层接口已存在（`ValidateReservationBySlot`）
|
||
|
||
**需要完成**：
|
||
1. 实现 `ValidateReservationBySlotAsync` 方法
|
||
2. 验证时段是否可预约
|
||
3. 验证用户是否有时间冲突
|
||
4. 验证房间是否已被预约
|
||
|
||
---
|
||
|
||
### 3. 其他相关接口（可能需要调整）
|
||
|
||
#### 3.1 `GetAvailableRooms` - 获取可预约房间列表
|
||
**位置**：`SQController.cs` 第 456 行
|
||
|
||
**当前问题**：
|
||
- 使用时间段查询（`start` 和 `end`）
|
||
- 可能需要改为按时段查询
|
||
|
||
**建议**：
|
||
- 如果前端仍在使用，需要评估是否改为按时段查询
|
||
- 或者废弃，使用 `GetRoomListWithSlotsNew` 接口
|
||
|
||
---
|
||
|
||
#### 3.2 `GetRoomListWithSlotsNew` - 获取房间列表及时段状态
|
||
**位置**：`SQController.cs` 第 1617 行
|
||
|
||
**状态**：
|
||
- ✅ 已实现按时段查询
|
||
- ✅ 返回时段状态和价格
|
||
- ⚠️ 建议：在时段信息中也添加预约列表（与详情接口保持一致）
|
||
|
||
---
|
||
|
||
## 📝 修改优先级
|
||
|
||
### 高优先级（必须完成）
|
||
1. ✅ 修改时段DTO，添加预约信息
|
||
2. ✅ 修改房间详情接口，整合预约信息
|
||
3. ⚠️ **实现 `CreateReservationBySlotAsync` 方法**
|
||
4. ⚠️ **实现 `ValidateReservationBySlotAsync` 方法**
|
||
5. ⚠️ **在 Controller 中添加按时段创建预约接口**
|
||
|
||
### 中优先级（建议完成）
|
||
6. ⚠️ 废弃或限制 `AddSQReservation` 接口（只允许按时段预约）
|
||
7. ⚠️ 废弃或限制 `CanCreateSQReservation` 接口
|
||
8. ⚠️ 在 `GetRoomListWithSlotsNew` 中也添加预约信息到时段中
|
||
|
||
### 低优先级（可选）
|
||
9. 评估 `GetAvailableRooms` 接口是否需要调整
|
||
10. 更新接口文档
|
||
|
||
---
|
||
|
||
## 🔍 时段定义
|
||
|
||
系统使用4个固定时段：
|
||
- **0 = 凌晨**：00:00 - 06:00
|
||
- **1 = 上午**：06:00 - 12:00
|
||
- **2 = 下午**：12:00 - 18:00
|
||
- **3 = 晚上**：18:00 - 24:00
|
||
|
||
预约必须完全匹配某个时段的时间范围，不能跨时段或自定义时间。
|
||
|
||
---
|
||
|
||
## 📌 注意事项
|
||
|
||
1. **向后兼容**：保留 `today_reservations` 字段，但建议前端使用 `time_slots[].reservations`
|
||
2. **数据一致性**：确保所有接口的时段判断逻辑一致
|
||
3. **错误处理**：如果用户尝试使用非时段时间预约，应返回明确的错误提示
|
||
4. **测试覆盖**：需要测试各种时段边界情况
|
||
|
||
---
|
||
|
||
## 🎯 下一步行动
|
||
|
||
1. 实现按时段创建预约的核心逻辑
|
||
2. 实现按时段校验预约的逻辑
|
||
3. 在 Controller 中添加按时段创建预约的接口
|
||
4. 更新旧接口，限制为只能按时段预约（或废弃）
|
||
5. 更新前端对接文档
|
||
|