🎱 台球预订系统 API 接口文档

台球预订系统 API 接口文档

本系统是一套完整的台球预订系统，支持三端应用：

  • 商家端：商家管理台桌、教练、预订和统计
  • 教练端：教练管理个人信息、查看订单和收益统计
  • 用户端：用户搜索台桌、教练，进行预订和支付
基础信息
API基础URL /api
请求格式 JSON
响应格式 JSON
编码 UTF-8
注意事项

所有接口都需要进行签名验证，部分接口需要用户登录后才能访问。

认证说明

JWT Token认证
系统使用JWT Token进行用户身份认证，用户登录成功后会返回token，后续请求需要在请求头中携带该token。

请求头格式

Authorization: Bearer {token}

签名验证

所有API请求都需要进行签名验证，签名算法为MD5。
sign = md5(app_id + timestamp + nonce + app_secret)

签名参数

参数名 类型 必填 说明
app_id String 是 应用ID
timestamp Integer 是 时间戳
nonce String 是 随机字符串
sign String 是 签名

响应格式

统一响应结构
所有API接口都采用统一的响应格式，便于前端统一处理。
{ "code": "0000", "message": "请求成功", "data": { // 具体数据内容 }, "timestamp": 1640995200 }

响应字段说明

字段名 类型 说明
code String 响应码，0000表示成功
message String 响应消息
data Object/Array 响应数据
timestamp Integer 服务器时间戳

错误码

错误码列表
错误码 说明 解决方案
0000 请求成功 -
1001 参数错误 检查请求参数
1002 签名验证失败 检查签名算法
1003 Token无效 重新登录获取Token
1004 权限不足 检查用户权限
2001 用户不存在 检查用户ID
2002 密码错误 检查密码
3001 商家不存在 检查商家ID
3002 商家未审核 等待商家审核通过
4001 教练不存在 检查教练ID
4002 教练不在线 选择在线教练
5001 台桌不存在 检查台桌ID
5002 台桌不可用 选择其他台桌或时间
6001 订单不存在 检查订单号
6002 订单状态异常 检查订单状态
9999 系统异常 联系技术支持

商家认证接口

商家认证接口提供完整的商家入驻、审核和登录流程。系统支持智能审核状态管理，确保只有通过审核的商家才能正常使用系统功能。

审核状态码说明
verify_status = 0 待审核 - 商家申请已提交，等待管理员审核
verify_status = 1 审核通过 - 商家可以正常登录和使用系统
verify_status = 2 审核驳回 - 申请被拒绝，可查看驳回原因并重新提交
主要功能特性
智能重新提交 被驳回的申请可以重新提交，系统会更新现有记录
审核状态检查 登录时自动检查审核状态，未通过审核无法登录
文件上传支持 支持商家头像和店铺介绍图片上传
多种登录方式 支持密码登录和验证码登录两种方式
商家注册
POST /api/merchant/auth/register
商家注册接口，用于新商家入驻系统。支持智能重新提交逻辑：如果手机号已存在且审核被驳回，允许重新提交申请。

请求参数

参数名 类型 必填 说明 示例值
name String 是 商家名称 星辰台球厅
contact_person String 是 联系人 张三
contact_phone String 是 联系电话（注册后不可修改） 13800138000
address String 是 详细地址 北京市朝阳区建国路88号
password String 是 登录密码 123456
description String 否 商家描述 专业台球娱乐场所
avatar String 否 商家头像URL /uploads/avatar/xxx.jpg
shop_images Array 否 店铺图片URL数组 ["/uploads/shop/1.jpg", "/uploads/shop/2.jpg"]
业务逻辑说明
新用户注册 创建新记录，状态为待审核(0)
已存在待审核 提示"申请已提交，请等待审核"
已存在已通过 提示"该手机号已注册，请直接登录"
已存在被驳回 允许重新提交，更新现有记录并重置为待审核状态

请求示例

{ "name": "星辰台球厅", "contact_person": "张三", "contact_phone": "13800138000", "password": "123456", "address": "北京市朝阳区建国路88号", "description": "专业台球娱乐场所", "avatar": "/uploads/avatar/merchant_123.jpg", "shop_images": [ "/uploads/shop/shop_1.jpg", "/uploads/shop/shop_2.jpg" ] }

响应示例

{ "code": "0000", "message": "注册成功，请等待审核", "data": { "merchant_id": 123, "verify_status": 0, "status_text": "待审核" } }
商家登录
POST /api/merchant/auth/login
商家登录接口，返回访问令牌。包含审核状态检查逻辑，只有审核通过的商家才能正常登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
password String 是 密码 123456
审核状态说明
verify_status = 0 待审核状态，显示固定等待消息，禁止登录
verify_status = 1 审核通过，允许正常登录
verify_status = 2 审核驳回，显示具体驳回原因，禁止登录

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "merchant_info": { "id": 123, "name": "星辰台球厅", "contact_phone": "13800138000", "verify_status": 1, "status_text": "审核通过" } } }
商家验证码登录
POST /api/merchant/auth/loginWithCode
商家通过手机验证码登录，同样包含审核状态检查逻辑。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
code String 是 验证码 123456

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "merchant_info": { "id": 123, "name": "星辰台球厅", "contact_phone": "13800138000", "verify_status": 1, "status_text": "审核通过" } } }
发送找回密码验证码
POST /api/merchant/auth/sendResetCode
商家找回密码第一步：发送验证码到注册手机号。包含频率限制和每日发送次数限制。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 注册手机号 13800138000
限制规则
发送频率 同一手机号1分钟内只能发送一次
每日限制 同一手机号每天最多发送5次
验证码有效期 5分钟
账号状态检查 只有正常状态的商家账号才能找回密码

请求示例

{ "phone": "13800138000" }

响应示例

{ "code": "0000", "message": "验证码发送成功", "data": { "phone": "13800138000", "expire_minutes": 5, "send_time": "2024-01-15 14:30:00" } }
重置密码
POST /api/merchant/auth/resetPassword
商家找回密码第二步：使用验证码重置密码。重置成功后会清除所有登录token，需要重新登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 注册手机号 13800138000
code String 是 验证码 123456
password String 是 新密码（至少6位） newpassword123
安全机制
密码强度 新密码长度不能少于6位
验证码校验 验证码必须有效且未过期
强制重新登录 重置成功后清除所有登录token
一次性使用 验证码使用后立即失效

请求示例

{ "phone": "13800138000", "code": "123456", "password": "newpassword123" }

响应示例

{ "code": "0000", "message": "密码重置成功，请使用新密码登录", "data": [] }
获取商家信息
GET /api/merchant/auth/info
获取当前登录商家的详细信息。

请求参数

无需参数，通过Token获取当前登录商家信息

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 123, "name": "星辰台球厅", "contact_person": "张三", "contact_phone": "13800138000", "address": "北京市朝阳区建国路88号", "business_license": "91110000123456789X", "description": "专业台球娱乐场所", "avatar": "/uploads/avatar/merchant_123.jpg", "shop_images": [ "/uploads/shop/shop_1.jpg", "/uploads/shop/shop_2.jpg" ], "verify_status": 1, "verify_remark": "", "status": 1, "create_time": 1640995200 } }
更新商家信息
POST /api/merchant/auth/updateInfo
更新当前登录商家的信息。

请求参数

参数名 类型 必填 说明 示例值
name String 否 商家名称 星辰台球厅
phone String 否 联系电话 13800138000
email String 否 邮箱 contact@example.com
address String 否 详细地址 北京市朝阳区建国路88号
description String 否 商家描述 专业台球娱乐场所
business_hours String 否 营业时间 09:00-22:00
avatar String 否 商家头像URL /storage/uploads/avatars/20240115/xxx.jpg
shop_images Array 否 店铺介绍图片数组（最多9张） ["/storage/uploads/images/20240115/xxx1.jpg", "/storage/uploads/images/20240115/xxx2.jpg"]

请求示例

{ "name": "星辰台球厅", "description": "专业台球娱乐场所，设备先进，环境优雅", "avatar": "/storage/uploads/avatars/20240115/xxx.jpg", "shop_images": [ "/storage/uploads/images/20240115/xxx1.jpg", "/storage/uploads/images/20240115/xxx2.jpg", "/storage/uploads/images/20240115/xxx3.jpg" ] }

响应示例

{ "code": "0000", "message": "更新成功", "data": [] }

商家端台桌管理 最近更新：2025-06-19

台桌列表
GET /api/merchant/table/list
获取商家的台桌列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
status Integer 否 状态筛选：0-禁用，1-启用 1
type Integer 否 台桌类型：1-斯诺克，2-美式，3-中式 1
keyword String 否 搜索关键词（台桌名称） A区1号桌

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total": 12, "per_page": 10, "current_page": 1, "last_page": 2, "data": [ { "id": 1, "name": "A区1号桌", "type": 1, "type_text": "斯诺克", "price": 50.00, "status": 1, "status_text": "启用", "create_time": "2024-01-15 10:00:00" } ] } }
台桌详情
GET /api/merchant/table/detail
获取台桌详细信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "name": "A区1号桌", "type": 1, "type_text": "斯诺克", "description": "专业比赛用台", "price": 50.00, "status": 1, "status_text": "启用", "location": "一楼A区", "image": "/uploads/table/table1.jpg", "create_time": "2024-01-15 10:00:00", "update_time": "2024-01-15 10:00:00" } }
更新台桌信息
POST /api/merchant/table/update
更新台桌信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1
name String 否 台桌名称 A区1号桌
type Integer 否 台桌类型：1-斯诺克，2-美式，3-中式 1
description String 否 台桌描述 专业比赛用台
price Decimal 否 小时收费 50.00
status Integer 否 状态：0-禁用，1-启用 1
location String 否 位置信息 一楼A区
image String 否 台桌图片URL /uploads/table/table1.jpg

响应示例

{ "code": "0000", "message": "更新成功", "data": { "id": 1, "name": "A区1号桌", "type": 1, "description": "专业比赛用台", "price": 50.00, "status": 1, "location": "一楼A区", "image": "/uploads/table/table1.jpg", "update_time": "2024-01-15 11:30:00" } }
删除台桌
POST /api/merchant/table/delete
删除台桌。如果台桌存在未完成的预约，将无法删除。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1

响应示例

{ "code": "0000", "message": "删除成功", "data": [] }
教练列表
GET /api/merchant/coach/list
获取商家的教练列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
status Integer 否 状态筛选：0-禁用，1-启用 1
keyword String 否 搜索关键词（姓名或电话） 张教练

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total": 12, "per_page": 10, "current_page": 1, "last_page": 2, "data": [ { "id": 1, "name": "张教练", "phone": "13800138000", "avatar": "/uploads/coach/avatar1.jpg", "gender": 1, "age": 28, "specialties": "斯诺克,九球", "experience": "5年教学经验", "hourly_rate": 120.00, "status": 1, "create_time": "2024-01-15 10:00:00" } ] } }
教练申请
POST /api/merchant/coach/apply
教练申请成为商家的教练。

请求参数

参数名 类型 必填 说明 示例值
name String 是 教练姓名 张教练
phone String 是 联系电话 13800138000
avatar String 是 头像URL /uploads/coach/avatar1.jpg
gender Integer 是 性别：1-男，2-女 1
age Integer 是 年龄 28
specialties String 是 擅长项目，多个用逗号分隔 斯诺克,九球
experience String 是 教学经验 5年教学经验
hourly_rate Decimal 是 每小时费用 120.00

请求示例

{ "name": "张教练", "phone": "13800138000", "avatar": "/uploads/coach/avatar1.jpg", "gender": 1, "age": 28, "specialties": "斯诺克,九球", "experience": "5年教学经验", "hourly_rate": 120.00 }

响应示例

{ "code": "0000", "message": "申请成功", "data": [] }
意见反馈
POST /api/merchant/feedback
提交意见反馈。

请求参数

参数名 类型 必填 说明 示例值
content String 是 反馈内容 我有一些建议...
contact String 否 联系方式 13800138000

请求示例

{ "content": "我有一些建议...", "contact": "13800138000" }

响应示例

{ "code": "0000", "message": "提交成功", "data": [] }
商家入驻申请
POST /api/merchant/apply
商家入驻申请。

请求参数

台球预订系统 API 接口文档

🎱 台球预订系统 API 接口文档

台球预订系统 API 接口文档

