outsource/mahjong_group
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
mahjong_group/业务逻辑文档.md
zpc 63aedaf041 调整文件结构
2026-01-01 14:39:23 +08:00

82 KiB
Raw Permalink Blame History

目录

  1. 项目概述
  2. 系统架构
  3. 界面原型图与交互说明 ⭐ 新增
  4. 核心业务模块
  5. 核心业务流程图
  6. 数据模型
  7. API接口详解
  8. 业务规则汇总
  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 系统架构图

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 页面跳转关系图

graph TD
    subgraph TabBar页面
        A[首页<br>index.vue]
        B[预约<br>book-room-page.vue]
        C[我的<br>me-page.vue]
    end

    subgraph 弹窗组件
        D[预约详情弹窗<br>ReservationPopup]
        E[签到弹窗<br>qiandao-popup]
        F[评价弹窗<br>reservation-evaluate]
    end

    subgraph 子页面
        G[预约表单<br>appointment-page]
        H[预约记录<br>appointment-record]
        I[我的收益<br>my-earnings-page]
        J[我的消息<br>my-message-page]
        K[黑名单<br>blacklist-page]
        L[登录<br>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 界面交互流程总结

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 登录流程

用户通过微信小程序登录，获取手机号授权后绑定账号。

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 预约生命周期

stateDiagram-v2
    [*] --> 待开始: 创建预约
    待开始 --> 已锁定: 人满
    待开始 --> 已取消: 发起者取消
    待开始 --> 待开始: 参与者加入/退出
    已锁定 --> 待开始: 参与者退出
    已锁定 --> 已取消: 发起者取消
    已锁定 --> 进行中: 签到
    待开始 --> 进行中: 签到（人未满也可签到）
    进行中 --> 已结束: 时间结束
    已取消 --> [*]
    已结束 --> [*]

4.2.2 预约状态说明

status 状态名 说明
0 待开始 预约已创建，等待参与者加入或等待开始时间
1 已锁定 参与人数已满，等待开始
2 进行中 发起者已签到，游戏进行中
3 已结束 预约时间已过，预约完成
4 已取消 预约被取消

4.2.3 发起预约流程

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 加入预约流程

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 取消预约流程

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 签到流程

签到是预约流程的关键环节，只有发起者可以操作，用于确认实际到场人员。

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 评价流程

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 押金流程总览

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 押金分配规则

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 自动发送场景

flowchart LR
    A[组局成功] --> B[通知所有参与者]
    C[组局失败/解散] --> D[通知所有参与者]
    E[预约即将开始] --> F[提醒参与者]
    G[签到完成] --> H[通知到场/未到场情况]

4.6.3 消息流程

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 收益流程

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 黑名单功能

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 完整预约生命周期

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 时序图：完整预约流程

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 房间时段状态机

stateDiagram-v2
    [*] --> 可预约: 默认状态
    可预约 --> 已预约: 有人预约该时段
    可预约 --> 不可预约: 后台设置不可用
    已预约 --> 可预约: 预约取消
    已预约 --> 进行中: 签到开始
    进行中 --> 可预约: 预约结束
    不可预约 --> 可预约: 后台取消不可用

    note right of 可预约: 绿色
    note right of 已预约: 橙色
    note right of 不可预约: 灰色

6. 数据模型

9.1 核心数据表关系图

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 预约状态机

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 参与者状态机

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 到场状态机

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 退款状态机

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