mahjong_group/docs/1.0.0/历史需求/接口修改清单_时段预约整合.md

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

📋 修改概述

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