本系统是一套完整的台球预订系统，支持三端应用：

  • 商家端：商家管理台桌、教练、预订和统计
  • 教练端：教练管理个人信息、查看订单和收益统计
  • 用户端：用户搜索台桌、教练，进行预订和支付
基础信息
参数名 类型 必填 说明 示例值
name String 是 商家名称 星辰台球厅
phone String 是 联系电话 13800138000
email String 是 邮箱 contact@example.com
API基础URL /api
请求格式 JSON
响应格式 JSON
编码 UTF-8
注意事项

所有接口都需要进行签名验证，部分接口需要用户登录后才能访问。

认证说明

JWT Token认证
系统使用JWT Token进行用户身份认证，用户登录成功后会返回token，后续请求需要在请求头中携带该token。

请求头格式

Authorization: Bearer {token}

签名验证

所有API请求都需要进行签名验证，签名算法为MD5。
sign = md5(app_id + timestamp + nonce + app_secret)

签名参数

参数名 类型 必填 说明
app_id String 是 应用ID
timestamp Integer 是 时间戳
nonce String 是 随机字符串
sign String 是 签名

响应格式

统一响应结构
所有API接口都采用统一的响应格式，便于前端统一处理。
{ "code": "0000", "message": "请求成功", "data": { // 具体数据内容 }, "timestamp": 1640995200 }

响应字段说明

字段名 类型 说明
code String 响应码，0000表示成功
message String 响应消息
data Object/Array 响应数据
timestamp Integer 服务器时间戳

错误码

错误码列表
错误码 说明 解决方案
0000 请求成功 -
1001 参数错误 检查请求参数
1002 签名验证失败 检查签名算法
1003 Token无效 重新登录获取Token
1004 权限不足 检查用户权限
2001 用户不存在 检查用户ID
2002 密码错误 检查密码
3001 商家不存在 检查商家ID
3002 商家未审核 等待商家审核通过
4001 教练不存在 检查教练ID
4002 教练不在线 选择在线教练
5001 台桌不存在 检查台桌ID
5002 台桌不可用 选择其他台桌或时间
6001 订单不存在 检查订单号
6002 订单状态异常 检查订单状态
9999 系统异常 联系技术支持

商家认证接口

商家认证接口提供完整的商家入驻、审核和登录流程。系统支持智能审核状态管理，确保只有通过审核的商家才能正常使用系统功能。

审核状态码说明
verify_status = 0 待审核 - 商家申请已提交，等待管理员审核
verify_status = 1 审核通过 - 商家可以正常登录和使用系统
verify_status = 2 审核驳回 - 申请被拒绝，可查看驳回原因并重新提交
主要功能特性
智能重新提交 被驳回的申请可以重新提交，系统会更新现有记录
审核状态检查 登录时自动检查审核状态，未通过审核无法登录
文件上传支持 支持商家头像和店铺介绍图片上传
多种登录方式 支持密码登录和验证码登录两种方式
商家注册
POST /api/merchant/auth/register
商家注册接口，用于新商家入驻系统。支持智能重新提交逻辑：如果手机号已存在且审核被驳回，允许重新提交申请。

请求参数

参数名 类型 必填 说明 示例值
name String 是 商家名称 星辰台球厅
contact_person String 是 联系人 张三
contact_phone String 是 联系电话（注册后不可修改） 13800138000
address String 是 详细地址 北京市朝阳区建国路88号
password String 是 登录密码 123456
description String 否 商家描述 专业台球娱乐场所
avatar String 否 商家头像URL /uploads/avatar/xxx.jpg
shop_images Array 否 店铺图片URL数组 ["/uploads/shop/1.jpg", "/uploads/shop/2.jpg"]
业务逻辑说明
新用户注册 创建新记录，状态为待审核(0)
已存在待审核 提示"申请已提交，请等待审核"
已存在已通过 提示"该手机号已注册，请直接登录"
已存在被驳回 允许重新提交，更新现有记录并重置为待审核状态

请求示例

{ "name": "星辰台球厅", "contact_person": "张三", "contact_phone": "13800138000", "password": "123456", "address": "北京市朝阳区建国路88号", "description": "专业台球娱乐场所", "avatar": "/uploads/avatar/merchant_123.jpg", "shop_images": [ "/uploads/shop/shop_1.jpg", "/uploads/shop/shop_2.jpg" ] }

响应示例

{ "code": "0000", "message": "注册成功，请等待审核", "data": { "merchant_id": 123, "verify_status": 0, "status_text": "待审核" } }
商家登录
POST /api/merchant/auth/login
商家登录接口，返回访问令牌。包含审核状态检查逻辑，只有审核通过的商家才能正常登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
password String 是 密码 123456
审核状态说明
verify_status = 0 待审核状态，显示固定等待消息，禁止登录
verify_status = 1 审核通过，允许正常登录
verify_status = 2 审核驳回，显示具体驳回原因，禁止登录

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "merchant_info": { "id": 123, "name": "星辰台球厅", "contact_phone": "13800138000", "verify_status": 1, "status_text": "审核通过" } } }
商家验证码登录
POST /api/merchant/auth/loginWithCode
商家通过手机验证码登录，同样包含审核状态检查逻辑。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
code String 是 验证码 123456

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "merchant_info": { "id": 123, "name": "星辰台球厅", "contact_phone": "13800138000", "verify_status": 1, "status_text": "审核通过" } } }
发送找回密码验证码
POST /api/merchant/auth/sendResetCode
商家找回密码第一步：发送验证码到注册手机号。包含频率限制和每日发送次数限制。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 注册手机号 13800138000
限制规则
发送频率 同一手机号1分钟内只能发送一次
每日限制 同一手机号每天最多发送5次
验证码有效期 5分钟
账号状态检查 只有正常状态的商家账号才能找回密码

请求示例

{ "phone": "13800138000" }

响应示例

{ "code": "0000", "message": "验证码发送成功", "data": { "phone": "13800138000", "expire_minutes": 5, "send_time": "2024-01-15 14:30:00" } }
重置密码
POST /api/merchant/auth/resetPassword
商家找回密码第二步：使用验证码重置密码。重置成功后会清除所有登录token，需要重新登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 注册手机号 13800138000
code String 是 验证码 123456
password String 是 新密码（至少6位） newpassword123
安全机制
密码强度 新密码长度不能少于6位
验证码校验 验证码必须有效且未过期
强制重新登录 重置成功后清除所有登录token
一次性使用 验证码使用后立即失效

请求示例

{ "phone": "13800138000", "code": "123456", "password": "newpassword123" }

响应示例

{ "code": "0000", "message": "密码重置成功，请使用新密码登录", "data": [] }
获取商家信息
GET /api/merchant/auth/info
获取当前登录商家的详细信息。

请求参数

无需参数，通过Token获取当前登录商家信息

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 123, "name": "星辰台球厅", "contact_person": "张三", "contact_phone": "13800138000", "address": "北京市朝阳区建国路88号", "business_license": "91110000123456789X", "description": "专业台球娱乐场所", "avatar": "/uploads/avatar/merchant_123.jpg", "shop_images": [ "/uploads/shop/shop_1.jpg", "/uploads/shop/shop_2.jpg" ], "verify_status": 1, "verify_remark": "", "status": 1, "create_time": 1640995200 } }
更新商家信息
POST /api/merchant/auth/updateInfo
更新当前登录商家的信息。

请求参数

参数名 类型 必填 说明 示例值
name String 否 商家名称 星辰台球厅
phone String 否 联系电话 13800138000
email String 否 邮箱 contact@example.com
address String 否 详细地址 北京市朝阳区建国路88号
description String 否 商家描述 专业台球娱乐场所
business_hours String 否 营业时间 09:00-22:00
avatar String 否 商家头像URL /storage/uploads/avatars/20240115/xxx.jpg
shop_images Array 否 店铺介绍图片数组（最多9张） ["/storage/uploads/images/20240115/xxx1.jpg", "/storage/uploads/images/20240115/xxx2.jpg"]

请求示例

{ "name": "星辰台球厅", "description": "专业台球娱乐场所，设备先进，环境优雅", "avatar": "/storage/uploads/avatars/20240115/xxx.jpg", "shop_images": [ "/storage/uploads/images/20240115/xxx1.jpg", "/storage/uploads/images/20240115/xxx2.jpg", "/storage/uploads/images/20240115/xxx3.jpg" ] }

响应示例

{ "code": "0000", "message": "更新成功", "data": [] }

商家端台桌管理

台桌列表
GET /api/merchant/table/list
获取商家的台桌列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
status Integer 否 状态筛选：0-禁用，1-启用 1
type Integer 否 台桌类型：1-斯诺克，2-美式，3-中式 1
keyword String 否 搜索关键词（台桌名称） A区1号桌

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total": 12, "per_page": 10, "current_page": 1, "last_page": 2, "data": [ { "id": 1, "name": "A区1号桌", "type": 1, "type_text": "斯诺克", "price": 50.00, "status": 1, "status_text": "启用", "create_time": "2024-01-15 10:00:00" } ] } }
台桌详情
GET /api/merchant/table/detail
获取台桌详细信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "name": "A区1号桌", "type": 1, "type_text": "斯诺克", "description": "专业比赛用台", "price": 50.00, "status": 1, "status_text": "启用", "location": "一楼A区", "image": "/uploads/table/table1.jpg", "create_time": "2024-01-15 10:00:00", "update_time": "2024-01-15 10:00:00" } }
更新台桌信息
POST /api/merchant/table/update
更新台桌信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1
name String 否 台桌名称 A区1号桌
type Integer 否 台桌类型：1-斯诺克，2-美式，3-中式 1
description String 否 台桌描述 专业比赛用台
price Decimal 否 小时收费 50.00
status Integer 否 状态：0-禁用，1-启用 1
location String 否 位置信息 一楼A区
image String 否 台桌图片URL /uploads/table/table1.jpg

响应示例

{ "code": "0000", "message": "更新成功", "data": { "id": 1, "name": "A区1号桌", "type": 1, "description": "专业比赛用台", "price": 50.00, "status": 1, "location": "一楼A区", "image": "/uploads/table/table1.jpg", "update_time": "2024-01-15 11:30:00" } }
删除台桌
POST /api/merchant/table/delete
删除台桌。如果台桌存在未完成的预约，将无法删除。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1

响应示例

{ "code": "0000", "message": "删除成功", "data": [] }
教练列表
GET /api/merchant/coach/list
获取商家的教练列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
status Integer 否 状态筛选：0-禁用，1-启用 1
keyword String 否 搜索关键词（姓名或电话） 张教练

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total": 12, "per_page": 10, "current_page": 1, "last_page": 2, "data": [ { "id": 1, "name": "张教练", "phone": "13800138000", "avatar": "/uploads/coach/avatar1.jpg", "gender": 1, "age": 28, "specialties": "斯诺克,九球", "experience": "5年教学经验", "hourly_rate": 120.00, "status": 1, "create_time": "2024-01-15 10:00:00" } ] } } 台球预订系统 API 接口文档

🎱 台球预订系统 API 接口文档

台球预订系统 API 接口文档

本系统是一套完整的台球预订系统，支持三端应用：

  • 商家端：商家管理台桌、教练、预订和统计
  • 教练端：教练管理个人信息、查看订单和收益统计
  • 用户端：用户搜索台桌、教练，进行预订和支付
基础信息
API基础URL /api
请求格式 JSON
响应格式 JSON
编码 UTF-8
注意事项

所有接口都需要进行签名验证，部分接口需要用户登录后才能访问。

认证说明

JWT Token认证
系统使用JWT Token进行用户身份认证，用户登录成功后会返回token，后续请求需要在请求头中携带该token。

请求头格式

Authorization: Bearer {token}

签名验证

所有API请求都需要进行签名验证，签名算法为MD5。
sign = md5(app_id + timestamp + nonce + app_secret)

签名参数

参数名 类型 必填 说明
app_id String 是 应用ID
timestamp Integer 是 时间戳
nonce String 是 随机字符串
sign String 是 签名

响应格式

