391 lines
9.8 KiB
Markdown
391 lines
9.8 KiB
Markdown
# API接口文档 - 预约房间页面 (book-room-page)
|
||
|
||
## 文档说明
|
||
|
||
本文档为 `uniapp/mahjong_group/pages/appointment/book-room-page.vue` 页面提供完整的API接口设计方案。
|
||
|
||
---
|
||
|
||
## 📊 数据库设计评估
|
||
|
||
### 现有字段（SQRooms表）
|
||
✅ **已有字段：**
|
||
- `id`: 房间ID
|
||
- `name`: 房间名称
|
||
- `price_per_hour`: 价格/小时
|
||
- `capacity`: 可容纳人数
|
||
- `status`: 可用状态 (bool)
|
||
|
||
⚠️ **缺失字段（需要扩展）：**
|
||
- `image_url`: 房间图片URL
|
||
- `room_type`: 房间类型（如：小包、中包、大包、豪华包）
|
||
- `description`: 房间描述
|
||
|
||
### 已新增字段
|
||
|
||
```sql
|
||
-- 扩展 SQRooms 表，添加以下字段：
|
||
ALTER TABLE SQRooms ADD image_url NVARCHAR(500) NULL;
|
||
ALTER TABLE SQRooms ADD room_type NVARCHAR(50) NULL;
|
||
ALTER TABLE SQRooms ADD description NVARCHAR(500) NULL;
|
||
```
|
||
|
||
---
|
||
|
||
## 📡 API接口设计
|
||
|
||
### 1️⃣ 获取房间列表（带时段占用信息）
|
||
|
||
**接口名称：** GetRoomListWithTimeSlots
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口路径：** `/api/SQ/GetRoomListWithTimeSlots`
|
||
|
||
**功能说明：** 获取指定日期的所有房间列表，包含房间详细信息、价格、当前状态以及时段占用情况
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| date | long | 是 | 查询日期（Unix时间戳-秒级），传入当天0点的时间戳 |
|
||
| showTimeSlots | bool | 否 | 是否返回时段占用信息（默认false） |
|
||
|
||
**示例：**
|
||
```
|
||
GET /api/SQ/GetRoomListWithTimeSlots?date=1733443200&showTimeSlots=true
|
||
```
|
||
|
||
#### 响应数据
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "ok",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "304号-大包",
|
||
"room_type": "大包",
|
||
"image_url": "https://example.com/rooms/304.jpg",
|
||
"price_per_hour": 30.00,
|
||
"vip_price_per_hour": 25.00,
|
||
"capacity": 6,
|
||
"description": "豪华大包厢，配有独立卫生间",
|
||
"status": "available", // available-可预约, using-使用中, unavailable-不可用
|
||
"is_available": true,
|
||
"time_slots": { // 仅当 showTimeSlots=true 时返回
|
||
"dawn": { // 凌晨 0:00-6:00
|
||
"is_occupied": true,
|
||
"reservations": [
|
||
{ "start_time": "2025-12-06 02:00:00", "end_time": "2025-12-06 06:00:00" }
|
||
]
|
||
},
|
||
"morning": { // 上午 6:00-12:00
|
||
"is_occupied": false,
|
||
"reservations": []
|
||
},
|
||
"afternoon": { // 下午 12:00-18:00
|
||
"is_occupied": true,
|
||
"reservations": [
|
||
{ "start_time": "2025-12-06 14:00:00", "end_time": "2025-12-06 18:00:00" }
|
||
]
|
||
},
|
||
"evening": { // 晚上 18:00-24:00
|
||
"is_occupied": false,
|
||
"reservations": []
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "305号-中包",
|
||
"room_type": "中包",
|
||
"image_url": "https://example.com/rooms/305.jpg",
|
||
"price_per_hour": 20.00,
|
||
"vip_price_per_hour": null,
|
||
"capacity": 4,
|
||
"description": "标准中包厢",
|
||
"status": "using",
|
||
"is_available": false,
|
||
"time_slots": null
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 房间ID |
|
||
| name | string | 房间名称 |
|
||
| room_type | string | 房间类型 |
|
||
| image_url | string | 房间图片URL（若为空，前端显示默认图） |
|
||
| price_per_hour | decimal | 标准价格/小时 |
|
||
| vip_price_per_hour | decimal | 会员价/小时（null表示无会员价） |
|
||
| capacity | int | 可容纳人数 |
|
||
| description | string | 房间描述 |
|
||
| status | string | 房间状态：<br/>- `available`: 可预约<br/>- `using`: 当前使用中<br/>- `unavailable`: 不可用（维护中等） |
|
||
| is_available | bool | 是否可预约 |
|
||
| time_slots | object | 时段占用信息（仅当请求参数 showTimeSlots=true 时返回） |
|
||
|
||
---
|
||
|
||
### 2️⃣ 新增获取可预约房间列表
|
||
|
||
**接口名称：** GetReservationRoomListNew
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口路径：** `/api/SQ/GetReservationRoomListNew`
|
||
|
||
**功能说明：** 获取指定时间段内可预约的房间列表（不包含已预约和不可用时段的房间）
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| startTime | long | 是 | 开始时间（Unix时间戳-秒级） |
|
||
| endTime | long | 是 | 结束时间（Unix时间戳-秒级） |
|
||
|
||
**示例：**
|
||
```
|
||
GET /api/SQ/GetReservationRoomListNew?startTime=1733457600&endTime=1733472000
|
||
```
|
||
|
||
#### 响应数据
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "ok",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "304号-大包",
|
||
"room_type": "大包",
|
||
"image_url": "https://example.com/rooms/304.jpg",
|
||
"price_per_hour": 30.00,
|
||
"vip_price_per_hour": 25.00,
|
||
"capacity": 6,
|
||
"description": "豪华大包厢",
|
||
"display_name": "304号-大包 30.00/小时" // 用于前端直接显示
|
||
},
|
||
{
|
||
"id": 3,
|
||
"name": "306号-小包",
|
||
"room_type": "小包",
|
||
"image_url": null,
|
||
"price_per_hour": 15.00,
|
||
"vip_price_per_hour": null,
|
||
"capacity": 4,
|
||
"description": "标准小包厢",
|
||
"display_name": "306号-小包 15.00/小时"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3️⃣ 获取营业时间配置
|
||
|
||
**接口名称：** GetBusinessHours
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口路径：** `/api/Common/GetBusinessHours`
|
||
|
||
**功能说明：** 获取店铺营业时间配置
|
||
|
||
#### 请求参数
|
||
|
||
无
|
||
|
||
#### 响应数据
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "ok",
|
||
"data": {
|
||
"open_time": "09:00",
|
||
"close_time": "23:00",
|
||
"is_24_hours": false,
|
||
"description": "早9点 至 晚23点"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| open_time | string | 开始营业时间（HH:mm格式） |
|
||
| close_time | string | 结束营业时间（HH:mm格式） |
|
||
| is_24_hours | bool | 是否24小时营业 |
|
||
| description | string | 营业时间描述文本 |
|
||
|
||
---
|
||
|
||
### 4️⃣ 获取房间详情
|
||
|
||
**接口名称：** GetRoomDetail
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口路径：** `/api/SQ/GetRoomDetail`
|
||
|
||
**功能说明：** 获取指定房间的详细信息
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| roomId | int | 是 | 房间ID |
|
||
| date | long | 否 | 查询日期（默认今天） |
|
||
|
||
#### 响应数据
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "ok",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "304号-大包",
|
||
"room_type": "大包",
|
||
"image_url": "https://example.com/rooms/304.jpg",
|
||
"images": [ // 多图展示
|
||
"https://example.com/rooms/304_1.jpg",
|
||
"https://example.com/rooms/304_2.jpg"
|
||
],
|
||
"price_per_hour": 30.00,
|
||
"vip_price_per_hour": 25.00,
|
||
"capacity": 6,
|
||
"description": "豪华大包厢，配有独立卫生间、智能麻将桌、空调、Wi-Fi等设施",
|
||
"amenities": ["独立卫生间", "智能麻将桌", "空调", "Wi-Fi"],
|
||
"status": "available",
|
||
"today_reservations": [ // 今日预约情况
|
||
{
|
||
"start_time": "2025-12-06 14:00:00",
|
||
"end_time": "2025-12-06 18:00:00",
|
||
"status": 0
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 前端调用流程
|
||
|
||
### 页面加载流程
|
||
|
||
```javascript
|
||
// 1. 页面初始化
|
||
onLoad() {
|
||
this.getDateList(); // 生成7天日期列表（前端）
|
||
this.loadRoomList(); // 加载房间列表
|
||
this.getBusinessHours(); // 获取营业时间
|
||
}
|
||
|
||
// 2. 加载房间列表（基础模式）
|
||
async loadRoomList() {
|
||
const selectedDate = this.dateList[this.currentTimeIndex];
|
||
const timestamp = this.dateToTimestamp(selectedDate.time);
|
||
|
||
const res = await uni.request({
|
||
url: '/api/SQ/GetRoomListWithTimeSlots',
|
||
data: {
|
||
date: timestamp,
|
||
showTimeSlots: this.showFreeTime // 根据开关决定是否获取时段
|
||
}
|
||
});
|
||
|
||
this.roomList = res.data.data;
|
||
}
|
||
|
||
// 3. 切换日期时重新加载
|
||
clickTime(index) {
|
||
this.currentTimeIndex = index;
|
||
this.loadRoomList();
|
||
}
|
||
|
||
// 4. 切换时段显示开关
|
||
change(value) {
|
||
this.showFreeTime = value;
|
||
this.loadRoomList(); // 重新加载，包含时段信息
|
||
}
|
||
|
||
// 5. 点击预约按钮
|
||
handleBookRoom(room) {
|
||
if (room.status !== 'available') {
|
||
uni.showToast({ title: '该房间不可预约', icon: 'none' });
|
||
return;
|
||
}
|
||
|
||
// 跳转到预约详情页，传递房间信息
|
||
uni.navigateTo({
|
||
url: '/pages/appointment/appointment-page?' +
|
||
'roomId=' + room.id +
|
||
'&roomName=' + encodeURIComponent(room.name) +
|
||
'&date=' + this.dateList[this.currentTimeIndex].time
|
||
});
|
||
}
|
||
```
|
||
|
||
|
||
## ✅ 总结
|
||
|
||
### 数据库设计评估结果
|
||
|
||
**现有设计基本满足需求**，但建议扩展以下字段以提升用户体验：
|
||
|
||
1. ⚠️ **必要扩展**（影响核心功能）：
|
||
- 无，现有字段可满足基本功能
|
||
|
||
2. ✨ **建议扩展**（提升用户体验）：
|
||
- `image_url`: 房间图片
|
||
- `room_type`: 房间类型
|
||
- `vip_price_per_hour`: 会员价
|
||
- `description`: 房间描述
|
||
|
||
### API实现优先级
|
||
|
||
| 优先级 | 接口 | 说明 |
|
||
|--------|------|------|
|
||
| 🔴 **P0** | GetRoomListWithTimeSlots | 核心接口，提供房间列表和时段信息 |
|
||
| 🟡 **P1** | 优化 GetReservationRoomList | 返回更丰富的房间信息 |
|
||
| 🟢 **P2** | GetBusinessHours | 营业时间配置 |
|
||
| 🔵 **P3** | GetRoomDetail | 房间详情 |
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **时区处理**:
|
||
- 前端传递时间戳时需统一使用UTC+8时区
|
||
- 后端 `DateTimeOffset.FromUnixTimeSeconds()` 自动处理时区转换
|
||
|
||
2. **默认图片**:
|
||
- 前端需准备默认房间图片：`/static/default-room.png`
|
||
- 当 `image_url` 为空时使用默认图
|
||
|
||
3. **缓存策略**:
|
||
- 房间列表建议缓存5分钟
|
||
- 时段信息实时查询，不缓存
|
||
|
||
4. **性能优化**:
|
||
- 首次加载不查询时段信息（showTimeSlots=false）
|
||
- 仅当用户打开开关时再查询时段详情
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**创建日期**: 2025-12-06
|
||
**最后更新**: 2025-12-06
|
||
|