# 接口修改清单 - 时段预约整合

## 📋 修改概述

**目标**：将预约系统统一为只能通过时间段（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. 更新前端对接文档