统一响应结构
所有API接口都采用统一的响应格式，便于前端统一处理。
{ "code": "0000", "message": "请求成功", "data": { // 具体数据内容 }, "timestamp": 1640995200 }

响应字段说明

字段名 类型 说明
code String 响应码，0000表示成功
message String 响应消息
data Object/Array 响应数据
timestamp Integer 服务器时间戳

错误码

错误码列表
错误码 说明 解决方案
0000 请求成功 -
1001 参数错误 检查请求参数
1002 签名验证失败 检查签名算法
1003 Token无效 重新登录获取Token
1004 权限不足 检查用户权限
2001 用户不存在 检查用户ID
2002 密码错误 检查密码
3001 商家不存在 检查商家ID
3002 商家未审核 等待商家审核通过
4001 教练不存在 检查教练ID
4002 教练不在线 选择在线教练
5001 台桌不存在 检查台桌ID
5002 台桌不可用 选择其他台桌或时间
6001 订单不存在 检查订单号
6002 订单状态异常 检查订单状态
9999 系统异常 联系技术支持

商家认证接口

商家认证接口提供完整的商家入驻、审核和登录流程。系统支持智能审核状态管理，确保只有通过审核的商家才能正常使用系统功能。

审核状态码说明
verify_status = 0 待审核 - 商家申请已提交，等待管理员审核
verify_status = 1 审核通过 - 商家可以正常登录和使用系统
verify_status = 2 审核驳回 - 申请被拒绝，可查看驳回原因并重新提交
主要功能特性
智能重新提交 被驳回的申请可以重新提交，系统会更新现有记录
审核状态检查 登录时自动检查审核状态，未通过审核无法登录
文件上传支持 支持商家头像和店铺介绍图片上传
多种登录方式 支持密码登录和验证码登录两种方式
商家注册
POST /api/merchant/auth/register
商家注册接口，用于新商家入驻系统。支持智能重新提交逻辑：如果手机号已存在且审核被驳回，允许重新提交申请。

请求参数

参数名 类型 必填 说明 示例值
name String 是 商家名称 星辰台球厅
contact_person String 是 联系人 张三
contact_phone String 是 联系电话（注册后不可修改） 13800138000
address String 是 详细地址 北京市朝阳区建国路88号
password String 是 登录密码 123456
description String 否 商家描述 专业台球娱乐场所
avatar String 否 商家头像URL /uploads/avatar/xxx.jpg
shop_images Array 否 店铺图片URL数组 ["/uploads/shop/1.jpg", "/uploads/shop/2.jpg"]
业务逻辑说明
新用户注册 创建新记录，状态为待审核(0)
已存在待审核 提示"申请已提交，请等待审核"
已存在已通过 提示"该手机号已注册，请直接登录"
已存在被驳回 允许重新提交，更新现有记录并重置为待审核状态

请求示例

{ "name": "星辰台球厅", "contact_person": "张三", "contact_phone": "13800138000", "password": "123456", "address": "北京市朝阳区建国路88号", "description": "专业台球娱乐场所", "avatar": "/uploads/avatar/merchant_123.jpg", "shop_images": [ "/uploads/shop/shop_1.jpg", "/uploads/shop/shop_2.jpg" ] }

响应示例

{ "code": "0000", "message": "注册成功，请等待审核", "data": { "merchant_id": 123, "verify_status": 0, "status_text": "待审核" } }
商家登录
POST /api/merchant/auth/login
商家登录接口，返回访问令牌。包含审核状态检查逻辑，只有审核通过的商家才能正常登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
password String 是 密码 123456
审核状态说明
verify_status = 0 待审核状态，显示固定等待消息，禁止登录
verify_status = 1 审核通过，允许正常登录
verify_status = 2 审核驳回，显示具体驳回原因，禁止登录

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "merchant_info": { "id": 123, "name": "星辰台球厅", "contact_phone": "13800138000", "verify_status": 1, "status_text": "审核通过" } } }
商家验证码登录
POST /api/merchant/auth/loginWithCode
商家通过手机验证码登录，同样包含审核状态检查逻辑。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
code String 是 验证码 123456

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "merchant_info": { "id": 123, "name": "星辰台球厅", "contact_phone": "13800138000", "verify_status": 1, "status_text": "审核通过" } } }
发送找回密码验证码
POST /api/merchant/auth/sendResetCode
商家找回密码第一步：发送验证码到注册手机号。包含频率限制和每日发送次数限制。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 注册手机号 13800138000
限制规则
发送频率 同一手机号1分钟内只能发送一次
每日限制 同一手机号每天最多发送5次
验证码有效期 5分钟
账号状态检查 只有正常状态的商家账号才能找回密码

请求示例

{ "phone": "13800138000" }

响应示例

{ "code": "0000", "message": "验证码发送成功", "data": { "phone": "13800138000", "expire_minutes": 5, "send_time": "2024-01-15 14:30:00" } }
重置密码
POST /api/merchant/auth/resetPassword
商家找回密码第二步：使用验证码重置密码。重置成功后会清除所有登录token，需要重新登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 注册手机号 13800138000
code String 是 验证码 123456
password String 是 新密码（至少6位） newpassword123
安全机制
密码强度 新密码长度不能少于6位
验证码校验 验证码必须有效且未过期
强制重新登录 重置成功后清除所有登录token
一次性使用 验证码使用后立即失效

请求示例

{ "phone": "13800138000", "code": "123456", "password": "newpassword123" }

响应示例

{ "code": "0000", "message": "密码重置成功，请使用新密码登录", "data": [] }
获取商家信息
GET /api/merchant/auth/info
获取当前登录商家的详细信息。

请求参数

无需参数，通过Token获取当前登录商家信息

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 123, "name": "星辰台球厅", "contact_person": "张三", "contact_phone": "13800138000", "address": "北京市朝阳区建国路88号", "business_license": "91110000123456789X", "description": "专业台球娱乐场所", "avatar": "/uploads/avatar/merchant_123.jpg", "shop_images": [ "/uploads/shop/shop_1.jpg", "/uploads/shop/shop_2.jpg" ], "verify_status": 1, "verify_remark": "", "status": 1, "create_time": 1640995200 } }
更新商家信息
POST /api/merchant/auth/updateInfo
更新当前登录商家的信息。

请求参数

参数名 类型 必填 说明 示例值
name String 否 商家名称 星辰台球厅
phone String 否 联系电话 13800138000
email String 否 邮箱 contact@example.com
address String 否 详细地址 北京市朝阳区建国路88号
description String 否 商家描述 专业台球娱乐场所
business_hours String 否 营业时间 09:00-22:00
avatar String 否 商家头像URL /storage/uploads/avatars/20240115/xxx.jpg
shop_images Array 否 店铺介绍图片数组（最多9张） ["/storage/uploads/images/20240115/xxx1.jpg", "/storage/uploads/images/20240115/xxx2.jpg"]

请求示例

{ "name": "星辰台球厅", "description": "专业台球娱乐场所，设备先进，环境优雅", "avatar": "/storage/uploads/avatars/20240115/xxx.jpg", "shop_images": [ "/storage/uploads/images/20240115/xxx1.jpg", "/storage/uploads/images/20240115/xxx2.jpg", "/storage/uploads/images/20240115/xxx3.jpg" ] }

响应示例

{ "code": "0000", "message": "更新成功", "data": [] }

商家端台桌管理

台桌列表
GET /api/merchant/table/list
获取商家的台桌列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
status Integer 否 状态筛选：0-禁用，1-启用 1
type Integer 否 台桌类型：1-斯诺克，2-美式，3-中式 1
keyword String 否 搜索关键词（台桌名称） A区1号桌

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total": 12, "per_page": 10, "current_page": 1, "last_page": 2, "data": [ { "id": 1, "name": "A区1号桌", "type": 1, "type_text": "斯诺克", "price": 50.00, "status": 1, "status_text": "启用", "create_time": "2024-01-15 10:00:00" } ] } }
台桌详情
GET /api/merchant/table/detail
获取台桌详细信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "name": "A区1号桌", "type": 1, "type_text": "斯诺克", "description": "专业比赛用台", "price": 50.00, "status": 1, "status_text": "启用", "location": "一楼A区", "image": "/uploads/table/table1.jpg", "create_time": "2024-01-15 10:00:00", "update_time": "2024-01-15 10:00:00" } }
更新台桌信息
POST /api/merchant/table/update
更新台桌信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1
name String 否 台桌名称 A区1号桌
type Integer 否 台桌类型：1-斯诺克，2-美式，3-中式 1
description String 否 台桌描述 专业比赛用台
price Decimal 否 小时收费 50.00
status Integer 否 状态：0-禁用，1-启用 1
location String 否 位置信息 一楼A区
image String 否 台桌图片URL /uploads/table/table1.jpg

响应示例

{ "code": "0000", "message": "更新成功", "data": { "id": 1, "name": "A区1号桌", "type": 1, "description": "专业比赛用台", "price": 50.00, "status": 1, "location": "一楼A区", "image": "/uploads/table/table1.jpg", "update_time": "2024-01-15 11:30:00" } }
删除台桌
POST /api/merchant/table/delete
删除台桌。如果台桌存在未完成的预约，将无法删除。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 台桌ID 1

响应示例

{ "code": "0000", "message": "删除成功", "data": [] }

商家端教练管理 最近更新：2025-06-19

教练列表
GET /api/merchant/coach/list
获取商家的教练列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
status Integer 否 状态筛选：0-禁用，1-启用 1
keyword String 否 搜索关键词（姓名或电话） 张教练

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total": 12, "per_page": 10, "current_page": 1, "last_page": 2, "data": [ { "id": 1, "name": "张教练", "phone": "13800138000", "avatar": "/uploads/coach/avatar1.jpg", "gender": 1, "age": 28, "specialties": "斯诺克,九球", "experience": "5年教学经验", "hourly_rate": 120.00, "status": 1, "create_time": "2024-01-15 10:00:00" } ] } }
教练详情
GET /api/merchant/coach/detail
获取教练详细信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 教练ID 1

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "name": "张教练", "phone": "13800138000", "avatar": "/uploads/coach/avatar1.jpg", "gender": 1, "age": 28, "description": "专业台球教练，擅长斯诺克和九球教学", "specialties": "斯诺克,九球", "experience": "5年教学经验", "certificates": "国家级台球教练证", "hourly_rate": 120.00, "status": 1, "work_days": "1,2,3,4,5", "work_hours": "09:00-18:00", "create_time": "2024-01-15 10:00:00", "update_time": "2024-01-15 10:00:00" } }
更新教练信息
POST /api/merchant/coach/update
更新教练信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 教练ID 1
name String 否 教练姓名 张教练
phone String 否 联系电话 13800138000
gender Integer 否 性别：1-男，2-女 1
age Integer 否 年龄 28
avatar String 否 头像URL /uploads/coach/avatar1.jpg
description String 否 教练简介 专业台球教练，擅长斯诺克和九球教学
specialties String 否 专长领域，多个用逗号分隔 斯诺克,九球
experience String 否 教学经验 5年教学经验
certificates String 否 持有证书 国家级台球教练证
hourly_rate Decimal 否 小时收费 120.00
status Integer 否 状态：0-禁用，1-启用 1
work_days String 否 工作日，1-7代表周一到周日，多个用逗号分隔 1,2,3,4,5
work_hours String 否 工作时间段 09:00-18:00

响应示例

{ "code": "0000", "message": "更新成功", "data": { "id": 1, "name": "张教练", "phone": "13800138000", "avatar": "/uploads/coach/avatar1.jpg", "gender": 1, "age": 28, "description": "专业台球教练，擅长斯诺克和九球教学", "specialties": "斯诺克,九球", "experience": "5年教学经验", "certificates": "国家级台球教练证", "hourly_rate": 120.00, "status": 1, "work_days": "1,2,3,4,5", "work_hours": "09:00-18:00", "update_time": "2024-01-15 11:30:00" } }
删除教练
POST /api/merchant/coach/delete
删除教练。如果教练存在未完成的预约，将无法删除。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 教练ID 1

响应示例

{ "code": "0000", "message": "删除成功", "data": [] }

预订管理接口

预订列表
GET /api/merchant/booking/list
获取商家的预订列表。

请求参数

参数名 类型 必填 说明 示例值
status String 否 状态筛选：pending/confirmed/completed/cancelled confirmed
start_date String 否 开始日期 2024-01-01
end_date String 否 结束日期 2024-01-31

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "order_id": "TB202401011400001", "type": "table", "status": "confirmed", "amount": 100.00, "customer_phone": "13800138000", "start_time": "2024-01-01 14:00:00", "end_time": "2024-01-01 16:00:00" } ], "total": 25 } }
确认预订
POST /api/merchant/booking/confirm
确认用户的预订申请。

请求参数

参数名 类型 必填 说明 示例值
order_id String 是 订单ID TB202401011400001

响应示例

{ "code": "0000", "message": "确认成功", "data": { "order_id": "TB202401011400001", "status": "confirmed" } }

