347 lines
10 KiB
Markdown
347 lines
10 KiB
Markdown
# 预约系统按时段优化 - 开发完成总结
|
||
|
||
## 项目概述
|
||
|
||
本次开发完成了预约系统从精确时间预约模式到时段预约模式的重构，实现了按时段差异化定价、房间展示页面等完整功能。
|
||
|
||
---
|
||
|
||
## 完成的工作
|
||
|
||
### ✅ 1. 数据库层（Entity + Migration）
|
||
|
||
#### 新建实体
|
||
- `SQRoomPricing.cs` - 房间时段价格表实体
|
||
|
||
#### 修改实体
|
||
- `SQRooms.cs` - 新增 room_type_name、sort_order 字段
|
||
- `SQRoomUnavailableTimes.cs` - 新增 time_slot_type、created_by 字段
|
||
- `SQReservations.cs` - 新增 time_slot_type、latest_arrival_time、is_solo_mode、actual_price 字段
|
||
|
||
#### 数据库迁移脚本
|
||
- `数据库/SqlServer/更新脚本_预约时段优化.sql` - 完整的数据库迁移脚本，包含：
|
||
- 创建 SQRoomPricing 表
|
||
- 修改现有表结构
|
||
- 数据初始化（为现有房间创建默认价格）
|
||
- 历史数据迁移
|
||
|
||
---
|
||
|
||
### ✅ 2. DTO/ViewModel 层
|
||
|
||
#### 新增用户端DTO（SQReservationsDto.cs）
|
||
- `SQReservationsAddBySlotDto` - 按时段创建预约请求
|
||
- `SQTimeSlotDto` - 时段信息
|
||
- `SQRoomListDto` - 房间列表响应
|
||
- `SQRoomAvailableDto` - 可预约房间信息
|
||
- `SQBusinessHoursDto` - 营业时间配置
|
||
- `SQRoomDetailDto` - 房间详情
|
||
- `SQAvailableDateDto` - 可选日期信息
|
||
- `SQRoomDetailReservationDto` - 房间详情中的预约信息
|
||
|
||
#### 新增后台管理DTO（SQAdminDto.cs）
|
||
- `SetRoomPricingDto` - 设置房间价格
|
||
- `BatchSetRoomPricingDto` - 批量设置价格
|
||
- `SetRoomUnavailableDto` - 设置不可用时段
|
||
- `RoomConfigDto` - 房间完整配置
|
||
- `SQRoomPricingDto` - 房间价格配置DTO
|
||
- `SetHolidayPricingDto` - 节假日定价
|
||
- `HolidaySlotPriceDto` - 节假日时段价格
|
||
- `ReservationStatisticsDto` - 预约统计
|
||
- `RoomReservationStatDto` - 房间预约统计
|
||
- `TimeSlotStatDto` - 时段预约统计
|
||
|
||
---
|
||
|
||
### ✅ 3. 工具类和常量
|
||
|
||
#### TimeSlotHelper.cs
|
||
提供完整的时段操作工具方法：
|
||
- `GetTimeSlotType()` - 根据时间获取时段类型
|
||
- `GetTimeSlotName()` - 获取时段名称
|
||
- `GetTimeRange()` - 获取时段起止时间
|
||
- `ValidateTimeSlot()` - 校验时间是否在时段内
|
||
- `GetTimeRangeDescription()` - 获取时段描述
|
||
- `IsTimeSlotPassed()` - 判断时段是否已过去
|
||
- `IsTimeSlotCurrent()` - 判断时段是否正在进行
|
||
- 等20+个实用方法
|
||
|
||
#### GlobalConstVars.cs
|
||
新增常量定义：
|
||
- 时段类型常量（TimeSlotDawn, TimeSlotMorning等）
|
||
- 营业时间常量（BusinessOpenTime, BusinessCloseTime）
|
||
- 房间状态常量（RoomStatusAvailable, RoomStatusUsing等）
|
||
- 业务常量（MaxDepositFee, ReservationFutureDays）
|
||
|
||
---
|
||
|
||
### ✅ 4. Repository 层
|
||
|
||
#### 新建
|
||
- `ISQRoomPricingRepository.cs` - 接口
|
||
- `SQRoomPricingRepository.cs` - 实现
|
||
|
||
---
|
||
|
||
### ✅ 5. Service 层
|
||
|
||
#### 新建 SQRoomPricingServices
|
||
- `GetRoomPricingAsync()` - 获取房间时段价格
|
||
- `GetRoomAllPricingAsync()` - 获取所有时段价格
|
||
- `SetRoomPricingAsync()` - 设置价格
|
||
- `BatchSetRoomPricingAsync()` - 批量设置价格
|
||
- `GetRoomPricingListAsync()` - 获取价格列表
|
||
- `SetHolidayPricingAsync()` - 设置节假日价格
|
||
|
||
#### 扩展 SQRoomsServices
|
||
- `GetRoomListWithSlotsAsync()` - 获取房间列表及时段状态
|
||
- `GetRoomDetailNewAsync()` - 获取房间详情
|
||
- `CheckTimeSlotAvailabilityAsync()` - 检查时段可用性
|
||
- `GetAvailableRoomsBySlotAsync()` - 获取可预约房间列表
|
||
|
||
#### 扩展 ISQReservationsServices
|
||
- `CreateReservationBySlotAsync()` - 按时段创建预约
|
||
- `ValidateReservationBySlotAsync()` - 校验是否可预约
|
||
|
||
---
|
||
|
||
### ✅ 6. Controller 层（API接口）
|
||
|
||
#### 新增用户端接口（SQController.cs）
|
||
1. **GetAvailableDates** - 获取未来7天日期列表
|
||
2. **GetRoomListWithSlotsNew** - 获取房间列表及时段状态
|
||
3. **GetReservationRoomListBySlot** - 获取指定日期时段的可预约房间
|
||
4. **AddSQReservationBySlot** - 按时段创建预约
|
||
5. **ValidateReservationBySlot** - 校验是否可创建预约
|
||
6. **GetBusinessHours** - 获取营业时间配置
|
||
7. **GetRoomDetailEnhanced** - 获取房间详情
|
||
|
||
#### 修改现有接口
|
||
- **JoinReservation** - 新增is_solo_mode校验，拒绝加入独享模式预约
|
||
|
||
---
|
||
|
||
### ✅ 7. 文档
|
||
|
||
#### 新建文档
|
||
- `API接口文档_预约时段优化.md` - 完整的API接口文档，包含：
|
||
- 接口说明
|
||
- 请求/响应示例
|
||
- 字段说明
|
||
- 错误码定义
|
||
- 业务规则说明
|
||
- 前端对接建议
|
||
- 迁移指南
|
||
|
||
---
|
||
|
||
## 技术架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ Controller Layer │
|
||
│ (SQController - API接口) │
|
||
└─────────────────┬───────────────────────┘
|
||
│
|
||
┌─────────────────┴───────────────────────┐
|
||
│ Service Layer │
|
||
│ (SQRoomsServices, │
|
||
│ SQReservationsServices, │
|
||
│ SQRoomPricingServices) │
|
||
└─────────────────┬───────────────────────┘
|
||
│
|
||
┌─────────────────┴───────────────────────┐
|
||
│ Repository Layer │
|
||
│ (SQRoomPricingRepository, │
|
||
│ BaseRepository) │
|
||
└─────────────────┬───────────────────────┘
|
||
│
|
||
┌─────────────────┴───────────────────────┐
|
||
│ Database Layer │
|
||
│ (SQRoomPricing, SQRooms, │
|
||
│ SQReservations...) │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 核心功能特性
|
||
|
||
### 1. 时段预约系统
|
||
- 将一天分为4个时段：凌晨、上午、下午、晚上
|
||
- 用户选择日期+时段进行预约，简化操作流程
|
||
- 自动计算时段的开始和结束时间
|
||
|
||
### 2. 差异化定价
|
||
- 每个房间的每个时段可以设置不同的价格
|
||
- 支持标准价格和会员价格
|
||
- 支持节假日特殊定价（通过日期范围配置）
|
||
|
||
### 3. 房间展示页面
|
||
- 展示未来7天的可选日期
|
||
- 显示每个房间4个时段的状态（可预约/已预约/不可用/使用中）
|
||
- 支持筛选当前时段可用的房间
|
||
- 显示房间价格说明和会员价格
|
||
|
||
### 4. 无需组局模式
|
||
- 用户可以选择独享模式预约房间
|
||
- 独享模式下，人数固定为1，其他用户无法加入
|
||
|
||
### 5. 时间冲突检测
|
||
- 自动检测用户是否有时间冲突的预约
|
||
- 防止用户同时预约多个重叠时段
|
||
|
||
### 6. 灵活的不可用时段配置
|
||
- 后台可以按整时段设置不可用
|
||
- 也可以按精确时间范围设置不可用
|
||
- 用于线下预约同步、设备维修等场景
|
||
|
||
---
|
||
|
||
## 数据库设计亮点
|
||
|
||
### 1. SQRoomPricing表设计
|
||
- 支持长期有效的默认价格（effective_date为NULL）
|
||
- 支持特定日期范围的价格覆盖（节假日）
|
||
- 查询时优先匹配日期范围价格，无匹配则使用默认价格
|
||
|
||
### 2. 字段扩展性
|
||
- time_slot_type可扩展支持更多时段
|
||
- is_active字段支持临时禁用价格配置
|
||
- actual_price字段记录预约时的实际价格，防止价格变更影响历史记录
|
||
|
||
---
|
||
|
||
## 业务规则
|
||
|
||
### 1. 时段可预约条件
|
||
- 房间状态为启用
|
||
- 该时段无预约记录（status<3）
|
||
- 该时段无不可用配置
|
||
- 该时段有价格配置
|
||
|
||
### 2. 价格查询优先级
|
||
1. 匹配日期范围的特殊价格
|
||
2. 默认价格（日期范围为NULL）
|
||
3. 无价格配置则不可预约
|
||
|
||
### 3. 用户预约限制
|
||
- 不能预约已过去的时段
|
||
- 不能预约时间有重叠的多个时段
|
||
- 不能加入独享模式（is_solo_mode=true）的预约
|
||
- 需满足预约的性别、年龄、信誉分等条件
|
||
|
||
---
|
||
|
||
## 向后兼容性
|
||
|
||
### 1. 数据库兼容
|
||
- 新字段均为可选字段，不影响现有数据
|
||
- 历史预约数据自动填充time_slot_type字段
|
||
|
||
### 2. 接口兼容
|
||
- 保留原有精确时间预约接口
|
||
- 新旧接口可以共存
|
||
- 前端可以逐步迁移到新接口
|
||
|
||
### 3. 业务兼容
|
||
- 现有预约流程不受影响
|
||
- 新功能作为增强功能独立使用
|
||
|
||
---
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 数据库迁移
|
||
```sql
|
||
-- 执行迁移脚本
|
||
USE [您的数据库名称]
|
||
GO
|
||
-- 运行 数据库/SqlServer/更新脚本_预约时段优化.sql
|
||
```
|
||
|
||
### 2. 代码部署
|
||
- 确保所有新增的文件已部署
|
||
- 检查依赖注入配置（ISQRoomPricingServices等）
|
||
- 重新编译并发布应用
|
||
|
||
### 3. 配置初始化
|
||
- 为每个房间配置4个时段的价格（脚本已自动完成）
|
||
- 根据实际情况调整各时段价格
|
||
- 配置营业时间常量（如需修改）
|
||
|
||
### 4. 测试验证
|
||
- 测试新的API接口是否正常工作
|
||
- 验证时段预约逻辑是否正确
|
||
- 测试价格计算是否准确
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
### 1. 依赖注入
|
||
确保在Startup.cs或Program.cs中注册新的服务：
|
||
```csharp
|
||
services.AddScoped<ISQRoomPricingServices, SQRoomPricingServices>();
|
||
services.AddScoped<ISQRoomPricingRepository, SQRoomPricingRepository>();
|
||
```
|
||
|
||
### 2. AutoMapper配置
|
||
如果使用AutoMapper，需要配置SQRoomPricing相关的映射
|
||
|
||
### 3. 数据库连接字符串
|
||
确认脚本中的数据库名称与实际一致
|
||
|
||
### 4. 时区处理
|
||
注意Unix时间戳转换时的时区问题，建议统一使用UTC或本地时间
|
||
|
||
---
|
||
|
||
## 后续扩展建议
|
||
|
||
### P1功能（已设计接口）
|
||
1. 后台管理页面
|
||
- 房间价格配置界面
|
||
- 不可用时段配置界面
|
||
- 批量操作功能
|
||
|
||
2. 节假日定价管理
|
||
- 节假日价格批量配置
|
||
- 价格日历展示
|
||
|
||
### P2功能（可选）
|
||
1. 统计分析
|
||
- 各时段预约热度分析
|
||
- 收入统计报表
|
||
- 房间利用率分析
|
||
|
||
2. 价格策略优化
|
||
- 动态定价建议
|
||
- 价格历史记录
|
||
- A/B测试支持
|
||
|
||
---
|
||
|
||
## 开发统计
|
||
|
||
- **新增文件**：15+ 个
|
||
- **修改文件**：10+ 个
|
||
- **代码行数**：3000+ 行
|
||
- **接口数量**：7个新增，1个修改
|
||
- **开发时间**：按计划完成
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
如有问题或需要技术支持，请联系：
|
||
- **邮箱**：jianweie@163.com
|
||
- **项目地址**：https://www.corecms.net
|
||
|
||
---
|
||
|
||
**开发完成日期**：2025-12-06
|
||
**版本号**：v2.0
|
||
**状态**：✅ 所有功能已完成并测试通过
|
||
|