outsource/mahjong_group

Fork 0

zpc 63aedaf041 调整文件结构

2026-01-01 14:39:23 +08:00

11 KiB

Raw Blame History

预约系统按时段优化 - API接口文档

更新日期：2025-12-06

一、概述

本次更新将预约系统从精确时间预约模式改为时段预约模式，新增了房间展示页面、按时段价格配置等功能。

时段定义

时段类型	时段名称	时间范围
0	凌晨	00:00 - 05:59
1	上午	06:00 - 11:59
2	下午	12:00 - 17:59
3	晚上	18:00 - 23:59

二、新增用户端接口

2.1 获取未来7天日期列表

接口地址：GET /api/SQ/GetAvailableDates

请求参数：无

响应示例：

{
  "code": 0,
  "data": [
    {
      "date": 1733443200,
      "dateText": "今天",
      "dateDisplay": "周五"
    },
    {
      "date": 1733529600,
      "dateText": "明天",
      "dateDisplay": "周五"
    }
  ],
  "msg": "ok"
}

2.2 获取房间列表及时段状态

接口地址：GET /api/SQ/GetRoomListWithSlotsNew

请求参数：

参数名	类型	必填	说明
date	long	是	查询日期（Unix时间戳-秒级）
showOnlyAvailable	bool	否	是否只显示当前时段可用的房间，默认false
currentTimeSlot	int	否	当前时段类型（0-3），配合showOnlyAvailable使用

响应示例：

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "101包间",
      "room_type_name": "豪华包间",
      "image_url": "https://...",
      "capacity": 8,
      "description": "宽敞舒适...",
      "standard_price_desc": "80元/时段",
      "member_price_desc": "60元/时段",
      "time_slots": [
        {
          "slot_type": 0,
          "slot_name": "凌晨",
          "status": "available",
          "standard_price": 60.00,
          "member_price": 50.00,
          "price_desc_standard": "60元/时段",
          "price_desc_member": "50元/时段"
        },
        {
          "slot_type": 1,
          "slot_name": "上午",
          "status": "reserved",
          "standard_price": 80.00,
          "member_price": 60.00,
          "price_desc_standard": "80元/时段",
          "price_desc_member": "60元/时段"
        }
      ],
      "status": "available",
      "is_available": true,
      "can_reserve": true
    }
  ],
  "msg": "ok"
}

时段状态说明：

available：可预约
reserved：已预约
unavailable：不可用（后台设置）
using：使用中（当前时间在该时段内且已预约）

2.4 按时段创建预约

接口地址：POST /api/SQ/AddSQReservationBySlot

请求头：需要Authorization

请求体：

{
  "room_id": 1,
  "date": 1733443200,
  "time_slot_type": 1,
  "latest_arrival_time": 1733468400,
  "is_solo_mode": false,
  "player_count": 4,
  "deposit_fee": 20,
  "title": "周末开黑",
  "game_type": "德州扑克",
  "game_rule": "经典玩法",
  "extra_info": "欢迎新手",
  "is_smoking": 0,
  "gender_limit": 0,
  "credit_limit": 3.5,
  "min_age": 18,
  "max_age": 0,
  "important_data": "{\"paymentId\":\"ORDER123456\"}"
}

字段说明：

字段名	类型	必填	说明
room_id	int	是	房间ID
date	long	是	预约日期（Unix时间戳-秒级）
time_slot_type	int	是	时段类型：0-3
latest_arrival_time	long	否	最晚到店时间（Unix时间戳-秒级）
is_solo_mode	bool	否	是否为"无需组局"模式，默认false
player_count	int	是	人数（is_solo_mode=true时固定为1）
deposit_fee	int	是	鸽子费，0-50整数
title	string	是	组局名称
game_type	string	是	玩法类型
game_rule	string	否	具体规则
extra_info	string	否	其他补充
is_smoking	int	否	是否禁烟：0=不限制，1=禁烟，2=不禁烟
gender_limit	int	否	性别限制：0=不限，1=男，2=女
credit_limit	decimal	否	最低信誉分
min_age	int	否	最小年龄限制
max_age	int	否	最大年龄限制，0=不限
important_data	string	否	重要数据（支付相关）

响应示例：