教练端认证接口

教练登录
POST /api/coach/auth/login
教练登录接口，验证用户名和密码后返回访问令牌。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13899888898
password String 是 密码 123456

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "coach_info": { "id": 1, "phone": "13899888898", "nickname": "李教练", "avatar": "/uploads/coach/avatar.jpg", "phone": "13800138001", "specialties": "斯诺克,九球", "experience": 5, "rating": 4.8, "status": 1 } } }
教练注册
POST /api/coach/auth/register
教练注册接口，创建新的教练账户，需要等待管理员审核。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13899888898
password String 是 密码 123456
gender String 否 性别 女
age Integer 否 年龄 25
avatar String 否 头像URL /uploads/coach/avatar.jpg
specialties Array 是 专业特长(数组) ["1","2","3"]
level String 否 技术等级 2
experience_years Integer 否 从业年限 5
hourly_rate Decimal 否 课时费(元/小时) 139.00
bio String 否 个人简介 甜美可人，专业服务

响应示例

{ "code": "0000", "message": "注册成功，请等待审核", "data": { "id": 123 } }
教练退出登录
POST /api/coach/auth/logout
教练退出登录接口，清除登录状态。
认证要求

此接口需要教练登录，请在请求头中包含有效的Token。

响应示例

{ "code": "0000", "message": "退出成功", "data": [] }
获取教练信息
GET /api/coach/auth/info
获取当前登录教练的详细信息。
认证要求

此接口需要教练登录，请在请求头中包含有效的Token。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "phone": "13899888898", "nickname": "李教练", "avatar": "/uploads/coach/avatar.jpg", "phone": "13800138001", "specialties": "斯诺克,九球", "experience": 5, "hourly_rate": 120.00, "description": "专业台球教练，五年教学经验", "rating": 4.8, "order_count": 158, "status": 1, "create_time": 1640995200 } }
更新教练信息
POST /api/coach/auth/updateinfo
更新教练的基本信息，如昵称、头像、联系方式等。
认证要求

此接口需要教练登录，请在请求头中包含有效的Token。

请求参数

参数名 类型 必填 说明 示例值
gender String 否 性别 女
age Integer 否 年龄 25
avatar String 否 头像URL /uploads/coach/avatar.jpg
specialties Array 否 专业特长(数组) ["1","2","3"]
level String 否 技术等级 2
experience_years Integer 否 从业年限 5
hourly_rate Decimal 否 课时费(元/小时) 139.00
bio String 否 个人简介 甜美可人，专业服务
life_photos Array 否 生活照数组（最多9张） ["/storage/uploads/images/20240115/xxx1.jpg", "/storage/uploads/images/20240115/xxx2.jpg"]

响应示例

{ "code": "0000", "message": "更新成功", "data": [] }
更新教练档案
POST /api/coach/auth/updateprofile
更新教练的详细档案信息，包括真实姓名、身份证、证书等。
认证要求

此接口需要教练登录，请在请求头中包含有效的Token。

请求参数

参数名 类型 必填 说明 示例值
certificates String 否 持有证书 专业证书
achievements String 否 主要成就 领导省一级冠军
teaching_methods Array 否 教学方式 ["1","2","3"]
available_days String 否 可教学时间(周几) 1,2,3,5,6,7
start_time String 否 开始时间 10:00:00
end_time String 否 结束时间 22:00:00
max_students Integer 否 最大学员数 20

响应示例

{ "code": "0000", "message": "档案更新成功", "data": [] }
教练实名认证
POST /api/coach/auth/realNameAuth
教练实名认证接口，提交身份证信息进行实名认证。
认证要求

此接口需要教练登录，请在请求头中包含有效的Token。

请求参数

参数名 类型 必填 说明 示例值
person_name String 是 真实姓名 李小美
id_card String 是 身份证号码 110101199501011234

响应示例

{ "code": "0000", "message": "实名认证成功", "data": { "is_verified": 1, "person_name": "李小美" } }
获取实名认证状态
GET /api/coach/auth/verifyStatus
获取当前教练的实名认证状态。
认证要求

此接口需要教练登录，请在请求头中包含有效的Token。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "is_verified": 1, "person_name": "李小美", "id_card": "110101199501***234", "verify_time": "2025-06-02 15:30:00" } }

教练端短信验证码登录

发送登录验证码
POST /api/coach/auth/sendLoginCode
向已注册教练手机号发送登录验证码，系统自动生成6位数字验证码并发送。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000

响应示例

{ "code": "0000", "message": "验证码发送成功", "data": { "phone": "13800138000", "code": "342561", "expire_minutes": 5, "send_time": "2024-01-15 10:30:00", "template": "verify_code" } }
注意事项

• 验证码由系统自动生成，无需前端传入

• 同一手机号1分钟内只能发送一次验证码

• 验证码有效期为5分钟

• 只有已注册的教练才能接收登录验证码

手机号验证码登录
POST /api/coach/auth/loginWithCode
教练使用手机号+验证码登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
code String 是 6位数验证码 123456

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...", "login_type": "sms_code", "coach_info": { "id": 1, "name": "张教练", "nickname": "小张", "phone": "13800138000", "avatar": "https://example.com/avatar.jpg", "merchant_id": 1, "status": 1 } } }
发送找回密码验证码
POST /api/coach/auth/sendResetCode
教练找回密码第一步：发送验证码到注册手机号。包含频率限制和每日发送次数限制。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 注册手机号 13800138000
限制规则
发送频率 同一手机号1分钟内只能发送一次
每日限制 同一手机号每天最多发送5次
验证码有效期 5分钟
账号状态检查 只有正常状态的教练账号才能找回密码

请求示例

{ "phone": "13800138000" }

响应示例

{ "code": "0000", "message": "验证码发送成功", "data": { "phone": "13800138000", "expire_minutes": 5, "send_time": "2024-01-15 14:30:00" } }
重置密码
POST /api/coach/auth/resetPassword
教练找回密码第二步：使用验证码重置密码。重置成功后会清除所有登录token，需要重新登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 注册手机号 13800138000
code String 是 验证码 123456
password String 是 新密码（至少6位） newpassword123
安全机制
密码强度 新密码长度不能少于6位
验证码校验 验证码必须有效且未过期
强制重新登录 重置成功后清除所有登录token
一次性使用 验证码使用后立即失效
密码加密 使用PHP password_hash函数加密存储

请求示例

{ "phone": "13800138000", "code": "123456", "password": "newpassword123" }

响应示例

{ "code": "0000", "message": "密码重置成功，请使用新密码登录", "data": [] }

教练端订单管理

我的订单列表
GET /api/coach/order/list
获取教练的订单列表。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "order_id": "CO202401011400001", "type": "coach", "status": "confirmed", "amount": 240.00, "customer_name": "张三", "start_time": "2024-01-01 14:00:00", "end_time": "2024-01-01 16:00:00" } ], "total": 15 } }

教练端数据统计

收益统计
GET /api/coach/statistics/income
获取教练的收益统计数据。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total_income": 15600.00, "month_income": 3200.00, "total_hours": 130, "total_orders": 65, "rating": 4.8 } }

用户端认证接口

微信登录
POST /api/user/auth/wxlogin
用户微信登录接口，通过微信授权code获取用户信息并登录。

请求参数

参数名 类型 必填 说明 示例值
code String 是 微信授权code 013Q7s0w3m2QC93X6H1w3Qc13d1Q7s0l
nickname String 否 用户昵称 台球爱好者
avatar String 否 用户头像 https://example.com/avatar.jpg

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "user_info": { "id": 1001, "nickname": "台球爱好者", "avatar": "https://example.com/avatar.jpg", "phone": "13800138000", "status": 1 } } }
手机号登录
POST /api/user/auth/phonelogin
用户手机号登录接口，通过手机号和验证码登录。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
code String 是 短信验证码 123456

响应示例

{ "code": "0000", "message": "登录成功", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "user_info": { "id": 1001, "nickname": "用户8000", "avatar": "", "phone": "13800138000", "status": 1 } } }
用户登出
POST /api/user/auth/logout
用户登出接口，清除用户登录状态。

请求参数

无需参数，通过Token获取当前登录用户信息

响应示例

{ "code": "0000", "message": "登出成功", "data": [] }
获取用户信息
GET /api/user/auth/info
获取当前登录用户的详细信息。

请求参数

无需参数，通过Token获取当前登录用户信息

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1001, "username": "13800138000", "nickname": "台球爱好者", "email": "user@example.com", "phone": "13800138000", "avatar": "https://example.com/avatar.jpg", "status": 1, "create_time": "2024-01-01 10:00:00" } }
更新用户信息
POST /api/user/auth/updateprofile
更新当前登录用户的个人信息。

请求参数

参数名 类型 必填 说明 示例值
nickname String 否 用户昵称 台球大师
email String 否 邮箱地址 user@example.com
avatar String 否 头像URL https://example.com/new_avatar.jpg

响应示例

{ "code": "0000", "message": "更新成功", "data": [] }
实名认证
POST /api/user/auth/realnameauth
用户实名认证接口，提交身份证信息进行实名认证。

请求参数

参数名 类型 必填 说明 示例值
real_name String 是 真实姓名 张三
id_card String 是 身份证号 110101199001011234

响应示例

{ "code": "0000", "message": "实名认证成功", "data": [] }
绑定手机号
POST /api/user/auth/bindphone
为当前用户绑定手机号码。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
code String 是 短信验证码 123456

响应示例

{ "code": "0000", "message": "绑定成功", "data": [] }

用户端商家相关

商家列表
GET /api/user/merchant/list
获取商家列表，支持关键词搜索、城市筛选、距离排序等。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
keyword String 否 搜索关键词 星辰台球
city String 否 城市筛选 北京市
district String 否 区域筛选 朝阳区
sort String 否 排序方式：rating/distance/table_count rating
latitude Float 否 纬度（用于距离排序） 39.9042
longitude Float 否 经度（用于距离排序） 116.4074

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 1, "name": "星辰台球厅", "avatar": "/uploads/merchant/avatar.jpg", "address": "北京市朝阳区建国路88号", "phone": "010-12345678", "rating": 4.8, "table_count": 12, "coach_count": 3, "business_hours": "08:00-24:00", "description": "专业台球娱乐场所", "distance": "1.2km" } ], "total": 25, "current_page": 1, "last_page": 3 } }
商家详情
GET /api/user/merchant/detail/{id}
获取指定商家的详细信息，包括统计数据和最近评价。

路径参数

参数名 类型 必填 说明 示例值
id Integer 是 商家ID 1

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "name": "星辰台球厅", "avatar": "/uploads/merchant/avatar.jpg", "address": "北京市朝阳区建国路88号", "phone": "010-12345678", "email": "merchant@example.com", "rating": 4.8, "description": "专业台球娱乐场所", "business_hours": "08:00-24:00", "facilities": ["停车场", "WiFi", "空调"], "images": ["/uploads/merchant/img1.jpg"], "latitude": 39.9042, "longitude": 116.4074, "table_count": 12, "coach_count": 3, "avg_table_price": 50.00, "recent_reviews": [ { "nickname": "用户A", "avatar": "/uploads/avatar.jpg", "rating": 5, "review": "环境很好，设备新", "create_time": "2024-01-15 14:30:00" } ], "create_time": "2024-01-01 10:00:00" } }
商家台桌列表
GET /api/user/merchant/tables/{id}
获取指定商家的台桌列表。

路径参数

参数名 类型 必填 说明 示例值
id Integer 是 商家ID 1

查询参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
type String 否 台桌类型筛选 snooker

响应示例

{ "code": "0000", "message": "获取成功", "data": { "merchant_info": { "id": 1, "name": "星辰台球厅", "address": "北京市朝阳区建国路88号" }, "list": [ { "id": 1, "name": "1号台", "type": "snooker", "description": "标准斯诺克台桌", "hourly_rate": 50.00, "images": ["/uploads/table/img1.jpg"], "is_available": true } ], "total": 12, "current_page": 1, "last_page": 2 } }
商家教练列表
GET /api/user/merchant/coaches/{id}
获取指定商家的教练列表。

路径参数

参数名 类型 必填 说明 示例值
id Integer 是 商家ID 1

查询参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
specialty String 否 专长筛选 斯诺克

响应示例

