mahjong_group/docs/1.0.0/历史需求/快速开始指南.md

# 预约系统按时段优化 - 快速开始指南

## 部署前检查清单

### ✅ 1. 数据库准备
- [ ] 备份现有数据库
- [ ] 检查数据库连接字符串配置
- [ ] 确认SQL Server版本兼容性

### ✅ 2. 代码检查
- [ ] 确认所有新文件都已添加到项目中
- [ ] 检查项目引用是否正确
- [ ] 确保代码可以编译通过

### ✅ 3. 依赖注入配置
- [ ] 检查Startup.cs或Program.cs中的服务注册

---

## 快速部署步骤

### 步骤1：执行数据库迁移

```bash
# 1. 打开 SQL Server Management Studio
# 2. 连接到您的数据库
# 3. 打开脚本文件：数据库/SqlServer/更新脚本_预约时段优化.sql
# 4. 修改第15行的数据库名称为实际数据库名
# 5. 执行整个脚本
```

**重要提示**：
- 脚本执行前会检查表和字段是否已存在
- 首次执行会自动为现有房间创建默认价格配置
- 标准价 = 原price_per_hour × 6，会员价 = 标准价 × 0.8

### 步骤2：添加服务注册

在 `Startup.cs` 或 `Program.cs` 的服务配置部分添加：

```csharp
// 注册新的服务
services.AddScoped<ISQRoomPricingRepository, SQRoomPricingRepository>();
services.AddScoped<ISQRoomPricingServices, SQRoomPricingServices>();
```

### 步骤3：编译并发布

```bash
# 编译项目
dotnet build

# 发布项目
dotnet publish -c Release
```

### 步骤4：测试验证

使用Postman或Swagger测试以下接口：

#### 4.1 测试获取日期列表
```http
GET http://your-domain/api/SQ/GetAvailableDates
```

预期响应：返回未来8天的日期列表

#### 4.2 测试获取房间列表
```http
GET http://your-domain/api/SQ/GetRoomListWithSlotsNew?date=1733443200
```

预期响应：返回房间列表，每个房间包含4个时段的状态和价格

#### 4.3 测试创建预约（需要登录）
```http
POST http://your-domain/api/SQ/AddSQReservationBySlot
Content-Type: application/json
Authorization: Bearer {your_token}

{
  "room_id": 1,
  "date": 1733443200,
  "time_slot_type": 1,
  "player_count": 4,
  "deposit_fee": 20,
  "title": "测试预约",
  "game_type": "德州扑克",
  "is_solo_mode": false
}
```

预期响应：返回预约ID和时间信息

---

## 常见问题排查

### Q1: 编译错误 "找不到类型或命名空间"

**原因**：缺少项目引用或using语句

**解决**：
1. 检查项目引用关系
2. 确保所有新建的文件都已包含在项目中
3. 添加必要的using语句

### Q2: 运行时错误 "未注册服务"

**原因**：依赖注入配置缺失

**解决**：
在Startup.cs中添加服务注册：
```csharp
services.AddScoped<ISQRoomPricingServices, SQRoomPricingServices>();
services.AddScoped<ISQRoomPricingRepository, SQRoomPricingRepository>();
```

### Q3: 数据库脚本执行失败

**原因**：数据库版本不兼容或权限不足

**解决**：
1. 确认SQL Server版本（建议2016+）
2. 确认数据库用户有CREATE TABLE权限
3. 检查数据库名称是否正确

### Q4: 接口返回500错误

**可能原因**：
1. 数据库迁移未完成
2. 房间价格未配置
3. 服务未正确注入

**排查步骤**：
1. 检查数据库是否有SQRoomPricing表
2. 查询该表是否有数据
3. 查看应用日志获取详细错误信息

### Q5: 时段价格显示为0

**原因**：房间价格未配置或查询失败

**解决**：
1. 检查SQRoomPricing表是否有对应房间的价格配置
2. 运行以下SQL查询：
```sql
SELECT * FROM SQRoomPricing WHERE room_id = 1 AND is_active = 1
```
3. 如果没有数据，手动插入或重新运行迁移脚本的初始化部分

---

## 功能验证清单

### 基础功能
- [ ] 可以获取未来7天日期列表
- [ ] 可以查看房间列表及4个时段状态
- [ ] 可以查看房间详情
- [ ] 可以获取营业时间配置

### 预约功能
- [ ] 可以按时段创建预约
- [ ] 创建预约时正确计算价格
- [ ] 无需组局模式正常工作
- [ ] 时间冲突检测正常工作
- [ ] 不能加入独享模式预约

### 房间状态
- [ ] 可预约时段显示为绿色/available
- [ ] 已预约时段显示为红色/reserved
- [ ] 不可用时段显示为灰色/unavailable
- [ ] 使用中时段显示正确

### 价格功能
- [ ] 各时段价格正确显示
- [ ] 标准价格和会员价格都有显示
- [ ] 创建预约时记录actual_price

---

## 性能优化建议

### 1. 数据库索引
已自动创建的索引：
- SQRoomPricing表：room_id + time_slot_type
- SQRoomPricing表：effective_date_start + effective_date_end

如需进一步优化，可添加：
```sql
-- SQReservations表时段类型索引
CREATE INDEX IX_SQReservations_TimeSlot 
ON SQReservations(time_slot_type, status, start_time);

-- SQRoomUnavailableTimes表时段类型索引
CREATE INDEX IX_SQRoomUnavailableTimes_TimeSlot 
ON SQRoomUnavailableTimes(room_id, time_slot_type);
```

### 2. 缓存策略
考虑对以下数据使用缓存：
- 房间列表（已实现Redis缓存）
- 房间价格配置（可缓存1小时）
- 营业时间配置（可缓存到应用重启）

### 3. 查询优化
- 批量查询房间价格而不是逐个查询
- 使用分页查询历史预约记录
- 定期清理已结束的旧预约数据

---

## 监控建议

### 1. 关键指标
- API响应时间（建议<500ms）
- 预约创建成功率
- 时段预约分布
- 价格查询命中率

### 2. 日志记录
建议记录以下事件：
- 预约创建/取消
- 价格配置变更
- 不可用时段设置
- 时间冲突检测触发

### 3. 异常监控
关注以下异常：
- 价格查询失败
- 时段计算错误
- 数据库连接超时
- 并发预约冲突

---

## 后续维护

### 日常维护
1. **价格调整**：根据业务需求定期调整各时段价格
2. **数据清理**：定期清理过期的不可用时段配置
3. **性能监控**：监控接口响应时间和数据库查询性能
4. **备份策略**：定期备份SQRoomPricing表数据

### 数据分析
定期分析以下数据：
- 各时段预约热度
- 房间利用率
- 价格与预约量关系
- 用户预约行为模式

### 功能扩展
根据需求可以添加：
- 后台管理界面
- 价格批量导入导出
- 预约统计报表
- 移动端适配

---

## 技术支持

### 文档资源
- **API接口文档**：`API接口文档_预约时段优化.md`
- **需求文档**：`需求文档.md`
- **开发总结**：`开发完成总结.md`

### 联系方式
- **邮箱**：jianweie@163.com
- **项目主页**：https://www.corecms.net

### 问题反馈
遇到问题时，请提供：
1. 错误信息或异常堆栈
2. 复现步骤
3. 环境信息（数据库版本、.NET版本等）
4. 相关日志

---

## 版本信息

- **当前版本**：v2.0
- **发布日期**：2025-12-06
- **兼容性**：.NET 6.0+, SQL Server 2016+
- **状态**：✅ 生产就绪

---

**祝部署顺利！** 🎉