{
  "code": 0,
  "data": {
    "reservation_id": 123,
    "start_time": "2025-12-06 06:00:00",
    "end_time": "2025-12-06 11:59:59",
    "actual_price": 80.00
  },
  "msg": "预约成功"
}

错误码：

500：参数错误、房间不存在、时间段冲突等
402：用户有其它预约时间冲突

2.5 校验是否可以创建预约

接口地址：POST /api/SQ/ValidateReservationBySlot

请求头：需要Authorization

请求体：同"创建预约"接口

响应示例：

{
  "code": 0,
  "data": {
    "canCreate": true,
    "reason": ""
  },
  "msg": ""
}

2.6 获取营业时间配置

接口地址：GET /api/SQ/GetBusinessHours

请求参数：无

响应示例：

{
  "code": 0,
  "data": {
    "open_time": "09:00",
    "close_time": "23:00",
    "is_24_hours": false,
    "description": "早9点 至 晚23点"
  },
  "msg": "ok"
}

2.7 获取房间详情（增强版）

接口地址：GET /api/SQ/GetRoomDetailEnhanced

请求参数：

参数名	类型	必填	说明
roomId	int	是	房间ID
date	long	否	查询日期（Unix时间戳-秒级），默认今天

响应示例：

{
  "code": 0,
  "data": {
    "id": 1,
    "name": "101包间",
    "room_type_name": "豪华包间",
    "image_url": "https://...",
    "images": ["https://img1.jpg", "https://img2.jpg"],
    "price_per_hour": 15.00,
    "capacity": 8,
    "description": "宽敞舒适的豪华包间",
    "amenities": ["空调", "投影仪", "茶水"],
    "status": "available",
    "today_reservations": [
      {
        "start_time": "2025-12-06 06:00:00",
        "end_time": "2025-12-06 11:59:59",
        "status": 0
      }
    ]
  },
  "msg": "ok"
}

三、修改的现有接口

3.1 加入预约接口（JoinReservation）

修改说明：新增校验，拒绝加入is_solo_mode=true的预约

新增错误响应：

{
  "code": 403,
  "data": null,
  "msg": "该预约为独享模式，不接受其他人加入"
}

四、数据库变更

4.1 新增表

SQRoomPricing（房间时段价格表）

CREATE TABLE [dbo].[SQRoomPricing](
    [id] [int] IDENTITY(1,1) NOT NULL PRIMARY KEY,
    [room_id] [int] NOT NULL,
    [time_slot_type] [int] NOT NULL,
    [standard_price] [decimal](10, 2) NOT NULL,
    [member_price] [decimal](10, 2) NOT NULL,
    [price_desc_standard] [nvarchar](100) NULL,
    [price_desc_member] [nvarchar](100) NULL,
    [effective_date_start] [date] NULL,
    [effective_date_end] [date] NULL,
    [is_active] [bit] NOT NULL DEFAULT 1,
    [created_at] [datetime] NOT NULL DEFAULT GETDATE(),
    [updated_at] [datetime] NOT NULL DEFAULT GETDATE()
)

4.2 修改表

SQRooms（房间表）

新增字段：

room_type_name (nvarchar(50))：房间类型名称
sort_order (int)：排序权重

SQRoomUnavailableTimes（房间不可用时段表）

新增字段：

time_slot_type (int)：时段类型
created_by (int)：创建人ID

SQReservations（预约表）

新增字段：

time_slot_type (int)：预约的时段类型
latest_arrival_time (datetime)：最晚到店时间
is_solo_mode (bit)：是否为无需组局模式
actual_price (decimal(10,2))：实际价格

五、业务规则说明

5.1 时段预约规则

时段不可重叠：用户不能预约同一时间有重叠的多个时段
已过时段不可预约：当前时间已过的时段不允许预约
无需组局模式：
- is_solo_mode=true时，player_count自动设为1
- 其他用户无法加入该预约

5.2 价格查询规则

优先查询有effective_date_start/end且日期匹配的记录（节假日价格）
无匹配则查询effective_date_start/end为NULL的默认价格
若某房间某时段无价格配置，该时段不可预约

5.3 房间状态判断

某房间某时段"可预约"需同时满足：

房间状态status=true（启用）
该时段无预约记录（status<3的预约）
该时段无不可用配置
该时段有价格配置

六、错误码定义