{ "code": "0000", "message": "获取成功", "data": { "merchant_info": { "id": 1, "name": "星辰台球厅", "address": "北京市朝阳区建国路88号" }, "list": [ { "id": 1, "nickname": "李教练", "avatar": "/uploads/coach/avatar.jpg", "real_name": "李明", "specialties": ["斯诺克", "九球"], "experience": "5年教学经验", "hourly_rate": 120.00, "rating": 4.8, "order_count": 158, "description": "专业斯诺克教练", "is_available": true } ], "total": 3, "current_page": 1, "last_page": 1 } }

通用订单管理

创建台桌订单
POST /api/common/order/createTableOrder
创建台桌预订订单。

请求参数

参数名 类型 必填 说明 示例值
table_id Integer 是 台桌ID 1
start_time String 是 开始时间 2024-01-01 14:00:00
end_time String 是 结束时间 2024-01-01 16:00:00
contact_phone String 是 联系电话 13800138000
remark String 否 备注 生日聚会

响应示例

{ "code": "0000", "message": "订单创建成功", "data": { "order_id": "TB202401011400001", "amount": 100.00, "status": "pending_payment", "payment_deadline": "2024-01-01 14:15:00" } }
查询订单详情
GET /api/common/order/detail
根据订单ID查询订单详情。

请求参数

参数名 类型 必填 说明 示例值
order_id String 是 订单ID TB202401011400001

响应示例

{ "code": "0000", "message": "获取成功", "data": { "order_id": "TB202401011400001", "type": "table", "status": "paid", "amount": 100.00, "table_info": { "id": 1, "name": "1号台", "type": "snooker" }, "merchant_info": { "id": 1, "name": "星辰台球厅", "address": "北京市朝阳区建国路88号" }, "start_time": "2024-01-01 14:00:00", "end_time": "2024-01-01 16:00:00", "contact_phone": "13800138000", "create_time": "2024-01-01 13:45:00" } }

支付接口

微信小程序支付
POST /api/common/pay/wxapp
小程序内发起微信支付，返回支付参数供小程序调用。

请求参数

参数名 类型 必填 说明 示例值
order_id String 是 订单ID TB202401011400001
openid String 是 用户openid oGZUI0zHgKSH1hsJn6S4n6m9KtUg
amount Number 是 支付金额（分） 10000
description String 是 商品描述 台球桌预约费用

响应示例

{ "code": "0000", "message": "支付参数获取成功", "data": { "appId": "wx1234567890123456", "timeStamp": "1704088800", "nonceStr": "abc123def456", "package": "prepay_id=wx12345678901234567890123456789012", "signType": "RSA", "paySign": "BPvQJHdDYMpZCtXS0aPNOdJsKfKQ2..." } }
微信支付回调
POST /api/common/pay/wxnotify
微信支付成功后的回调接口，用于处理支付结果。

请求参数

微信服务器回调数据，按照微信官方格式。

响应示例

{ "code": "SUCCESS", "message": "成功" }
微信退款
POST /api/common/pay/wxrefund
发起微信退款申请。

请求参数

参数名 类型 必填 说明 示例值
order_id String 是 原订单ID TB202401011400001
refund_amount Number 是 退款金额（分） 10000
refund_reason String 是 退款原因 用户主动取消订单

响应示例

{ "code": "0000", "message": "退款申请成功", "data": { "refund_id": "REF202401011500001", "status": "PROCESSING", "refund_amount": 10000, "create_time": "2024-01-01 15:00:00" } }
创建支付
POST /api/common/pay/create
为订单创建支付请求，支持多种支付方式。

请求参数

参数名 类型 必填 说明 示例值
order_id String 是 订单ID TB202401011400001
pay_type String 是 支付方式：wechat/alipay wechat
return_url String 否 支付成功后跳转地址 https://example.com/success

响应示例

{ "code": "0000", "message": "支付创建成功", "data": { "pay_id": "PAY2024010114001", "pay_type": "wechat", "amount": 100.00, "qr_code": "weixin://wxpay/bizpayurl?pr=...", "expire_time": "2024-01-01 14:15:00" } }
查询支付状态
GET /api/common/pay/query
查询支付状态，用于确认支付是否成功。

请求参数

参数名 类型 必填 说明 示例值
pay_id String 是 支付ID PAY2024010114001

响应示例

{ "code": "0000", "message": "查询成功", "data": { "pay_id": "PAY2024010114001", "order_id": "TB202401011400001", "status": "success", "amount": 100.00, "pay_time": "2024-01-01 14:05:30", "transaction_id": "4200001234567890123456" } }

文件上传接口

图片上传
POST /api/common/upload/image
上传单张图片文件，支持jpg、jpeg、png、gif、webp格式。大于5MB的图片会自动压缩。

请求参数

参数名 类型 必填 说明 示例值
file File 是 图片文件 image.jpg
type String 否 文件类型：avatar/logo/table avatar
图片限制说明

• 单张图片最大10MB

• 支持格式：jpg、jpeg、png、gif、webp

• 大于5MB的图片会自动压缩

• 压缩后仍大于10MB的图片会上传失败

响应示例

{ "code": "0000", "message": "上传成功", "data": { "url": "https://example.com/uploads/images/202401/image_123456.jpg", "size": 1024567, "type": "image/jpeg" } }
批量图片上传
POST /api/common/upload/images
批量上传图片文件，支持最多9张图片同时上传。支持自动压缩功能：大于5MB的图片会自动压缩。

请求参数

参数名 类型 必填 说明 示例值
files[] File[] 是 图片文件数组（最多9张） image1.jpg, image2.jpg
图片限制说明

• 单张图片最大10MB

• 支持格式：jpg、jpeg、png、gif、webp

• 大于5MB的图片会自动压缩

• 压缩后仍大于10MB的图片会被跳过

• 最多同时上传9张图片

请求示例（JavaScript）

const formData = new FormData(); // 添加多个文件 for (let i = 0; i < files.length; i++) { formData.append('files[]', files[i]); } fetch('/api/common/upload/images', { method: 'POST' , body: formData, headers: { 'Authorization' : 'Bearer YOUR_TOKEN' } }) .then(response=> response.json()) .then(data => { if (data.code === '0000') { console.log('上传成功:', data.data.files); } });

响应示例

{ "code": "0000", "message": "上传成功", "data": { "files": [ { "url": "/storage/uploads/images/20240115/abc123.jpg", "filename": "20240115/abc123.jpg", "size": 524288, "type": "image/jpeg" }, { "url": "/storage/uploads/images/20240115/def456.jpg", "filename": "20240115/def456.jpg", "size": 1048576, "type": "image/jpeg" } ], "count": 2 } }

地区数据接口

省市区级联选择接口，支持三级地区数据查询，用于商家注册地址选择、用户地址管理等场景。

  • 省份列表：获取全国所有省份、直辖市、自治区数据
  • 城市列表：根据省份ID获取对应的城市列表
  • 区县列表：根据城市ID获取对应的区县列表
  • 完整地址：根据省市区ID获取完整的地址信息
获取省份列表
GET /api/common/region/provinces
获取全国所有省份、直辖市、自治区列表。

响应示例

{ "code": "0000", "message": "获取省份列表成功", "data": [ { "id": 1, "code": "110000", "name": "北京市", "sort_order": 1 }, { "id": 2, "code": "120000", "name": "天津市", "sort_order": 2 }, { "id": 19, "code": "440000", "name": "广东省", "sort_order": 19 } ] }
获取城市列表
GET /api/common/region/cities
根据省份ID获取对应的城市列表。

请求参数

参数名 类型 必填 说明 示例值
province_id Integer 是 省份ID 19

响应示例

{ "code": "0000", "message": "获取城市列表成功", "data": [ { "id": 1, "code": "440100", "name": "广州市", "province_id": 19, "sort_order": 1 }, { "id": 2, "code": "440300", "name": "深圳市", "province_id": 19, "sort_order": 2 } ] }
获取区县列表
GET /api/common/region/districts
根据城市ID获取对应的区县列表。

请求参数

参数名 类型 必填 说明 示例值
city_id Integer 是 城市ID 1

响应示例

{ "code": "0000", "message": "获取区县列表成功", "data": [ { "id": 1, "code": "440103", "name": "荔湾区", "city_id": 1, "sort_order": 1 }, { "id": 2, "code": "440104", "name": "越秀区", "city_id": 1, "sort_order": 2 } ] }
获取完整地址信息
GET /api/common/region/fullAddress
根据省市区ID获取完整的地址信息，包含各级名称和编码。

请求参数

参数名 类型 必填 说明 示例值
province_id Integer 否 省份ID 19
city_id Integer 否 城市ID 1
district_id Integer 否 区县ID 1

响应示例

{ "code": "0000", "message": "获取地址信息成功", "data": { "province": { "id": 19, "code": "440000", "name": "广东省" }, "city": { "id": 1, "code": "440100", "name": "广州市" }, "district": { "id": 1, "code": "440103", "name": "荔湾区" }, "full_address": "广东省广州市荔湾区" } }
使用说明

• 省市区数据采用国家标准行政区划代码

• 数据按照sort_order字段排序，优先显示重要城市

• 建议前端实现级联选择，用户选择省份后再加载城市，选择城市后再加载区县

• fullAddress接口支持部分参数查询，可只传province_id获取省份信息

• 所有接口都支持CORS跨域请求

前端集成示例
// 获取省份列表 fetch('/api/common/region/provinces') .then(response => response.json()) .then(data => { if (data.code === '0000') { // 填充省份下拉框 populateProvinceSelect(data.data); } }); // 省份选择变化时获取城市 function onProvinceChange(provinceId) { fetch(`/api/common/region/cities?province_id=${provinceId}`) .then(response => response.json()) .then(data => { if (data.code === '0000') { // 填充城市下拉框 populateCitySelect(data.data); // 清空区县下拉框 clearDistrictSelect(); } }); } // 城市选择变化时获取区县 function onCityChange(cityId) { fetch(`/api/common/region/districts?city_id=${cityId}`) .then(response => response.json()) .then(data => { if (data.code === '0000') { // 填充区县下拉框 populateDistrictSelect(data.data); } }); }

系统配置接口

获取系统配置
GET /api/common/config/system
获取系统的基础配置信息。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "app_name": "台球预订系统", "version": "1.0.0", "service_phone": "400-123-4567", "payment_methods": ["wechat", "alipay"], "table_types": [ { "code": "snooker", "name": "斯诺克" }, { "code": "pool", "name": "九球" } ] } }

短信服务接口

短信服务相关接口，基于短信宝API实现，支持验证码发送、业务通知、余额查询等功能。

  • 验证码发送：支持商家注册、通用验证码等场景
  • 业务通知：支持教练预约通知、商家台桌预订通知
  • 防刷机制：同一手机号1分钟内只能发送一次，每日限制5次
  • 模板管理：支持多种短信模板，自动添加签名【星界飞码网络】
  • 错误映射：短信宝错误码映射为统一的API错误码
短信模板说明
merchant_register 商家注册验证码模板 - 参数：{code}
verify_code 通用验证码模板 - 参数：{code}
coach_booking 教练预约通知模板 - 参数：{userName}, {address}, {DateTime}
merchant_booking 商家台桌预订通知模板 - 参数：{merchant_name}, {number}, {from_time}
发送验证码短信
POST /api/sms/sendCode
发送验证码短信，系统自动生成6位数字验证码并发送到指定手机号，支持多种场景模板。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
template String 否 模板类型：merchant_register/verify_code/coach_booking/merchant_booking verify_code
expire Integer 否 过期时间（分钟），默认5分钟 5

响应示例

{ "code": "0000", "message": "验证码发送成功", "data": { "phone": "13800138000", "code": "645231", "expire_minutes": 5, "send_time": "2024-01-15 10:30:00", "template": "verify_code" } }
注意事项

• 验证码由系统自动生成，无需前端传入

• 同一手机号1分钟内只能发送一次验证码

• 每日每个手机号最多发送5次验证码

• 验证码默认有效期为5分钟

• 短信内容会自动添加签名【星界飞码网络】

发送自定义短信
POST /api/sms/send
发送自定义内容的短信，适用于通知类消息。
权限要求

此接口需要管理员权限，请在请求头中包含有效的管理员Token。

请求参数

参数名 类型 必填 说明 示例值
phone String 是 手机号 13800138000
content String 是 短信内容（不包含签名） 【星界飞码网络】用户张三在万达广场预约了您的指导课程，时间为2024-01-15 14:00-16:00，请及时确认。

响应示例

