# 麻将组局预约小程序 - 业务逻辑详解文档
## 目录
1. [项目概述](#1-项目概述)
2. [系统架构](#2-系统架构)
3. [**界面原型图与交互说明**](#3-界面原型图与交互说明) ⭐ 新增
4. [核心业务模块](#4-核心业务模块)
5. [核心业务流程图](#5-核心业务流程图)
6. [数据模型](#6-数据模型)
7. [API接口详解](#7-api接口详解)
8. [业务规则汇总](#8-业务规则汇总)
9. [状态机定义](#9-状态机定义)
---
## 1. 项目概述
### 1.1 产品定位
这是一个**麻将组局预约小程序**，帮助麻将爱好者在线上发起、加入麻将局，线下到店进行游戏。小程序提供了完整的预约流程管理，包括房间选择、预约发起、参与管理、签到评价等功能。
### 1.2 技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| 前端 | UniApp + Vue 3 | 支持微信小程序、H5、APP多端发布 |
| 后端 | .NET Core 6.0+ | RESTful API |
| ORM | SqlSugar | 数据库访问层 |
| 数据库 | Microsoft SQL Server | 数据持久化 |
| 支付 | 微信支付 | 鸽子费（押金）支付 |
### 1.3 核心功能清单
```
┌─────────────────────────────────────────────────────────┐
│ 麻将组局预约系统 │
├─────────────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 首页 │ │ 预约 │ │ 个人中心│ │ 消息 │ │
│ │ 预约列表│ │ 房间选择│ │ 我的预约│ │ 站内信 │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
├─────────────────────────────────────────────────────────┤
│ 核心业务： │
│ • 发起预约 • 加入预约 • 取消预约 │
│ • 预约签到 • 牌友评价 • 信誉管理 │
│ • 鸽子费支付 • 退款处理 • 收益提现 │
└─────────────────────────────────────────────────────────┘
```
---
## 2. 系统架构
### 2.1 前端架构
```
uniapp/mahjong_group/
├── pages/ # 页面目录
│ ├── index/
│ │ └── index.vue # 首页 - 预约列表
│ ├── appointment/
│ │ ├── book-room-page.vue # 房间选择页（Tab页）
│ │ └── appointment-page.vue # 预约表单页
│ └── me/
│ ├── me-page.vue # 个人中心
│ ├── appointment-record-page.vue # 预约记录
│ ├── my-earnings-page.vue # 我的收益
│ └── my-message-page.vue # 消息中心
├── components/ # 组件目录
│ ├── index/
│ │ └── MahjongCard.vue # 麻将预约卡片（九宫格）
│ └── com/
│ ├── index/
│ │ └── ReservationPopup.vue # 预约详情弹窗
│ └── page/
│ ├── container-base.vue # 基础容器（含签到、评价弹窗）
│ └── qiandao-popup.vue # 签到弹窗
└── common/
├── server/
│ └── interface/ # API接口定义
│ ├── sq.js # 预约相关接口
│ ├── user.js # 用户相关接口
│ ├── earnings.js # 收益相关接口
│ └── message.js # 消息相关接口
└── system/
├── request.js # 请求封装（含签名）
└── cacheService.js # 缓存服务
```
### 2.2 后端架构
```
server/CoreCms.Net.Web.WebApi/
└── Controllers/
└── SQController.cs # 预约核心控制器（全部预约相关API）
├── GetReservationList # 首页预约列表
├── AddSQReservation # 创建预约
├── JoinReservation # 加入预约
├── CancelReservation # 取消预约
├── CheckInReservation # 签到
├── GetEvaluateServices # 获取评价
├── AddEvaluateServices # 添加评价
├── GetMessageList # 消息列表
├── GetEarningsSummary # 收益统计
└── ApplyWithdraw # 申请提现
```
### 2.3 系统架构图
```mermaid
graph TB
subgraph 客户端
A[微信小程序] --> B[UniApp]
C[H5网页] --> B
D[APP] --> B
end
subgraph 前端层
B --> E[Vue 3 组件]
E --> F[API接口层]
F --> G[请求封装/签名]
end
subgraph 后端层
G --> H[.NET Core WebAPI]
H --> I[SQController]
I --> J[Services服务层]
J --> K[SqlSugar ORM]
end
subgraph 数据层
K --> L[(SQL Server)]
end
subgraph 第三方服务
H --> M[微信支付]
H --> N[微信登录]
end
```
---
## 3. 界面原型图与交互说明
本章节展示小程序的主要界面原型图，帮助理解各页面的布局和交互逻辑。**⭐ 标记的区域为重点功能区域**。
### 3.1 整体页面结构
```
┌─────────────────────────────────────────────────────────────┐
│ 小程序整体结构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 首页 │ │ 预约 │ │ 我的 │ │
│ │ index.vue │ │book-room │ │ me-page │ │
│ │ │ │ -page.vue │ │ .vue │ │
│ │ 预约列表 │ │ 房间选择 │ │ 个人中心 │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ v v v │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ReservationP │ │appointment │ │appointment │ │
│ │ opup.vue │ │ -page.vue │ │-record.vue │ │
│ │ 预约详情弹窗│ │ 预约表单 │ │ 预约记录 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
│ │ │
└────────────────┼────────────────┘
v
┌─────────────────────────────┐
│ TabBar │
│ [首页] [预约] [我的] │
└─────────────────────────────┘
```
---
### 3.2 首页 - 预约列表页
**文件**: `pages/index/index.vue`
```
┌─────────────────────────────────────────┐
│ ▓▓▓▓▓▓▓▓▓▓ 状态栏 ▓▓▓▓▓▓▓▓▓▓ │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ ╔═══════════════════════════════╗ │ │◄── ⭐ Banner轮播图
│ │ ║ 🀄 麻将棋牌馆广告 ║ │ │ (可配置)
│ │ ║ 点击查看详情 ║ │ │
│ │ ╚═══════════════════════════════╝ │ │
│ │ ○ ● ○ │ │◄── 轮播指示器
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ 📢 公告：本店营业时间 9:00-23:00 │ │◄── 滚动公告栏
│ └─────────────────────────────────────┘ │
│ │
│ ┌───────────────┐ ┌───────────────┐ │
│ │ ┌───────────┐ │ │ ┌───────────┐ │ │
│ │ │ 组局中... │ │ │ │ 待开始 │ │ │◄── 状态标签
│ │ ├───────────┤ │ │ ├───────────┤ │ │
│ │ │ 👤 │ │ │ │ 👤 👤 │ │ │
│ │ │ 👤 👤 │ │ │ │ 🀄 │ │ │◄── ⭐ 九宫格麻将桌
│ │ │ 🀄 │ │ │ │ 👤 👤 │ │ │ (显示已加入玩家)
│ │ │ ➕ ➕ │ │ │ │ 👤 │ │ │
│ │ │ ➕ │ │ │ ├───────────┤ │ │
│ │ ├───────────┤ │ │ │休闲局 │ │ │
│ │ │休闲娱乐局 │ │ │ │12/20 周五 │ │ │◄── 预约信息
│ │ │12/18 周三 │ │ │ │20:00-24:00│ │ │
│ │ │18:00-22:00│ │ │ │304包厢 │ │ │
│ │ │302包厢 │ │ │ │血战 禁烟 │ │ │
│ │ │血流成河 │ │ │ │信誉≧4.0 │ │ │
│ │ └───────────┘ │ └───────────────┘ │
│ └───────────────┘ │
│ │
│ ┌───────────────┐ ┌───────────────┐ │◄── 更多预约卡片...
│ │ ... │ │ ... │ │
│ └───────────────┘ └───────────────┘ │
│ │
│ ┌───┐ │
│ │ 🔘│ │◄── 悬浮球
│ └───┘ │
├─────────────────────────────────────────┤
│ [🏠首页] [📅预约] [👤我的] │◄── TabBar
└─────────────────────────────────────────┘
```
#### 重点说明：
| 区域 | 重点级别 | 说明 |
|------|---------|------|
| ⭐ 九宫格麻将桌 | 高 | **核心展示区域**，直观显示当前已加入人数，空位显示➕，已加入显示头像 |
| ⭐ Banner轮播 | 中 | 后台可配置，用于活动推广 |
| 状态标签 | 高 | 组局中/待开始/进行中/已结束，一眼看出预约状态 |
| 预约信息 | 中 | 关键信息：时间、房间、玩法、限制条件 |
---
### 3.3 麻将卡片组件详解
**文件**: `components/index/MahjongCard.vue`
```
┌─────────────────────────────────────────────────────────────────┐
│ 九宫格布局说明 (4人局) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 位置1 (上) │
│ 👤 ← 第3个加入的玩家 │
│ │
│ 位置2 🀄 位置3 │
│ 👤 (麻将桌logo) 👤 │
│ ↑ ↑ │
│ 第1个加入 第2个加入 │
│ (通常是发起者) 的玩家 │
│ │
│ 位置4 (下) │
│ 👤 ← 第4个加入的玩家 │
│ │
├─────────────────────────────────────────────────────────────────┤
│ 不同人数局的布局： │
│ │
│ 2人局: 3人局: 4人局(标准): │
│ 👤 👤 │
│ 👤 👤 👤 👤 👤 🀄 👤 │
│ 👤 │
└─────────────────────────────────────────────────────────────────┘
```
---
### 3.4 预约详情弹窗
**文件**: `components/com/index/ReservationPopup.vue`
点击首页的预约卡片后弹出：
```
┌─────────────────────────────────────────────────────────────┐
│ 预约信息 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 发起者 👤 张三 │ │◄── ⭐ 发起者信息
│ │ │ │
│ │ 参与者 👤李四 👤王五 [黑名单]👤赵六 │ │◄── ⭐ 参与者列表
│ │ ↑ │ │ (可显示黑名单标记)
│ │ 红色标记 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 开始时间 2025-12-20 18:00 │ │
│ │ 结束时间 2025-12-20 22:00 │ │◄── 时间信息
│ │ 合计：4小时 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 房间号： 304包厢-大包 │ │
│ │ 人数： 4人 │ │◄── ⭐ 预约详情
│ │ 玩法类型： 血战到底 │ │
│ │ 具体规则： 2番起胡，3倍封顶 │ │
│ │ 补充信息： 新手勿扰 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 是否禁烟： 禁烟 │ │
│ │ 性别： 男 │ │◄── ⭐ 参与限制条件
│ │ 年龄范围： 25岁 ~ 45岁 │ │ (重点检查项)
│ │ 信誉： ≧4.0 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 鸽子费： 10元 │ │◄── ⭐ 押金信息
│ │ 组局成功后若有牌友未赴约，其鸽子费平均分给其他牌友。 │ │
│ │ 组局成功或失败后鸽子费将全额返还。 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────┐ ┌─────────────────────────────┐ │
│ │ 关闭 │ │ 参与组局 │ │◄── ⭐ 操作按钮
│ └────────┘ └─────────────────────────────┘ │ (根据身份变化)
│ │
│ 按钮状态说明： │
│ • 未加入用户 → [关闭] [参与组局] │
│ • 参与者 → [关闭] [退出组局] │
│ • 发起者 → [关闭] [取消组局] [分享] │
│ • 已结束 → [关闭] │
└─────────────────────────────────────────────────────────────┘
```
---
### 3.5 发起预约 - 房间选择页
**文件**: `pages/appointment/book-room-page.vue`
```
┌─────────────────────────────────────────────────────────────┐
│ ▓▓▓▓▓▓▓▓▓▓▓▓ 状态栏 ▓▓▓▓▓▓▓▓▓▓▓▓▓ │
├─────────────────────────────────────────────────────────────┤
│ │
│ 发起预约 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌────┐│ │
│ │ │12/18 ││12/19 ││12/20 ││12/21 ││12/22 ││12/23 ││... ││ │◄── ⭐ 日期选择
│ │ │ 周三 ││ 周四 ││ 周五 ││ 周六 ││ 周日 ││ 周一 ││ ││ │ (今天+6天)
│ │ │[选中]││ ││ ││ ││ ││ ││ ││ │
│ │ └──────┘└──────┘└──────┘└──────┘└──────┘└──────┘└────┘│ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 营业时间：早09点 至 晚23点 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 查看当前时段空闲时间 [ 🔘 开关 ] │ │◄── 过滤开关
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ ┌──────┐ │ │ │
│ │ │ │ 🖼️ │ 302包厢 [当前使用中] │ │ │◄── 房间状态
│ │ │ │ 图片 │ 小包 2-4人 │ │ │
│ │ │ └──────┘ 标准价：38元/小时 │ │ │
│ │ │ 会员价：30元/小时 [预约] │ │ │◄── ⭐ 预约按钮
│ │ │ │ │ │
│ │ │ ━━ 已预定 ━━ 可预定 ━━ 不可预定 │ │ │◄── 图例说明
│ │ │ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ │ │
│ │ │ │ 🟠 │ │ 🟢 │ │ 🟢 │ │ 🔴 │ │ │ │◄── ⭐ 时段状态
│ │ │ │凌晨│ │上午│ │下午│ │晚上│ │ │ │ (核心展示)
│ │ │ └────┘ └────┘ └────┘ └────┘ │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 304包厢 - 大包 4-8人 │ │
│ │ ... │ │◄── 更多房间
│ └─────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ [🏠首页] [📅预约] [👤我的] │
└─────────────────────────────────────────────────────────────┘
```
#### 时段状态颜色说明：
| 颜色 | 状态 | 说明 |
|------|------|------|
| 🟢 绿色 | available | **可预约** - 该时段空闲 |
| 🟠 橙色 | reserved | **已预约** - 已被他人预约 |
| 🔴 灰色 | unavailable | **不可预约** - 后台设置不可用 |
| 🔵 蓝色 | using | **使用中** - 当前正在使用 |
---
### 3.6 发起预约 - 预约表单页
**文件**: `pages/appointment/appointment-page.vue`
```
┌─────────────────────────────────────────────────────────────┐
│ ◀ 返回 发起预约 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 时间设置 │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 日期 12/20 周五 [选择]│ │◄── 日期选择
│ │ │ │
│ │ 时间段 下午 (12:00-17:59) [选择]│ │◄── ⭐ 时段选择
│ │ │ │ (仅显示可预约)
│ │ 最晚到店 2025-12-20 12:30 [选择]│ │◄── 最晚到店时间
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 基本信息 │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 组局名称 [ 休闲娱乐，老少皆宜 ] │ │◄── ⭐ 必填
│ │ │ │
│ │ 人数 [ 4人 ▼ ] │ │◄── ⭐ 人数选择
│ │ 说明：选择1人为"无需组局"(独享模式) │ │
│ │ │ │
│ │ 玩法类型 [ 血战到底 ▼ ] │ │◄── ⭐ 必填
│ │ │ │
│ │ 具体规则 [ 2番起胡，3倍封顶 ▼ ] │ │◄── ⭐ 必填
│ │ │ │
│ │ 其他补充 [ 新手勿扰，打牌快 ] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 参与限制 │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 是否禁烟 ○ 不禁烟 ● 禁烟 │ │
│ │ │ │
│ │ 性别 ● 不限 ○ 男 ○ 女 │ │◄── ⭐ 筛选条件
│ │ │ │
│ │ 年龄范围 [ 25岁 ] - [ 45岁 ] [选择] │ │
│ │ │ │
│ │ 信誉 大于等于 [ ➖ ] 4.0 [ ➕ ] │ │◄── ⭐ 信誉门槛
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 鸽子费（押金） │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ○ 0元 ○ 5元 ● 10元 ○ 自定义 │ │◄── ⭐ 核心功能
│ │ │ │
│ │ 自定义金额 [ 20 ] 元 (0-50元) │ │
│ │ │ │
│ │ 说明：鸽子费（保证金），参与人需缴纳鸽子费。若有参与 │ │
│ │ 者在预约后没有赴约，其鸽子费由在场的所有人平分。组 │ │
│ │ 局成功或失败后鸽子费将全额返还。 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────┐ ┌─────────────────────────────────────────┐ │
│ │ 重置 │ │ 发起预约 │ │◄── ⭐ 提交按钮
│ └─────────┘ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
#### 表单必填项说明：
| 字段 | 必填 | 说明 |
|------|------|------|
| 日期 | ✅ | 从房间页带入 |
| 时间段 | ✅ | 仅显示该房间该日期可预约的时段 |
| 组局名称 | ✅ | 用于首页展示 |
| 人数 | ✅ | 1人=独享模式，2-4人=组局模式 |
| 玩法类型 | ✅ | 血战/血流成河等 |
| 具体规则 | ✅ | 依赖玩法类型 |
| 鸽子费 | ❌ | 默认0元，最高50元 |
---
### 3.7 个人中心页
**文件**: `pages/me/me-page.vue`
```
┌─────────────────────────────────────────────────────────────┐
│ ▓▓▓▓▓▓▓▓▓▓▓▓ 状态栏 ▓▓▓▓▓▓▓▓▓▓▓▓▓ │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 👤 张三 │ │◄── ⭐ 用户头像和昵称
│ │ UID: 10086 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ 🖼️ 当前没有预约 │ │ │◄── 当前预约状态
│ │ └────────────────────────────────────────────────────┘ │ │
│ │ 或者 │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ 待开始 | 休闲局 │ │ │◄── ⭐ 当前预约卡片
│ │ │ 12/20 18:00-22:00 | 304包厢 │ │ │ (如果有预约)
│ │ │ 血战到底 | 4人 │ │ │
│ │ │ [牌友评价] [签到] │ │ │◄── 快捷操作按钮
│ │ └────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 我的信誉 4.8 │ │◄── ⭐ 信誉分
│ │ │ │ (点击查看详情)
│ │ 牌品 ⭐⭐⭐⭐⭐ 4.5 │ │◄── ⭐ 牌品评分
│ │ │ │
│ │ 牌技 ⭐⭐⭐⭐☆ 4.2 │ │◄── ⭐ 牌技评分
│ │ │ │
│ │ 鸽子数 2 次 │ │◄── 爽约次数
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 常用功能 │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ 📋 预约记录 📑 订单记录 ❓ 常见问题 │ │
│ │ │ │
│ │ 🚫 黑名单 📞 联系我们 📩 我的消息 │ │◄── 功能入口
│ │ │ │
│ │ 💰 我的收益 │ │◄── ⭐ 收益入口
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ [🏠首页] [📅预约] [👤我的] │
└─────────────────────────────────────────────────────────────┘
```
---
### 3.8 签到弹窗
**文件**: `components/com/page/qiandao-popup.vue`
签到是预约流程的关键步骤，**仅发起者可操作**：
```
┌─────────────────────────────────────────────────────────────┐
│ 预约签到 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 请确认实际到场的参与者： │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ☑️ 👤 张三 (发起者) ← 默认勾选 │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ ☑️ 👤 李四 │ │◄── ⭐ 勾选到场人员
│ ├─────────────────────────────────────────────────────────┤ │
│ │ ☐ 👤 王五 ← 未勾选=爽约 │ │◄── ⭐ 未勾选=爽约
│ ├─────────────────────────────────────────────────────────┤ │
│ │ ☑️ 👤 赵六 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ⚠️ 注意： │
│ • 未勾选的参与者将被标记为"爽约" │
│ • 爽约者信誉分 -0.5，鸽子次数 +1 │
│ • 爽约者的押金将平分给到场者 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 确认签到 │ │◄── ⭐ 提交签到
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
### 3.9 评价弹窗
**文件**: `components/com/page/reservation-evaluate.vue`
预约完成后，参与者可以互相评价：
```
┌─────────────────────────────────────────────────────────────┐
│ 牌友评价 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 请为到场的牌友评分： │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 👤 李四 │ │
│ │ │ │
│ │ 牌品 ⭐⭐⭐⭐⭐ │ │◄── ⭐ 牌品评分
│ │ │ │ (1-5星)
│ │ 牌技 ⭐⭐⭐⭐☆ │ │◄── ⭐ 牌技评分
│ │ │ │ (1-5星)
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 👤 赵六 [已评价] ✅ │ │◄── 已评价标记
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────────────────────────────────┐ │
│ │ 关闭 │ │ 提交评价 │ │
│ └─────────────┘ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
### 3.10 我的收益页
**文件**: `pages/me/my-earnings-page.vue`
```
┌─────────────────────────────────────────────────────────────┐
│ ◀ 返回 我的收益 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 待提现收益 已提现收益 │ │
│ │ ￥128.50 ￥350.00 │ │◄── ⭐ 收益统计
│ │ │ │
│ │ [ 申请提现 ] │ │◄── ⭐ 提现按钮
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────┬───────────────────────┐ │
│ │ 收益记录 │ 提现记录 │ │◄── Tab切换
│ └───────────────────────┴───────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 2025-12-18 14:30 │ │
│ │ 组局佣金 - 304包厢 +￥12.50 │ │◄── 收益明细
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 2025-12-17 20:00 │ │
│ │ 爽约补偿 - 302包厢 +￥5.00 │ │◄── 爽约补偿
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 2025-12-15 18:00 │ │
│ │ 组局佣金 - 306包厢 +￥18.00 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
### 3.11 页面跳转关系图
```mermaid
graph TD
subgraph TabBar页面
A[首页
index.vue]
B[预约
book-room-page.vue]
C[我的
me-page.vue]
end
subgraph 弹窗组件
D[预约详情弹窗
ReservationPopup]
E[签到弹窗
qiandao-popup]
F[评价弹窗
reservation-evaluate]
end
subgraph 子页面
G[预约表单
appointment-page]
H[预约记录
appointment-record]
I[我的收益
my-earnings-page]
J[我的消息
my-message-page]
K[黑名单
blacklist-page]
L[登录
login]
end
A -->|点击卡片| D
D -->|参与组局| D
D -->|发起者取消| D
B -->|选择房间| G
G -->|提交成功| A
C -->|预约记录| H
C -->|我的收益| I
C -->|我的消息| J
C -->|黑名单| K
C -->|未登录| L
H -->|点击预约| D
H -->|牌友评价| F
H -->|签到| E
C -->|当前预约卡片| D
C -->|牌友评价| F
C -->|签到| E
style A fill:#e1f5fe
style B fill:#e1f5fe
style C fill:#e1f5fe
style D fill:#fff3e0
style E fill:#fff3e0
style F fill:#fff3e0
style G fill:#e8f5e9
```
---
### 3.12 界面交互流程总结
```mermaid
flowchart LR
subgraph 浏览流程
A1[首页浏览预约] --> A2[点击卡片]
A2 --> A3[查看详情弹窗]
A3 --> A4{是否加入?}
A4 -->|是| A5[参与组局]
A4 -->|否| A6[关闭弹窗]
end
subgraph 发起流程
B1[点击预约Tab] --> B2[选择日期]
B2 --> B3[选择房间]
B3 --> B4[点击预约按钮]
B4 --> B5[填写预约表单]
B5 --> B6[支付鸽子费]
B6 --> B7[发起成功]
end
subgraph 参与后流程
C1[预约开始] --> C2[发起者签到]
C2 --> C3[确认到场人员]
C3 --> C4[预约进行中]
C4 --> C5[预约结束]
C5 --> C6[互相评价]
C6 --> C7[押金退还]
end
style A5 fill:#4caf50,color:#fff
style B7 fill:#4caf50,color:#fff
style C7 fill:#4caf50,color:#fff
```
---
## 4. 核心业务模块
### 4.1 用户认证模块
#### 4.1.1 登录流程
用户通过微信小程序登录，获取手机号授权后绑定账号。
```mermaid
sequenceDiagram
participant U as 用户
participant MP as 小程序
participant WX as 微信服务器
participant BE as 后端服务
participant DB as 数据库
U->>MP: 点击登录
MP->>U: 请求授权手机号
U->>MP: 同意授权
MP->>WX: 获取code和encryptedData
WX->>MP: 返回加密数据
MP->>BE: POST /user/UseWxPhoneNumberLogin
Note over MP,BE: 传递code和sessionAuthId
BE->>WX: 解密手机号
WX->>BE: 返回手机号
BE->>DB: 查询/创建用户
DB->>BE: 返回用户信息
BE->>MP: 返回token和用户信息
MP->>MP: 存储token到本地
MP->>U: 登录成功
```
#### 3.1.2 用户信息结构
| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 用户ID |
| nickName | string | 昵称 |
| avatarImage | string | 头像URL |
| sex | int | 性别：1男 2女 |
| birthday | DateTime? | 生日（用于计算年龄） |
| credit_score | decimal | 信誉分（0-5分，默认5分） |
| play_level | decimal | 牌品评分（1-5分，默认4分） |
| skills_level | decimal | 牌技评分（1-5分，默认4分） |
| dove_count | int | 鸽子次数 |
---
### 4.2 预约管理模块
#### 4.2.1 预约生命周期
```mermaid
stateDiagram-v2
[*] --> 待开始: 创建预约
待开始 --> 已锁定: 人满
待开始 --> 已取消: 发起者取消
待开始 --> 待开始: 参与者加入/退出
已锁定 --> 待开始: 参与者退出
已锁定 --> 已取消: 发起者取消
已锁定 --> 进行中: 签到
待开始 --> 进行中: 签到（人未满也可签到）
进行中 --> 已结束: 时间结束
已取消 --> [*]
已结束 --> [*]
```
#### 4.2.2 预约状态说明
| status | 状态名 | 说明 |
|--------|--------|------|
| 0 | 待开始 | 预约已创建，等待参与者加入或等待开始时间 |
| 1 | 已锁定 | 参与人数已满，等待开始 |
| 2 | 进行中 | 发起者已签到，游戏进行中 |
| 3 | 已结束 | 预约时间已过，预约完成 |
| 4 | 已取消 | 预约被取消 |
#### 4.2.3 发起预约流程
```mermaid
flowchart TD
A[用户点击发起预约] --> B[选择日期]
B --> C[查看房间列表及时段状态]
C --> D{选择房间和时段}
D --> E[填写预约信息]
subgraph 预约信息
E --> E1[组局名称]
E --> E2[人数 1-4人]
E --> E3[玩法类型]
E --> E4[游戏规则]
E --> E5[参与限制]
E --> E6[鸽子费设置]
end
E1 & E2 & E3 & E4 & E5 & E6 --> F[提交前验证]
F --> G{调用CanCreateSQReservation}
G -->|验证失败| H[显示错误信息]
H --> E
G -->|验证通过| I{是否有鸽子费}
I -->|有| J[发起微信支付]
J --> K{支付结果}
K -->|成功| L[调用AddSQReservation创建预约]
K -->|失败| M[提示支付失败]
I -->|无| L
L --> N[创建预约记录]
N --> O[创建发起者参与记录 role=1]
O --> P[返回预约ID]
P --> Q[跳转到预约详情]
```
#### 4.2.4 加入预约流程
```mermaid
flowchart TD
A[用户点击加入预约] --> B{预约是否存在且未结束}
B -->|否| C[提示：预约不存在或已结束]
B -->|是| D{是否已加入该预约}
D -->|是| E[提示：您已加入该预约]
D -->|否| F{是否为独享模式}
F -->|是| G[提示：该预约不接受其他人加入]
F -->|否| H[校验参与条件]
subgraph 条件校验
H --> H1{信誉分是否达标}
H1 -->|否| I1[提示：信誉分不足]
H1 -->|是| H2{性别是否符合}
H2 -->|否| I2[提示：性别不符合要求]
H2 -->|是| H3{年龄是否在范围内}
H3 -->|否| I3[提示：年龄不符合限制]
H3 -->|是| H4{是否有时间冲突}
H4 -->|是| I4[提示：有其他预约时间冲突]
H4 -->|否| H5{预约是否已满}
H5 -->|是| I5[提示：预约已满]
end
H5 -->|否| J{是否有鸽子费}
J -->|有| K[发起微信支付]
K --> L{支付结果}
L -->|成功| M[创建参与者记录 role=0]
L -->|失败| N[提示支付失败]
J -->|无| M
M --> O[加入成功]
```
#### 4.2.5 取消预约流程
```mermaid
flowchart TD
A[用户点击取消预约] --> B{预约是否存在}
B -->|否| C[提示：预约不存在]
B -->|是| D{距开始是否<30分钟}
D -->|是| E[提示：开始前30分钟无法取消]
D -->|否| F{预约状态是否>=3}
F -->|是| G[提示：已结束或已取消]
F -->|否| H{用户角色}
H -->|发起者 role=1| I[发起者取消整个预约]
I --> J[预约状态改为已取消 status=4]
J --> K[所有参与者标记为已退出]
K --> L{是否有已支付押金}
L -->|有| M[已支付者标记为待退款 is_refund=3]
M --> N[发送通知给所有参与者]
L -->|无| N
H -->|参与者 role=0| O{预约是否已开始}
O -->|是| P[提示：只有发起者可取消]
O -->|否| Q[参与者退出]
Q --> R[标记该用户为已退出 status=1]
R --> S{该用户是否已支付押金}
S -->|是| T[标记为待退款 is_refund=3]
T --> U[退出成功]
S -->|否| U
N --> V[取消完成]
```
---
### 4.3 签到模块
#### 4.3.1 签到流程
签到是预约流程的关键环节，只有发起者可以操作，用于确认实际到场人员。
```mermaid
flowchart TD
A[发起者点击签到] --> B{预约是否存在}
B -->|否| C[提示：预约不存在]
B -->|是| D{预约状态是否>=3}
D -->|是| E[提示：已结束或已取消]
D -->|否| F{是否已签到 status=2}
F -->|是| G[提示：已签到，无法重复]
F -->|否| H{是否为发起者}
H -->|否| I[提示：仅发起者可签到]
H -->|是| J[显示参与者列表]
J --> K[勾选实际到场人员]
K --> L[提交签到]
L --> M[开启数据库事务]
M --> N[预约状态改为进行中 status=2]
N --> O[所有未退出参与者默认标记为到场 is_arrive=1]
O --> P{是否有未到场人员}
P -->|有| Q[未到场人员处理]
subgraph 爽约惩罚
Q --> Q1[标记为未到场 is_arrive=2]
Q1 --> Q2[标记为已退出 status=1]
Q2 --> Q3[扣除信誉分 -0.5]
Q3 --> Q4[增加鸽子次数 dove_count++]
Q4 --> Q5[记录信誉变更日志]
end
P -->|无| R[到场人员处理]
Q5 --> R
subgraph 守约奖励
R --> R1[增加信誉分 +0.2 最高5.0]
R1 --> R2[记录信誉变更日志]
end
R2 --> S{是否有押金}
S -->|有| T[到场且已支付者标记为待退款 is_refund=3]
T --> U[提交事务]
S -->|无| U
U --> V[签到完成]
```
#### 4.3.2 签到后信誉变化
| 情况 | 信誉变化 | 其他影响 |
|------|----------|----------|
| 到场（守约） | +0.2（最高5.0） | - |
| 未到场（爽约） | -0.5 | 鸽子次数+1 |
---
### 4.4 评价模块
#### 4.4.1 评价流程
```mermaid
flowchart TD
A[用户进入预约详情] --> B{预约是否已完成且已签到}
B -->|否| C[不显示评价入口]
B -->|是| D[显示评价入口]
D --> E[点击牌友评价]
E --> F[获取可评价参与者列表]
F --> G[只显示实际到场的其他参与者]
G --> H[选择要评价的人]
H --> I[填写评价]
subgraph 评价维度
I --> I1[牌品评分 1-5星]
I --> I2[牌技评分 1-5星]
end
I1 & I2 --> J[提交评价]
J --> K[创建评价记录]
K --> L[重新计算被评价人的平均分]
subgraph 平均分计算
L --> L1[获取所有历史评价]
L1 --> L2[计算 牌品 = sum评价 + 4 / 评价次数 + 1]
L2 --> L3[计算 牌技 = sum评价 + 4 / 评价次数 + 1]
L3 --> L4[如果只有1次评价，分母+1避免偏差]
end
L4 --> M[更新用户评分]
M --> N[评价完成]
```
#### 4.4.2 评价规则
1. **评价时机**：预约状态为"已结束"且已签到后
2. **评价对象**：只能评价实际到场的其他参与者（排除自己）
3. **评价次数**：每个参与者只能被评价一次
4. **评价维度**：
- 牌品（play_level）：1-5分
- 牌技（skills_level）：1-5分
#### 4.4.3 评分计算公式
```
新评分 = (历史评分总和 + 初始分4) / (评价次数 + 1)
特殊情况：当只有1次评价时，分母为(评价次数 + 2)避免偏差
```
---
### 4.5 押金（鸽子费）模块
#### 4.5.1 押金流程总览
```mermaid
flowchart TD
subgraph 发起预约
A[发起者设置鸽子费] --> B[发起者支付鸽子费]
B --> C[创建预约成功]
C --> D[参与者记录 is_refund=1 待支付]
end
subgraph 加入预约
E[参与者加入] --> F{预约是否有鸽子费}
F -->|有| G[参与者支付鸽子费]
G --> H[参与者记录 is_refund=2 已支付]
F -->|无| I[参与者记录 is_refund=0]
end
subgraph 签到/取消
J[签到或取消] --> K{参与者是否已支付}
K -->|是| L[标记为 is_refund=3 待退款]
K -->|否| M[无需退款]
end
subgraph 定时任务
N[定时扫描 is_refund=3] --> O[调用微信退款API]
O --> P{退款结果}
P -->|成功| Q[更新 is_refund=4 已退款]
P -->|失败| R[更新 is_refund=5 退款异常]
end
```
#### 4.5.2 押金状态说明
| is_refund | 状态名 | 说明 |
|-----------|--------|------|
| 0 | 无押金 | 预约不需要鸽子费 |
| 1 | 待支付 | 需要支付但未支付 |
| 2 | 已支付 | 已完成支付 |
| 3 | 待退款 | 已发起退款流程，等待处理 |
| 4 | 已退款 | 退款完成 |
| 5 | 退款异常 | 退款失败 |
#### 4.5.3 押金分配规则
```mermaid
flowchart TD
A[签到确认] --> B{是否有人爽约}
B -->|无| C[所有人押金原路退还]
B -->|有| D[计算爽约人数和到场人数]
D --> E[爽约者押金不退还]
E --> F[爽约者押金平分给到场者]
F --> G[到场者获得额外收益]
G --> H[到场者原押金退还]
```
---
### 4.6 消息通知模块
#### 4.6.1 消息类型
| 类型 | message_type | 说明 |
|------|--------------|------|
| 系统消息 | 0 | 预约相关自动通知 |
| 私信 | 1 | 暂未实现 |
#### 4.6.2 自动发送场景
```mermaid
flowchart LR
A[组局成功] --> B[通知所有参与者]
C[组局失败/解散] --> D[通知所有参与者]
E[预约即将开始] --> F[提醒参与者]
G[签到完成] --> H[通知到场/未到场情况]
```
#### 4.6.3 消息流程
```mermaid
sequenceDiagram
participant S as 系统
participant DB as 数据库
participant U as 用户
S->>DB: 插入消息记录 (SQMessage)
Note over DB: user_id=0 表示全体用户
U->>DB: 获取消息列表
DB->>U: 返回消息 + 已读状态
Note over DB: 已读状态存储在 SQMessageRead 表
U->>DB: 标记全部已读
Note over DB: 插入已读记录
```
---
### 4.7 收益模块
#### 4.7.1 收益来源
1. **发起预约佣金**：房费的10%（需线下员工在后台添加）
2. **爽约者押金分成**：爽约者的鸽子费平分给到场者
#### 4.7.2 收益流程
```mermaid
flowchart TD
A[预约完成] --> B{发起者是否有佣金}
B -->|有| C[后台员工添加佣金记录]
C --> D[更新待提现金额]
E[签到确认有人爽约] --> F[计算爽约押金]
F --> G[平分给到场者]
G --> D
D --> H[用户申请提现]
H --> I{金额是否超出可提现}
I -->|是| J[提示：超出可提现金额]
I -->|否| K[创建提现申请记录]
K --> L[状态：提现中]
L --> M[后台审核]
M --> N{审核结果}
N -->|同意| O[线下打款]
O --> P[状态：已提现]
N -->|拒绝| Q[状态：已取消]
```
#### 4.7.3 提现状态
| 状态 | 说明 |
|------|------|
| 提现中 | 申请已提交，等待审核 |
| 已提现 | 线下打款完成 |
| 已取消 | 后台拒绝/取消申请 |
---
### 4.8 黑名单模块
#### 4.8.1 黑名单功能
```mermaid
flowchart TD
A[用户A将用户B加入黑名单] --> B[写入黑名单表]
B --> C[首页预约列表]
C --> D{用户B是否在黑名单}
D -->|是| E[过滤B发起的预约]
D -->|否| F[正常显示]
```
#### 4.8.2 黑名单影响
1. 首页自动过滤黑名单用户发起的预约
2. 黑名单用户无法加入我发起的预约（待实现）
3. 评价页面显示黑名单状态
---
## 5. 核心业务流程图
### 5.1 完整预约生命周期
```mermaid
flowchart TB
subgraph 发起阶段
A1[选择房间日期] --> A2[填写预约信息]
A2 --> A3[设置参与限制]
A3 --> A4[设置鸽子费]
A4 --> A5{有鸽子费?}
A5 -->|是| A6[微信支付]
A5 -->|否| A7[创建预约]
A6 --> A7
A7 --> A8[预约状态: 待开始]
end
subgraph 参与阶段
A8 --> B1[等待参与者加入]
B1 --> B2{人数已满?}
B2 -->|是| B3[预约状态: 已锁定]
B2 -->|否| B4{有人退出?}
B4 -->|是| B1
B4 -->|否| B5{到达开始时间?}
B3 --> B5
B5 -->|否| B1
end
subgraph 签到阶段
B5 -->|是| C1[发起者签到]
C1 --> C2[确认到场人员]
C2 --> C3[处理到场/未到场]
C3 --> C4[更新信誉分]
C4 --> C5[预约状态: 进行中]
end
subgraph 结束阶段
C5 --> D1[游戏进行中]
D1 --> D2{到达结束时间?}
D2 -->|否| D1
D2 -->|是| D3[预约状态: 已结束]
D3 --> D4[可以互相评价]
D4 --> D5[处理押金退款]
D5 --> D6[发放佣金]
end
subgraph 取消分支
A8 --> E1{发起者取消?}
B1 --> E1
B3 --> E1
E1 -->|是| E2[预约状态: 已取消]
E2 --> E3[所有人退出]
E3 --> E4[退还已支付押金]
end
```
### 5.2 时序图：完整预约流程
```mermaid
sequenceDiagram
participant U1 as 发起者
participant U2 as 参与者
participant FE as 前端
participant BE as 后端
participant DB as 数据库
participant WX as 微信支付
%% 发起预约
rect rgb(200, 230, 200)
Note over U1,WX: 发起预约阶段
U1->>FE: 选择房间和时段
FE->>BE: GetRoomListWithSlotsNew
BE->>DB: 查询房间状态
DB->>BE: 返回房间列表
BE->>FE: 房间时段状态
U1->>FE: 填写预约信息
FE->>BE: CanCreateSQReservation
BE->>DB: 校验时间冲突等
DB->>BE: 校验结果
BE->>FE: 可以创建
FE->>WX: 支付鸽子费
WX->>FE: 支付成功
FE->>BE: AddSQReservation
BE->>DB: 创建预约+参与者记录
DB->>BE: 返回预约ID
BE->>FE: 预约成功
end
%% 加入预约
rect rgb(200, 200, 230)
Note over U1,WX: 加入预约阶段
U2->>FE: 浏览预约列表
FE->>BE: GetReservationList
BE->>DB: 查询预约列表
DB->>BE: 预约数据
BE->>FE: 预约列表
U2->>FE: 点击加入
FE->>BE: JoinReservation
BE->>DB: 校验条件
DB->>BE: 校验通过
BE->>FE: 需要支付鸽子费
FE->>WX: 支付鸽子费
WX->>FE: 支付成功
FE->>BE: JoinReservation(带支付信息)
BE->>DB: 创建参与者记录
DB->>BE: 成功
BE->>FE: 加入成功
end
%% 签到
rect rgb(230, 200, 200)
Note over U1,WX: 签到阶段
U1->>FE: 点击签到
FE->>FE: 显示参与者列表
U1->>FE: 确认到场人员
FE->>BE: CheckInReservation
BE->>DB: 开启事务
BE->>DB: 更新预约状态
BE->>DB: 更新到场状态
BE->>DB: 更新信誉分
BE->>DB: 标记待退款
BE->>DB: 提交事务
DB->>BE: 成功
BE->>FE: 签到成功
end
%% 评价
rect rgb(230, 230, 200)
Note over U1,WX: 评价阶段
U1->>FE: 点击评价
FE->>BE: GetEvaluateServices
BE->>DB: 查询可评价人员
DB->>BE: 参与者列表
BE->>FE: 可评价列表
U1->>FE: 提交评价
FE->>BE: AddEvaluateServices
BE->>DB: 创建评价记录
BE->>DB: 更新被评价人分数
DB->>BE: 成功
BE->>FE: 评价成功
end
```
### 5.3 房间时段状态机
```mermaid
stateDiagram-v2
[*] --> 可预约: 默认状态
可预约 --> 已预约: 有人预约该时段
可预约 --> 不可预约: 后台设置不可用
已预约 --> 可预约: 预约取消
已预约 --> 进行中: 签到开始
进行中 --> 可预约: 预约结束
不可预约 --> 可预约: 后台取消不可用
note right of 可预约: 绿色
note right of 已预约: 橙色
note right of 不可预约: 灰色
```
---
## 6. 数据模型
### 9.1 核心数据表关系图
```mermaid
erDiagram
CoreCmsUser ||--o{ SQReservationParticipants : "参与"
CoreCmsUser ||--o{ SQReservationEvaluate : "评价"
CoreCmsUser ||--o{ SQReservationReputation : "信誉记录"
CoreCmsUser ||--o{ CoreCmsUserBlacklist : "黑名单"
CoreCmsUser ||--o{ SQMessage : "接收消息"
CoreCmsUser ||--o{ SQEarningsRecord : "收益"
CoreCmsUser ||--o{ SQWithdrawRecord : "提现"
SQReservations ||--o{ SQReservationParticipants : "包含"
SQReservations ||--o{ SQReservationEvaluate : "评价关联"
SQReservations }o--|| SQRooms : "使用房间"
SQRooms ||--o{ SQRoomUnavailableTimes : "不可用时间"
SQRooms ||--o{ SQRoomPricing : "价格配置"
CoreCmsUser {
int id PK
string nickName
string avatarImage
int sex
datetime birthday
decimal credit_score
decimal play_level
decimal skills_level
int dove_count
}
SQReservations {
int id PK
int room_id FK
string room_name
datetime start_time
datetime end_time
int duration_minutes
string title
string game_type
string game_rule
int player_count
int status
decimal deposit_fee
decimal credit_limit
int gender_limit
int min_age
int max_age
bool is_smoking
datetime latest_arrival_time
string extra_info
bool is_solo_mode
datetime created_at
datetime updated_at
}
SQReservationParticipants {
int id PK
int reservation_id FK
int user_id FK
int role
int status
datetime join_time
datetime quit_time
int is_arrive
datetime check_reservation
int is_refund
string paymentId
string important_data
}
SQRooms {
int id PK
string name
int capacity
decimal price_per_hour
string description
string image_url
bool status
datetime created_at
}
SQReservationEvaluate {
int id PK
int reservation_id FK
int user_id FK
int to_user_id FK
int role
decimal play_level
decimal skills_level
datetime created_at
}
SQReservationReputation {
int id PK
int user_id FK
int reservation_id FK
decimal reputation_value
string remark
datetime created_at
}
```
### 9.2 数据表详细说明
#### 5.2.1 SQReservations（预约表）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键 |
| room_id | int | 房间ID（外键） |
| room_name | string | 房间名称（冗余） |
| start_time | datetime | 开始时间 |
| end_time | datetime | 结束时间 |
| duration_minutes | int | 时长（分钟） |
| title | string | 组局名称 |
| game_type | string | 游戏类型（血战/血流成河等） |
| game_rule | string | 游戏规则 |
| player_count | int | 需要人数（1-4） |
| status | int | 状态（0待开始/1已锁定/2进行中/3已结束/4已取消） |
| deposit_fee | decimal | 押金费用 |
| credit_limit | decimal | 最低信誉要求 |
| gender_limit | int | 性别限制（0不限/1男/2女） |
| min_age | int | 最小年龄限制 |
| max_age | int | 最大年龄限制 |
| is_smoking | bool | 是否禁烟 |
| latest_arrival_time | datetime | 最晚到店时间 |
| extra_info | string | 其他补充说明 |
| is_solo_mode | bool | 是否独享模式（人数=1时自动设为true） |
| remarks | string | 备注（如取消原因） |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
#### 5.2.2 SQReservationParticipants（参与者表）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键 |
| reservation_id | int | 预约ID（外键） |
| user_id | int | 用户ID（外键） |
| role | int | 角色（0参与者/1发起者） |
| status | int | 状态（0正常/1已退出） |
| join_time | datetime | 加入时间 |
| quit_time | datetime | 退出时间 |
| is_arrive | int | 是否到场（0未签到/1到场/2未到场） |
| check_reservation | datetime | 签到时间 |
| is_refund | int | 退款状态（0无/1待支付/2已支付/3待退款/4已退款/5异常） |
| paymentId | string | 支付订单号 |
| important_data | string | 重要数据（JSON格式，含支付信息等） |
---
## 7. API接口详解
### 9.1 预约相关接口
| 接口 | 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|------|
| 首页预约列表 | GET | /api/sq/GetReservationList | 无 | 获取未结束的预约列表，自动过滤黑名单 |
| 预约详情 | GET | /api/sq/GetReservationDetail | 无 | 根据ID获取预约详情 |
| 我的预约 | GET | /api/sq/GetMyReservation | 需要 | type=0参与的/type=1发起的 |
| 正在进行 | GET | /api/sq/GetMyUseReservation | 需要 | 获取未结束的预约 |
| 验证创建 | POST | /api/sq/CanCreateSQReservation | 需要 | 创建前校验 |
| 创建预约 | POST | /api/sq/AddSQReservation | 需要 | 发起新预约 |
| 加入预约 | POST | /api/sq/JoinReservation | 需要 | 加入现有预约 |
| 取消预约 | POST | /api/sq/CancelReservation | 需要 | 发起者/参与者取消 |
| 签到 | POST | /api/sq/CheckInReservation | 需要 | 发起者签到确认 |
### 9.2 房间相关接口
| 接口 | 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|------|
| 可选日期 | GET | /api/sq/GetAvailableDates | 无 | 今天+未来6天 |
| 房间时段 | GET | /api/sq/GetRoomListWithSlotsNew | 无 | 房间列表及时段状态 |
| 房间详情 | GET | /api/sq/GetRoomDetail | 无 | 房间信息及时段 |
| 可预约房间 | GET | /api/sq/GetReservationRoomList | 无 | 指定时间可预约的房间 |
| 营业时间 | GET | /api/sq/GetBusinessHours | 无 | 09:00-23:00 |
### 9.3 评价相关接口
| 接口 | 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|------|
| 获取评价 | GET | /api/sq/GetEvaluateServices | 需要 | 获取可评价的参与者 |
| 添加评价 | POST | /api/sq/AddEvaluateServices | 需要 | 评价参与者 |
| 信誉记录 | GET | /api/sq/GetReputationByUser | 需要 | 我的信誉变化记录 |
| 评价给我 | GET | /api/sq/GetEvaluateToMe | 需要 | 别人给我的评价 |
### 9.4 消息相关接口
| 接口 | 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|------|
| 消息列表 | GET | /api/sq/GetMessageList | 需要 | 站内信列表 |
| 未读数量 | GET | /api/sq/GetUnreadCount | 需要 | 未读消息数 |
| 标记已读 | POST | /api/sq/MarkAllAsRead | 需要 | 全部标记已读 |
### 9.5 收益相关接口
| 接口 | 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|------|
| 收益统计 | GET | /api/sq/GetEarningsSummary | 需要 | 待提现+已提现 |
| 收益记录 | POST | /api/sq/GetEarningsRecordList | 需要 | 收益明细 |
| 提现记录 | POST | /api/sq/GetWithdrawRecordList | 需要 | 提现历史 |
| 申请提现 | POST | /api/sq/ApplyWithdraw | 需要 | 发起提现 |
| 收益规则 | GET | /api/sq/GetEarningsRule | 无 | 规则说明 |
---
## 8. 业务规则汇总
### 9.1 时间规则
| 规则 | 值 | 说明 |
|------|-----|------|
| 可预约范围 | 今天+未来6天 | 共7天 |
| 时段划分 | 凌晨(0-6h)/上午(6-12h)/下午(12-18h)/晚上(18-24h) | 4个时段 |
| 营业时间 | 09:00-23:00 | 可在后台配置 |
| 取消限制 | 开始前30分钟 | 30分钟内无法取消 |
### 9.2 人数规则
| 规则 | 值 | 说明 |
|------|-----|------|
| 最少人数 | 1人 | 独享模式 |
| 最多人数 | 4人 | 麻将标准人数 |
| 独享模式 | player_count=1 | 自动设置，不接受其他人加入 |
| 人满锁定 | 达到player_count | 状态变为已锁定(1) |
### 9.3 押金规则
| 规则 | 值 | 说明 |
|------|-----|------|
| 金额范围 | 0-50元 | 可选0/5/10/20或自定义 |
| 用途 | 防止爽约 | 到场退还，爽约扣除 |
| 爽约分配 | 平分给到场者 | 由到场者瓜分 |
| 退款时机 | 签到后/取消后 | 标记待退款，定时任务处理 |
### 9.4 信誉规则
| 情况 | 变化 | 说明 |
|------|------|------|
| 初始信誉 | 5.0分 | 满分 |
| 守约奖励 | +0.2分 | 最高5.0 |
| 爽约惩罚 | -0.5分 | 最低0分，鸽子次数+1 |
| 信誉限制 | 发起者设置 | 低于限制无法加入 |
### 9.5 评价规则
| 规则 | 值 | 说明 |
|------|-----|------|
| 评价时机 | 预约完成后 | 状态为已结束 |
| 评价对象 | 到场的其他参与者 | 排除自己和未到场 |
| 评价维度 | 牌品/牌技 | 各1-5分 |
| 评价次数 | 每人一次 | 不可重复评价 |
| 初始分 | 4分 | 用于计算平均 |
### 9.6 参与限制规则
| 限制项 | 可选值 | 说明 |
|--------|--------|------|
| 性别限制 | 不限/男/女 | 0/1/2 |
| 年龄限制 | 最小-最大 | 0表示不限 |
| 信誉限制 | 0-5分 | 最低信誉要求 |
| 禁烟 | 是/否 | 是否禁止吸烟 |
---
## 9. 状态机定义
### 9.1 预约状态机
```mermaid
stateDiagram-v2
direction LR
[*] --> S0_待开始: 创建预约
S0_待开始 --> S1_已锁定: 人满
S0_待开始 --> S2_进行中: 签到
S0_待开始 --> S4_已取消: 取消
S1_已锁定 --> S0_待开始: 有人退出
S1_已锁定 --> S2_进行中: 签到
S1_已锁定 --> S4_已取消: 发起者取消
S2_进行中 --> S3_已结束: 时间结束
S3_已结束 --> [*]
S4_已取消 --> [*]
note right of S0_待开始: status=0
note right of S1_已锁定: status=1
note right of S2_进行中: status=2
note right of S3_已结束: status=3
note right of S4_已取消: status=4
```
### 9.2 参与者状态机
```mermaid
stateDiagram-v2
direction LR
[*] --> P0_正常: 加入预约
P0_正常 --> P1_已退出: 主动退出
P0_正常 --> P1_已退出: 被踢出(签到时未到场)
P0_正常 --> P1_已退出: 预约取消
P1_已退出 --> [*]
note right of P0_正常: status=0
note right of P1_已退出: status=1
```
### 9.3 到场状态机
```mermaid
stateDiagram-v2
direction LR
[*] --> A0_未签到: 加入预约
A0_未签到 --> A1_到场: 签到确认到场
A0_未签到 --> A2_未到场: 签到确认未到场
A1_到场 --> [*]: 完成
A2_未到场 --> [*]: 被踢出
note right of A0_未签到: is_arrive=0
note right of A1_到场: is_arrive=1
note right of A2_未到场: is_arrive=2
```
### 9.4 退款状态机
```mermaid
stateDiagram-v2
direction LR
[*] --> R0_无押金: 预约无鸽子费
[*] --> R1_待支付: 需要支付鸽子费
R1_待支付 --> R2_已支付: 支付成功
R1_待支付 --> R0_无押金: 预约取消(未支付)
R2_已支付 --> R3_待退款: 签到/取消触发
R3_待退款 --> R4_已退款: 定时任务退款成功
R3_待退款 --> R5_退款异常: 定时任务退款失败
R4_已退款 --> [*]
R5_退款异常 --> R3_待退款: 人工处理后重试
R5_退款异常 --> [*]: 人工处理
R0_无押金 --> [*]
note right of R0_无押金: is_refund=0
note right of R1_待支付: is_refund=1
note right of R2_已支付: is_refund=2
note right of R3_待退款: is_refund=3
note right of R4_已退款: is_refund=4
note right of R5_退款异常: is_refund=5
```
---
## 附录A：前端核心文件路径
| 功能 | 文件路径 |
|------|----------|
| 首页 | `uniapp/mahjong_group/pages/index/index.vue` |
| 房间选择 | `uniapp/mahjong_group/pages/appointment/book-room-page.vue` |
| 预约表单 | `uniapp/mahjong_group/pages/appointment/appointment-page.vue` |
| 个人中心 | `uniapp/mahjong_group/pages/me/me-page.vue` |
| 预约记录 | `uniapp/mahjong_group/pages/me/appointment-record-page.vue` |
| 我的收益 | `uniapp/mahjong_group/pages/me/my-earnings-page.vue` |
| 消息中心 | `uniapp/mahjong_group/pages/me/my-message-page.vue` |
| 登录 | `uniapp/mahjong_group/pages/me/login.vue` |
| 预约卡片组件 | `uniapp/mahjong_group/components/index/MahjongCard.vue` |
| 预约弹窗组件 | `uniapp/mahjong_group/components/com/index/ReservationPopup.vue` |
| 签到弹窗组件 | `uniapp/mahjong_group/components/com/page/qiandao-popup.vue` |
| API接口 | `uniapp/mahjong_group/common/server/interface/sq.js` |
## 附录B：后端核心文件路径
| 功能 | 文件路径 |
|------|----------|
| 预约控制器 | `server/CoreCms.Net.Web.WebApi/Controllers/SQController.cs` |
| 预约服务 | `server/CoreCms.Net.Services/SQ/SQReservationsServices.cs` |
| 房间服务 | `server/CoreCms.Net.Services/SQ/SQRoomsServices.cs` |
| 消息服务 | `server/CoreCms.Net.Services/SQ/SQMessageServices.cs` |
| 收益服务 | `server/CoreCms.Net.Services/SQ/SQEarningsServices.cs` |
---
## 附录C：版本更新记录
### v1.0.0 核心功能
1. **会员档案功能**
- 微信授权登录，绑定手机号
- 会员行为标签：星级评分、黑名单
- 组局成功率、被投诉次数、消费频次、鸽子次数统计
2. **麻友匹配机制**
- 发布组局需求
- 其他客户查看并加入
- 组局成功后自动发送消息
- 鸽子费（押金）机制
### v1.0.1 新增功能
1. **站内信功能**
- 消息入口，红点提示
- 自动发送通知（组局成功/失败）
- 手动发送通知（后台配置）
2. **预约页优化**
- 房间时段展示（4个时段）
- 房间可用状态可视化
- 无需组局选项（独享模式）
- 鸽子费自定义金额（最高50元）
3. **我的收益功能**
- 待提现/已提现金额展示
- 收益记录查询
- 提现申请（后台审核，线下打款）
- 佣金规则：房费10%
---
*文档生成时间：2024年*
*版本：v1.0.1*