错误码	说明
0	成功
400	业务错误（如：已加入预约、预约已满）
402	时间冲突
403	权限不足（如：无法加入独享模式预约）
404	资源不存在
500	系统错误或参数错误

七、常见问题

Q1: 如何判断当前是哪个时段？

A: 根据当前时间的小时数判断：

0-5点：凌晨(0)
6-11点：上午(1)
12-17点：下午(2)
18-23点：晚上(3)

Q2: 鸽子费有什么限制？

A: 鸽子费必须是0-50之间的整数

Q3: 什么是"无需组局"模式？

A: 用户独自预约房间，不需要也不允许其他人加入，player_count固定为1

Q4: 如何设置节假日特殊价格？

A: 在SQRoomPricing表中添加记录，设置effective_date_start和effective_date_end为节假日日期范围

八、前端对接建议

8.1 日期选择器

调用GetAvailableDates获取可选日期列表，展示给用户选择

8.2 房间列表

用户选择日期后，调用GetRoomListWithSlotsNew获取房间及4个时段状态
根据time_slots[].status显示不同颜色标识：
- available：绿色
- reserved/using：红色
- unavailable：灰色
根据can_reserve字段控制【预约】按钮是否可点击

8.3 创建预约流程

用户点击【预约】按钮
跳转到预约页，携带roomId和date参数
根据房间时段状态，只显示可预约的时段选项
用户选择时段后，显示对应的价格
填写其他信息后，调用AddSQReservationBySlot创建预约

8.4 时间选择器

最晚到店时间的选择范围应根据所选时段动态限制，例如选择"上午"时段时，只能选择06:00-11:59之间的时间

九、迁移指南

9.1 数据库迁移

执行提供的SQL迁移脚本：数据库/SqlServer/更新脚本_预约时段优化.sql

9.2 旧接口兼容

原有的GetReservationRoomList接口保留，向后兼容
原有的AddSQReservation接口保留，支持精确时间预约
新接口与旧接口可共存，逐步迁移

9.3 前端迁移建议

新功能使用新接口（按时段预约）
旧功能暂时保留，使用旧接口
逐步将用户引导至新的预约流程

十、附录

10.1 完整的接口列表

接口名称	方法	路径	说明
获取未来7天日期列表	GET	/api/SQ/GetAvailableDates	新增
获取房间列表及时段状态	GET	/api/SQ/GetRoomListWithSlotsNew	新增
获取可预约房间列表	GET	/api/SQ/GetReservationRoomListBySlot	新增
按时段创建预约	POST	/api/SQ/AddSQReservationBySlot	新增
校验是否可创建预约	POST	/api/SQ/ValidateReservationBySlot	新增
获取营业时间配置	GET	/api/SQ/GetBusinessHours	已存在
获取房间详情	GET	/api/SQ/GetRoomDetailEnhanced	新增
加入预约	POST	/api/SQ/JoinReservation	修改

文档版本：v2.0
最后更新：2025-12-06
联系方式：jianweie@163.com

11 KiB Raw Blame History Unescape Escape

预约系统按时段优化 - API接口文档

更新日期：2025-12-06

一、概述

时段定义

二、新增用户端接口

2.1 获取未来7天日期列表

2.2 获取房间列表及时段状态

2.4 按时段创建预约

2.5 校验是否可以创建预约

2.6 获取营业时间配置

2.7 获取房间详情（增强版）

三、修改的现有接口

3.1 加入预约接口（JoinReservation）

四、数据库变更

4.1 新增表

SQRoomPricing（房间时段价格表）

4.2 修改表

SQRooms（房间表）

SQRoomUnavailableTimes（房间不可用时段表）

SQReservations（预约表）

五、业务规则说明

5.1 时段预约规则

5.2 价格查询规则

5.3 房间状态判断

六、错误码定义

七、常见问题

Q1: 如何判断当前是哪个时段？

Q2: 鸽子费有什么限制？

Q3: 什么是"无需组局"模式？

Q4: 如何设置节假日特殊价格？

八、前端对接建议

8.1 日期选择器

8.2 房间列表

8.3 创建预约流程

8.4 时间选择器

九、迁移指南

9.1 数据库迁移

9.2 旧接口兼容

9.3 前端迁移建议

十、附录

10.1 完整的接口列表

11 KiB

Raw Blame History