{ "code": "0000", "message": "短信发送成功", "data": { "phone": "13800138000", "content": "【星界飞码网络】用户张三在万达广场预约了您的指导课程，时间为2024-01-15 14:00-16:00，请及时确认。", "send_time": "2024-01-15 10:30:00" } }
查询短信余额
GET /api/sms/balance
查询短信宝账户余额和发送统计信息。
权限要求

此接口需要管理员权限，请在请求头中包含有效的管理员Token。

响应示例

{ "code": "0000", "message": "查询余额成功", "data": { "sent_count": 0, "remaining_count": 491, "query_time": "2024-01-15 10:30:00" } }
发送测试短信
POST /api/sms/sendTest
发送测试短信，用于管理后台测试短信宝配置是否正确。
使用说明

此接口用于测试短信宝账户配置，可以使用自定义的用户名和密码进行测试。

请求参数

参数名 类型 必填 说明 示例值
username String 是 短信宝用户名 xingjiefeima111
password String 是 短信宝密码或ApiKey xingjiefeima123
phone String 是 测试手机号 13800138000
content String 是 短信内容（不包含签名） 这是一条测试短信
signature String 否 短信签名，默认【测试】 【测试】

响应示例

{ "code": "0000", "message": "测试短信发送成功", "data": { "phone": "13800138000", "content": "【测试】这是一条测试短信", "send_time": "2024-01-15 10:30:00" } }
短信服务状态
GET /api/sms/status
获取短信服务配置状态和连通性检测。
权限要求

此接口需要管理员权限，请在请求头中包含有效的管理员Token。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "service_name": "短信宝API服务", "api_version": "v1.0", "status": "active", "connectivity": "正常", "config": { "api_url": "https://api.smsbao.com/sms", "username": "your_username", "signature": "【星界飞码网络】", "rate_limit": 60, "daily_limit": 5 }, "templates": { "merchant_register": "【星界飞码网络】商家注册验证码：{code}，5分钟内有效。若非本人操作请忽略此消息。", "verify_code": "【星界飞码网络】您的验证码是{code}。如非本人操作，请忽略本短信", "coach_booking": "【星界飞码网络】用户{userName}在{address}预约了您的指导课程，时间为{DateTime}，请及时确认。", "merchant_booking": "{merchant_name}您好，有用户预定了{number}号台桌，到店时间为{from_time}，请注意按时接待！" }, "check_time": "2024-01-15 10:30:00" } }

微信小程序登录接口

微信小程序登录相关接口，用于获取用户的openid和session_key。

  • 登录流程：小程序调用wx.login()获取code，然后调用登录接口换取openid
  • 安全性：AppSecret在服务端配置，不会暴露给客户端
  • 缓存机制：access_token自动缓存，避免频繁请求微信服务器
微信登录
POST /api/wechat/login
使用微信授权code换取用户的openid和session_key。

请求参数

参数名 类型 必填 说明 示例值
code String 是 微信登录授权code 013Q7s0w3m2QC93X6H1w3Qc13d1Q7s0l

小程序端调用示例

// 小程序端获取code并登录 wx.login({ success (res) { if (res.code) { // 发送请求到后台 wx.request({ url: 'https://yourdomain.com/api/wechat/login', method: 'POST', data: { code: res.code }, success: function(response) { if (response.data.code === '0000') { // 登录成功，保存openid等信息 console.log('登录成功:', response.data.data.openid); } else { console.error('登录失败:', response.data.message); } } }); } } });

响应示例

{ "code": "0000", "message": "登录成功", "data": { "openid": "oABC123456789xyz", "session_key": "abc123def456ghi789", "unionid": "" }, "timeStamp": 1703145600, "randStr": "abcdef1234567890", "sign": "md5hash", "signType": "MD5" }
注意事项

code有效期为5分钟，且每个code只能使用一次。请确保在获取code后立即调用登录接口。

微信小程序获取手机号接口

微信小程序获取用户手机号相关接口，用于获取用户的真实手机号码。

  • 授权流程：用户点击授权按钮，小程序获取code，服务端调用微信API解密手机号
  • 隐私保护：用户手机号在日志中自动脱敏处理
  • 安全验证：支持水印验证，确保数据来源的真实性
获取手机号
POST /api/wechat/getphonenumber
根据小程序获取手机号授权code解密获取用户真实手机号。

请求参数

参数名 类型 必填 说明 示例值
code String 是 获取手机号授权code e31968a7f94cc5ee25fafc2aef2773f0
openid String 否 用户openid（可选） oABC123456789xyz

小程序端调用示例

// 在小程序页面中添加获取手机号按钮 (wxml) <button open-type="getPhoneNumber" bindgetphonenumber="getPhoneNumber"> 获取手机号 </button> // js文件中的处理函数 Page({ getPhoneNumber: function(e) { console.log(e.detail); // 获取到的信息 if (e.detail.code) { // 发送code到后台 wx.request({ url: 'https://yourdomain.com/api/wechat/getphonenumber', method: 'POST', data: { code: e.detail.code, openid: app.globalData.openid // 可选 }, success: function(response) { if (response.data.code === '0000') { const phoneNumber = response.data.data.phone_number; console.log('用户手机号:', phoneNumber); // 处理获取到的手机号 } else { console.error('获取手机号失败:', response.data.message); } }, fail: function(error) { console.error('请求失败:', error); } }); } else { console.log('用户拒绝授权获取手机号'); } } });

响应示例

{ "code": "0000", "message": "获取手机号成功", "data": { "phone_number": "+8613800138000", "pure_phone_number": "13800138000", "country_code": "86", "watermark": { "timestamp": 1703145600, "appid": "wx1234567890abcdef" } }, "timeStamp": 1703145600, "randStr": "abcdef1234567890", "sign": "md5hash", "signType": "MD5" }

响应字段说明

字段名 类型 说明
phone_number String 用户绑定的手机号（国外手机号会有区号）
pure_phone_number String 没有区号的手机号
country_code String 区号
watermark Object 数据水印，用于验证数据来源
watermark.timestamp Number 用户获取手机号操作的时间戳
watermark.appid String 小程序appid
重要提示

1. code有效期为5分钟，且每个code只能使用一次
2. 需要用户主动授权才能获取手机号
3. 接口有频率限制，请避免频繁调用
4. 务必妥善保管AppSecret，不要在客户端暴露

微信接口错误码
微信小程序接口相关的错误码说明。
错误码 说明 解决方案
0000 成功 -
4001 请求方式错误，请使用POST 检查请求方法
4002 code参数不能为空 检查参数是否正确传递
5001 微信小程序配置不完整 检查AppID和AppSecret配置
5002 获取access_token失败 检查网络连接和微信配置
5003 获取手机号失败 检查code是否有效或已过期
5004 微信API调用失败 检查网络连接
5005 微信登录失败 检查code和微信配置

微信官方错误码

错误码 说明 解决方案
-1 系统繁忙 稍后再试
40029 code无效 检查code是否正确且未过期
45011 API调用太频繁 减缓调用频率
40013 AppID不匹配 检查AppID配置

商家数据统计

营收统计
GET /api/merchant/statistics/revenue
获取商家的营收统计数据，支持按时间维度和业务类型统计。

请求参数

参数名 类型 必填 说明 示例值
start_date String 否 开始日期 2024-01-01
end_date String 否 结束日期 2024-01-31
dimension String 否 统计维度：day/week/month day

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total_revenue": 156800.50, "table_revenue": 89600.00, "coach_revenue": 67200.50, "daily_revenue": [ { "date": "2024-01-01", "table_revenue": 2890.00, "coach_revenue": 2180.50, "total_revenue": 5070.50 } ], "growth_rate": 15.6 } }
预订统计
GET /api/merchant/statistics/booking
获取商家的预订统计数据，包括预订数量、完成率等指标。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total_bookings": 1256, "completed_bookings": 1189, "completion_rate": 94.7, "table_bookings": [ { "table_id": 1, "table_name": "1号台", "booking_count": 156, "usage_rate": 85.2 } ], "hourly_distribution": [ { "hour": 9, "booking_count": 45 } ] } }

用户端意见反馈

提交意见反馈
POST /api/user/feedback/submit
用户提交意见反馈，支持文字内容和图片上传。

请求参数

参数名 类型 必填 说明 示例值
type Integer 是 反馈类型：1=建议 2=投诉 3=Bug反馈 4=其他 1
title String 是 反馈标题，1-100字符 预订功能改进建议
content String 是 反馈内容，1-1000字符 希望能增加提前预订功能
contact_info String 否 联系方式，最多50字符 13800138000
images Array 否 反馈图片URL数组，最多5张 ["https://example.com/img1.jpg"]

响应示例

{ "code": "0000", "message": "反馈提交成功，我们会尽快处理", "data": { "feedback_id": 123 } }
获取我的反馈列表
GET /api/user/feedback/list
获取当前用户的反馈列表，支持分页。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页条数，默认10，最大50 10

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 123, "type": 1, "type_text": "建议", "title": "预订功能改进建议", "content": "希望能增加提前预订功能", "status": 1, "status_text": "处理中", "create_time": "2024-01-01 10:00:00", "admin_reply": "" } ], "total": 5, "page": 1, "limit": 10, "has_more": false } }
获取反馈详情
GET /api/user/feedback/detail
根据反馈ID获取反馈详情。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 反馈ID 123

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 123, "type": 1, "type_text": "建议", "title": "预订功能改进建议", "content": "希望能增加提前预订功能，这样可以更方便用户安排时间。", "images": [ "https://example.com/feedback1.jpg" ], "contact_info": "13800138000", "status": 2, "status_text": "已解决", "admin_reply": "感谢您的建议，我们已将该功能列入开发计划中。", "reply_time": "2024-01-02 15:30:00", "create_time": "2024-01-01 10:00:00", "update_time": "2024-01-02 15:30:00" } }
获取反馈类型列表
GET /api/user/feedback/types
获取所有可用的反馈类型选项。

响应示例

{ "code": "0000", "message": "获取成功", "data": [ { "value": 1, "label": "建议", "description": "对产品功能或服务的改进建议" }, { "value": 2, "label": "投诉", "description": "对产品或服务不满意的投诉" }, { "value": 3, "label": "Bug反馈", "description": "发现的程序错误或异常问题" }, { "value": 4, "label": "其他", "description": "其他类型的反馈" } ] }

用户端教练申请

提交教练申请
POST /api/user/coachapplication/submit
用户提交教练申请，包含个人信息、专业背景和证件材料。

请求参数

参数名 类型 必填 说明 示例值
name String 是 真实姓名 张教练
phone String 是 联系电话 13800138000
age Integer 否 年龄(18-60) 28
gender Integer 否 性别：1=男 2=女 1
experience_years Integer 是 从业年限 5
specialty String 是 专业特长 花式台球、九球技巧
introduction String 是 个人介绍 专业台球教练，有丰富的教学经验...
id_card_front String 是 身份证正面照片URL https://example.com/id_front.jpg
id_card_back String 是 身份证背面照片URL https://example.com/id_back.jpg
education String 否 学历 本科
work_experience String 否 工作经历 2018年-2023年在XX台球俱乐部担任教练...
expected_salary Number 否 期望薪资 8000.00
available_time String 否 可工作时间 周一至周五 18:00-22:00
certificates Array 否 证书图片URL数组(最多5张) ["https://example.com/cert1.jpg", "https://example.com/cert2.jpg"]

响应示例

{ "code": "0000", "message": "申请提交成功，我们将在3个工作日内审核", "data": { "application_id": 123, "status": 0, "status_text": "待审核" } }
获取我的申请列表
GET /api/user/coachapplication/myapplications
获取当前用户的教练申请记录列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码(默认1) 1
limit Integer 否 每页数量(默认10) 10

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 123, "name": "张教练", "phone": "13800138000", "age": 28, "gender": 1, "gender_text": "男", "experience_years": 5, "specialty": "花式台球、九球技巧", "education": "本科", "expected_salary": 8000.00, "status": 0, "status_text": "待审核", "reject_reason": "", "admin_name": "", "process_time": null, "create_time": "2024-01-01 10:00:00" } ], "total": 1, "current_page": 1, "last_page": 1 } }
获取申请详情
GET /api/user/coachapplication/detail
根据申请ID获取详细的申请信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 申请ID 123

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 123, "name": "张教练", "phone": "13800138000", "age": 28, "gender": 1, "gender_text": "男", "experience_years": 5, "specialty": "花式台球、九球技巧", "introduction": "专业台球教练，有丰富的教学经验，擅长花式台球和九球技巧教学。", "certificates": [ "https://example.com/cert1.jpg", "https://example.com/cert2.jpg" ], "id_card_front": "https://example.com/id_front.jpg", "id_card_back": "https://example.com/id_back.jpg", "education": "本科", "work_experience": "2018年-2023年在XX台球俱乐部担任教练", "expected_salary": 8000.00, "available_time": "周一至周五 18:00-22:00", "status": 0, "status_text": "待审核", "reject_reason": "", "admin_name": "", "process_time": null, "create_time": "2024-01-01 10:00:00" } }
取消申请
POST /api/user/coachapplication/cancel
取消待审核状态的教练申请。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 申请ID 123

响应示例

{ "code": "0000", "message": "申请已取消", "data": [] }

用户端教练相关

教练列表
GET /api/user/coach/list
获取教练列表，支持多种筛选和排序条件。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
keyword String 否 搜索关键词 李教练
specialty String 否 专长筛选 斯诺克
merchant_id Integer 否 商家ID筛选 1
sort String 否 排序方式：rating/experience/price_asc/price_desc/order_count rating
min_rating Float 否 最低评分筛选 4.0
max_price Float 否 最高价格筛选 200.00

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 1, "nickname": "李教练", "avatar": "/uploads/coach/avatar.jpg", "real_name": "李明", "specialties": ["斯诺克", "九球"], "experience": "5年教学经验", "hourly_rate": 120.00, "rating": 4.8, "order_count": 158, "description": "专业斯诺克教练", "merchant_info": { "id": 1, "name": "星辰台球厅", "address": "北京市朝阳区建国路88号" }, "available_days": ["1", "2", "3", "4", "5"], "work_time": { "start": "09:00:00", "end": "22:00:00" }, "is_available": true } ], "total": 15, "current_page": 1, "last_page": 2 } }
教练详情
GET /api/user/coach/detail/{id}
获取指定教练的详细信息，包括评分统计和评价信息。

路径参数

参数名 类型 必填 说明 示例值
id Integer 是 教练ID 1

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "nickname": "李教练", "avatar": "/uploads/coach/avatar.jpg", "real_name": "李明", "specialties": ["斯诺克", "九球"], "experience": "5年教学经验", "hourly_rate": 120.00, "rating": 4.8, "order_count": 158, "description": "专业斯诺克教练，5年教学经验", "certificates": [ { "name": "台球教练资格证", "image": "/uploads/cert.jpg" } ], "available_days": ["1", "2", "3", "4", "5"], "work_time": { "start": "09:00:00", "end": "22:00:00" }, "merchant_info": { "id": 1, "name": "星辰台球厅", "address": "北京市朝阳区建国路88号", "phone": "010-12345678" }, "rating_stats": { "total_reviews": 156, "avg_rating": 4.8, "five_star": 120, "four_star": 30, "three_star": 5, "two_star": 1, "one_star": 0 }, "recent_reviews": [ { "nickname": "用户A", "avatar": "/uploads/avatar.jpg", "rating": 5, "review": "李教练很专业，技术过硬", "create_time": "2024-01-15 14:30:00" } ], "is_available": true, "create_time": "2024-01-01 10:00:00" } }
预约教练
POST /api/user/coach/book
预约指定教练的授课服务。
认证要求

此接口需要用户登录，请在请求头中包含有效的Token。

请求参数

参数名 类型 必填 说明 示例值
coach_id Integer 是 教练ID 1
booking_date String 是 预约日期（YYYY-MM-DD） 2024-01-20
start_time String 是 开始时间（HH:mm:ss） 14:00:00
duration Float 是 时长（小时） 2.0
contact_phone String 是 联系电话 13800138000
notes String 否 备注信息 希望重点练习技巧动作

响应示例

{ "code": "0000", "message": "预约成功，等待教练确认", "data": { "booking_id": 123, "total_amount": 240.00, "status": "pending" } }
取消预约
POST /api/user/coach/cancelbooking
取消已预约的教练服务（需提前2小时）。
认证要求

此接口需要用户登录，请在请求头中包含有效的Token。

请求参数

参数名 类型 必填 说明 示例值
booking_id Integer 是 预约ID 123
reason String 否 取消原因 临时有事

响应示例

{ "code": "0000", "message": "取消成功", "data": [] }
评价教练
POST /api/user/coach/evaluate
对已完成的教练服务进行评价。
认证要求

此接口需要用户登录，请在请求头中包含有效的Token。

请求参数

参数名 类型 必填 说明 示例值
booking_id Integer 是 预约ID 123
rating Integer 是 评分（1-5星） 5
review String 否 评价内容 教练很专业，技术过硬

响应示例

{ "code": "0000", "message": "评价成功", "data": [] }

用户端用户信息相关

获取用户信息
GET /api/user/user/info
获取当前登录用户的详细信息。
认证要求

此接口需要用户登录，请在请求头中包含有效的Token。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "username": "张三", "avatar": "https://example.com/avatar.jpg", "age": 25, "gender": "男", "phone": "15812345678", "email": "zhangsan@example.com", "balance": 100.00, "is_verified": 1, "level": "初级" } }
更新用户资料
POST /api/user/user/update
更新用户个人资料信息。
认证要求

此接口需要用户登录，请在请求头中包含有效的Token。

请求参数

参数名 类型 必填 说明 示例值
username String 否 用户名 张三
avatar String 否 头像地址 https://example.com/avatar.jpg
age Integer 否 年龄 25
phone String 否 手机号 15812345678
email String 否 邮箱 user@example.com

响应示例

{ "code": "0000", "message": "更新成功", "data": [] }
获取预约记录
GET /api/user/user/bookings
获取当前用户的预约记录列表。
认证要求

此接口需要用户登录，请在请求头中包含有效的Token。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
status String 否 状态筛选 completed

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 1, "booking_date": "2025-01-15", "start_time": "10:00:00", "duration": 2.0, "total_amount": 200.00, "status": "completed", "coach_info": { "id": 1, "nickname": "李教练" } } ], "total": 15 } }

商家端优惠券管理

优惠券列表
GET /api/merchant/coupon/list
获取商家的优惠券列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10
status Integer 否 状态筛选：0-禁用，1-启用 1
keyword String 否 搜索关键词（优惠券名称） 新用户专享

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total": 12, "per_page": 10, "current_page": 1, "last_page": 2, "data": [ { "id": 1, "name": "新用户专享", "type": 1, "type_text": "满减券", "discount_amount": 20.00, "min_amount": 100.00, "valid_days": 30, "status": 1, "status_text": "启用", "create_time": "2024-01-15 10:00:00" } ] } }
优惠券详情
GET /api/merchant/coupon/detail
获取优惠券详细信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 优惠券ID 1

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 1, "name": "新用户专享", "type": 1, "type_text": "满减券", "discount_amount": 20.00, "min_amount": 100.00, "valid_days": 30, "description": "新用户首次下单满100元减20元", "start_time": "2024-01-15 00:00:00", "end_time": "2024-12-31 23:59:59", "status": 1, "status_text": "启用", "create_time": "2024-01-15 10:00:00", "update_time": "2024-01-15 10:00:00" } }
更新优惠券信息
POST /api/merchant/coupon/update
更新优惠券信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 优惠券ID 1
name String 否 优惠券名称 新用户专享
type Integer 否 优惠券类型：1-满减券，2-折扣券 1
discount_amount Decimal 否 优惠金额（满减券）或折扣率（折扣券） 20.00
min_amount Decimal 否 最低消费金额 100.00
valid_days Integer 否 有效天数 30
description String 否 优惠券描述 新用户首次下单满100元减20元
start_time String 否 开始时间 2024-01-15 00:00:00
end_time String 否 结束时间 2024-12-31 23:59:59
status Integer 否 状态：0-禁用，1-启用 1

响应示例

{ "code": "0000", "message": "更新成功", "data": { "id": 1, "name": "新用户专享", "type": 1, "discount_amount": 20.00, "min_amount": 100.00, "valid_days": 30, "description": "新用户首次下单满100元减20元", "start_time": "2024-01-15 00:00:00", "end_time": "2024-12-31 23:59:59", "status": 1, "update_time": "2024-01-15 11:30:00" } }
删除优惠券
POST /api/merchant/coupon/delete
删除优惠券。如果优惠券已被用户领取且未使用，将无法删除。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 优惠券ID 1

响应示例

{ "code": "0000", "message": "删除成功", "data": [] }

用户端优惠券

可领取优惠券列表
GET /api/user/coupon/available
获取用户可以领取的优惠券列表。

请求参数

参数名 类型 必填 说明 示例值
user_id Integer 是 用户ID 1
merchant_id Integer 否 商家ID筛选 1
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认10 10

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 1, "name": "满100减20优惠券", "description_text": "满100元减20元", "can_receive": true, "merchant": { "id": 1, "name": "星辰台球俱乐部" } } ], "total": 8 } }
领取优惠券
POST /api/user/coupon/receive
用户领取优惠券。

请求参数

参数名 类型 必填 说明 示例值
user_id Integer 是 用户ID 1
coupon_id Integer 是 优惠券ID 1

响应示例

{ "code": "0000", "message": "领取成功", "data": { "user_coupon_id": 123, "coupon_code": "CP25011512345678" } }
我的优惠券
GET /api/user/coupon/myCoupons
获取用户已领取的优惠券列表。

请求参数

参数名 类型 必填 说明 示例值
user_id Integer 是 用户ID 1
status Integer 否 状态：0=未使用 1=已使用 2=已过期 0

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 123, "coupon_code": "CP25011512345678", "status": 0, "can_use": true, "coupon": { "name": "满100减20优惠券", "description_text": "满100元减20元" } } ] } }
使用优惠券
POST /api/user/coupon/use
在订单支付时使用优惠券进行抵扣。

请求参数

参数名 类型 必填 说明 示例值
user_id Integer 是 用户ID 1
user_coupon_id Integer 是 用户优惠券ID 123
order_id Integer 是 订单ID 456
amount Decimal 是 订单金额 150.00

响应示例

{ "code": "0000", "message": "使用成功", "data": { "original_amount": 150.00, "discount_amount": 20.00, "final_amount": 130.00 } }

用户端台桌相关

台桌列表
GET /api/user/table/list
获取台桌列表，支持多种筛选条件。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 1, "name": "1号台", "table_type": "snooker", "hourly_rate": 80.00, "is_available": true } ], "total": 15 } }
预约台桌
POST /api/user/table/book
预约指定台桌的使用时间。

响应示例

{ "code": "0000", "message": "预约成功", "data": { "booking_id": 123, "order_no": "TB2024011512345678" } }

支付中心接口

本系统封装了小诺支付平台的接口，为客户端（小程序、APP等）提供统一的支付接口。

客户端只需调用本系统的接口即可完成支付，无需直接对接第三方支付平台。

特点：

  • 统一的接口规范，便于客户端开发
  • 支持微信支付、支付宝支付
  • 自动处理订单状态和支付记录
  • 支持多种支付场景：H5、小程序、APP等
  • 完整的退款功能
创建支付订单（统一下单）
POST /api/thirdpay/create
创建支付订单，支持多种支付方式和场景。根据不同的method参数返回相应的支付参数。

请求参数

参数名 类型 必填 说明 示例值
order_id Integer 是 订单ID 123
pay_type String 是 支付类型：wechat(微信) | alipay(支付宝) wechat
method String 否 接口类型：web | jump | jsapi | app | scan | applet jsapi
device String 否 设备类型：pc | mobile | qq | wechat | alipay mobile
openid String 否 用户openid（JSAPI支付必传） oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
appid String 否 公众号AppId（JSAPI支付必传） wx8888888888888888
auth_code String 否 付款码（付款码支付必传） 120061098828009406
return_url String 否 支付成功返回地址 https://example.com/success

method参数说明

值 说明 返回类型
web 通用网页支付（自动判断返回类型） 跳转url/二维码/小程序url
jump 跳转支付 仅返回跳转url
jsapi JSAPI支付（小程序内支付） 返回JSAPI参数
app APP支付 APP支付参数或拉起小程序参数
scan 付款码支付 支付成功返回订单信息
applet 小程序支付 小程序插件参数或跳转参数

响应示例（JSAPI支付）

{ "code": "0000", "message": "创建支付订单成功", "data": { "payment_no": "PAY20250115123456789012", "trade_no": "20250115143529123", "pay_type": "jsapi", "pay_info": "{\"appId\":\"wx8888888888888888\",\"timeStamp\":\"1737005729\",\"nonceStr\":\"e61463f8efa94090b1f366cccfbbb444\",\"package\":\"prepay_id=wx201501151435298888888888\",\"signType\":\"RSA\",\"paySign\":\"oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\"}", "amount": "88.00" } }

响应示例（二维码支付）

{ "code": "0000", "message": "创建支付订单成功", "data": { "payment_no": "PAY20250115123456789012", "trade_no": "20250115143529123", "pay_type": "qrcode", "pay_info": "weixin://wxpay/bizpayurl?pr=04IPMKM", "amount": "88.00" } }
页面跳转支付
POST /api/thirdpay/submit
获取支付跳转链接，适用于H5页面直接跳转支付。

请求参数

参数名 类型 必填 说明 示例值
order_id Integer 是 订单ID 123
pay_type String 是 支付类型：wechat | alipay wechat
return_url String 否 支付成功返回地址 https://example.com/success

响应示例

{ "code": "0000", "message": "获取支付链接成功", "data": { "payment_no": "PAY20250115123456789012", "pay_url": "https://xnoo.cn/api/pay/submit?pid=1495&type=wxpay&out_trade_no=PAY20250115123456789012...", "amount": "88.00" } }
查询支付状态
POST /api/thirdpay/querystatus
查询支付订单状态。如果订单还在处理中，会自动查询第三方支付平台的最新状态。

请求参数

参数名 类型 必填 说明 示例值
order_no String 是 支付单号 PAY20250115123456789012

响应示例

{ "code": "0000", "message": "查询成功", "data": { "payment_no": "PAY20250115123456789012", "order_id": 123, "order_no": "TB2025011512345678", "status": 2, "status_text": "支付成功", "amount": "88.00", "pay_type": 4, "pay_type_text": "第三方微信支付", "pay_time": "2025-01-15 14:37:24", "create_time": "2025-01-15 14:35:29" } }

支付状态说明

状态值 说明
1 待支付
2 支付成功
3 支付失败
4 已退款
申请退款
POST /api/thirdpay/refund
对已支付成功的订单申请退款。退款将原路返回到用户的支付账户。

请求参数

参数名 类型 必填 说明 示例值
payment_no String 是 支付单号 PAY20250115123456789012
refund_amount Decimal 是 退款金额（不能大于支付金额） 88.00
refund_reason String 否 退款原因（最多200字） 用户申请退款

响应示例

{ "code": "0000", "message": "退款申请成功", "data": { "refund_no": "20250115143920001", "out_refund_no": "RF20250115143920123456", "refund_amount": "88.00" } }
查询退款状态
GET /api/thirdpay/refundquery
查询退款申请的处理状态。

请求参数

参数名 类型 必填 说明 示例值
out_refund_no String 是 商户退款单号 RF20250115143920123456

响应示例

{ "code": "0000", "message": "查询成功", "data": { "refund_no": "20250115143920001", "out_refund_no": "RF20250115143920123456", "payment_no": "PAY20250115123456789012", "order_no": "TB2025011512345678", "refund_amount": "88.00", "refund_reason": "用户申请退款", "status": 1, "status_text": "退款成功", "create_time": "2025-01-15 14:39:20" } }
获取支付方式列表
GET /api/thirdpay/types
获取系统支持的支付方式列表。

响应示例

{ "code": "0000", "message": "获取成功", "data": [ { "type": "wechat", "name": "微信支付", "icon": "/static/images/wechat_pay.png", "enabled": true }, { "type": "alipay", "name": "支付宝", "icon": "/static/images/alipay.png", "enabled": true } ] }
支付回调通知
GET /api/thirdpay/notify

注意：此接口由第三方支付平台自动调用，客户端无需调用。

支付成功后，系统会自动：

  • 更新支付记录状态为"支付成功"
  • 更新订单状态为"已支付"
  • 记录交易流水
  • 更新商户余额

退款管理接口

申请退款
POST /api/refund/apply
用户申请订单退款。

请求参数

参数名 类型 必填 说明 示例值
order_id Integer 是 订单ID 123
order_type String 是 订单类型：coach_booking coach_booking
refund_reason String 是 退款原因 临时有事无法上课

响应示例

{ "code": "0000", "message": "退款申请提交成功，等待审核", "data": { "refund_id": 456 } }
退款申请列表
GET /api/refund/list
获取用户的退款申请列表。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码 1
limit Integer 否 每页数量 20
status String 否 退款状态：pending|approved|rejected|processing|completed|failed pending

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 456, "order_id": 123, "refund_amount": 88.00, "refund_reason": "临时有事无法上课", "status": "pending", "status_text": "待审核", "create_time": "2025-01-15 10:30:00" } ], "total": 1, "page": 1, "limit": 20 } }
管理员审核退款
POST /api/refund/admin/audit
管理员审核退款申请。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 退款申请ID 456
action String 是 操作：approve|reject approve
admin_remark String 否 管理员备注 同意退款

响应示例

{ "code": "0000", "message": "退款已同意，正在处理中", "data": {} }

财务管理接口

交易流水列表
GET /api/finance/transactions
获取交易流水列表。

请求参数

参数名 类型 必填 说明 示例值
merchant_id Integer 否 商户ID（商户端必填） 123
user_id Integer 否 用户ID（用户端必填） 456
transaction_type String 否 交易类型：payment|refund|commission|withdraw payment
start_time String 否 开始时间 2025-01-01
end_time String 否 结束时间 2025-01-31

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 789, "transaction_no": "TXN20250115123456", "transaction_type": "payment", "transaction_type_text": "支付", "amount": 88.00, "commission_amount": 8.80, "merchant_amount": 79.20, "status": "success", "create_time": "2025-01-15 10:30:00" } ] } }
商户余额查询
GET /api/finance/balance
查询商户余额信息。

请求参数

参数名 类型 必填 说明 示例值
merchant_id Integer 是 商户ID 123

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total_income": 5000.00, "commission_deducted": 500.00, "available_balance": 3500.00, "frozen_balance": 500.00, "withdrawn_amount": 500.00 } }
申请提现
POST /api/finance/withdraw/apply
商户申请提现。

请求参数

参数名 类型 必填 说明 示例值
merchant_id Integer 是 商户ID 123
withdraw_amount Decimal 是 提现金额 500.00
bank_name String 是 银行名称 中国工商银行
bank_account String 是 银行账号 6222xxxxxxxxxxxxxxxx
account_name String 是 账户名称 张三

响应示例

{ "code": "0000", "message": "提现申请提交成功", "data": { "withdraw_id": 789 } }
提现申请列表
GET /api/finance/withdraw/list
获取提现申请列表。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 789, "withdraw_amount": 500.00, "bank_name": "中国工商银行", "bank_account": "6222****1234", "status": "pending", "status_text": "待审核", "create_time": "2025-01-15 10:30:00" } ] } }
结算统计
GET /api/finance/settlement/stats
获取商户的结算统计数据。

请求参数

参数名 类型 必填 说明 示例值
merchant_id Integer 是 商户ID 123

响应示例

{ "code": "0000", "message": "获取成功", "data": { "total_income": 5000.00, "total_commission": 500.00, "net_income": 4500.00, "total_refund": 100.00, "total_withdraw": 1000.00, "month_income": 800.00, "today_income": 200.00 } }

订单管理接口

订单列表
GET /api/order/list
获取用户的订单列表，支持分页和筛选。

请求参数

参数名 类型 必填 说明 示例值
page Integer 否 页码，默认1 1
limit Integer 否 每页数量，默认20 20
status String 否 订单状态筛选 completed
payment_status String 否 支付状态筛选 paid

响应示例

{ "code": "0000", "message": "获取成功", "data": { "list": [ { "id": 123, "booking_date": "2025-01-20", "start_time": "14:00:00", "duration": 2, "total_amount": 200.00, "status": "confirmed", "status_text": "已确认", "payment_status": "paid", "coach_name": "张教练", "merchant_name": "XXX台球俱乐部", "can_refund": true, "can_cancel": false } ], "total": 10 } }
订单详情
GET /api/order/detail
获取指定订单的详细信息。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 订单ID 123

响应示例

{ "code": "0000", "message": "获取成功", "data": { "id": 123, "booking_date": "2025-01-20", "start_time": "14:00:00", "end_time": "16:00:00", "duration": 2, "hourly_rate": 100.00, "total_amount": 200.00, "contact_phone": "13800138000", "coach": { "id": 456, "nickname": "张教练", "avatar": "/uploads/avatar.jpg" }, "payment": { "payment_no": "PAY20250115123456", "payment_type": "wechat", "payment_time": "2025-01-15 10:30:00" }, "can_refund": true } }
申请退款
POST /api/order/applyrefund
用户申请订单退款。

请求参数

参数名 类型 必填 说明 示例值
order_id Integer 是 订单ID 123
refund_reason String 是 退款原因 临时有事，无法上课

响应示例

{ "code": "0000", "message": "退款申请提交成功，等待审核", "data": { "refund_id": 789 } }
取消订单
POST /api/order/cancel
用户取消订单。

请求参数

参数名 类型 必填 说明 示例值
order_id Integer 是 订单ID 123
cancel_reason String 否 取消原因 时间冲突

响应示例

{ "code": "0000", "message": "订单已取消", "data": {} }

管理员接口

退款审核
POST /api/admin/refund/audit
管理员审核退款申请。

请求参数

参数名 类型 必填 说明 示例值
id Integer 是 退款申请ID 789
action String 是 操作：approve-同意，reject-拒绝 approve
admin_remark String 否 管理员备注 符合退款条件

响应示例

{ "code": "0000", "message": "退款已批准并处理完成", "data": {} }
提现审核
POST /api/admin/withdraw/audit
管理员审核提现申请。

响应示例

{ "code": "0000", "message": "提现申请已审核", "data": {} }
管理统计
GET /api/admin/refund/statistics
获取退款统计数据。

响应示例

{ "code": "0000", "message": "获取成功", "data": { "today_refund": 100.00, "month_refund": 1500.00, "pending_count": 5, "total_refund": 10000.00 } }

系统配置接口

配置列表
GET /api/admin/config/list
获取所有系统配置。

响应示例

{ "code": "0000", "message": "获取成功", "data": [ { "key": "commission_rate", "value": "0.10", "desc": "系统佣金率", "type": "float" } ] }
更新配置
POST /api/admin/config/update
批量更新系统配置。

请求参数

参数名 类型 必填 说明 示例值
configs Array 是 配置数组 见下方示例

请求示例

{ "configs": [ { "key": "commission_rate", "value": "0.15", "desc": "系统佣金率", "type": "float" } ] }
初始化配置
POST /api/admin/config/initDefault
初始化默认系统配置。

响应示例

{ "code": "0000", "message": "成功初始化 7 项默认配置", "data": {} }

更新日志

记录系统API接口的重要更新和功能变更。

v2.1.0 - 商家审核系统升级
新增 2024年1月
全面升级商家认证和审核系统，增强用户体验和管理效率。
新增功能
智能重新提交 被驳回的商家申请可以重新提交，系统自动更新现有记录
审核状态管理 新增verify_status字段，支持待审核(0)、通过(1)、驳回(2)三种状态
驳回原因记录 新增verify_remark字段，记录审核驳回的具体原因
文件上传支持 支持商家头像(avatar)和店铺介绍图片(shop_images)上传
验证码登录 新增商家验证码登录接口，支持多种登录方式
接口变更
/api/merchant/auth/register 增加智能重新提交逻辑，支持avatar和shop_images参数
/api/merchant/auth/login 增加审核状态检查，未通过审核无法登录
/api/merchant/auth/loginWithCode 新增验证码登录接口，同样包含审核状态检查
/api/merchant/auth/info 返回数据增加verify_status、verify_remark、avatar、shop_images字段
数据库变更
merchants表 新增verify_status、verify_remark、avatar、shop_images四个字段
业务逻辑优化
注册防重复 同一手机号在待审核或已通过状态下不允许重复注册
登录权限控制 只有审核通过的商家才能正常登录系统
错误信息优化 提供更详细的错误提示和状态说明
v2.0.0 - 基础系统
基础 2023年12月
台球预订系统基础功能实现。
核心功能
用户系统 用户注册、登录、信息管理
商家系统 商家注册、台桌管理、教练管理
教练系统 教练认证、订单管理、收益统计
预订系统 台桌预订、教练预约、支付结算
通用功能 文件上传、短信服务、地区数据