outsource/mahjong_group

Fork 0

zpc 1767a937a5 调整文件结构

2026-01-01 14:35:52 +08:00

36 KiB

Raw Blame History

麻将组局预约小程序 - 业务逻辑详解文档

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 用户认证模块

3.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	鸽子次数

3.2 预约管理模块

3.2.1 预约生命周期

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

3.2.2 预约状态说明

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

3.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[跳转到预约详情]

3.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[加入成功]

3.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[取消完成]

3.3 签到模块

3.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[签到完成]

3.3.2 签到后信誉变化

情况	信誉变化	其他影响
到场（守约）	+0.2（最高5.0）	-
未到场（爽约）	-0.5	鸽子次数+1

3.4 评价模块

3.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[评价完成]

3.4.2 评价规则

评价时机：预约状态为"已结束"且已签到后
评价对象：只能评价实际到场的其他参与者（排除自己）
评价次数：每个参与者只能被评价一次
评价维度：
- 牌品（play_level）：1-5分
- 牌技（skills_level）：1-5分

3.4.3 评分计算公式

新评分 = (历史评分总和 + 初始分4) / (评价次数 + 1)

特殊情况：当只有1次评价时，分母为(评价次数 + 2)避免偏差

3.5 押金（鸽子费）模块

3.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

3.5.2 押金状态说明

is_refund	状态名	说明
0	无押金	预约不需要鸽子费
1	待支付	需要支付但未支付
2	已支付	已完成支付
3	待退款	已发起退款流程，等待处理
4	已退款	退款完成
5	退款异常	退款失败

3.5.3 押金分配规则

flowchart TD
    A[签到确认] --> B{是否有人爽约}
    B -->|无| C[所有人押金原路退还]
    B -->|有| D[计算爽约人数和到场人数]
    D --> E[爽约者押金不退还]
    E --> F[爽约者押金平分给到场者]
    F --> G[到场者获得额外收益]
    G --> H[到场者原押金退还]

3.6 消息通知模块

3.6.1 消息类型

类型	message_type	说明
系统消息	0	预约相关自动通知
私信	1	暂未实现

3.6.2 自动发送场景

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

3.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: 插入已读记录

3.7 收益模块

3.7.1 收益来源

发起预约佣金：房费的10%（需线下员工在后台添加）
爽约者押金分成：爽约者的鸽子费平分给到场者

3.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[状态：已取消]

3.7.3 提现状态

状态	说明
提现中	申请已提交，等待审核
已提现	线下打款完成
已取消	后台拒绝/取消申请

3.8 黑名单模块

3.8.1 黑名单功能

flowchart TD
    A[用户A将用户B加入黑名单] --> B[写入黑名单表]
    B --> C[首页预约列表]
    C --> D{用户B是否在黑名单}
    D -->|是| E[过滤B发起的预约]
    D -->|否| F[正常显示]

3.8.2 黑名单影响

首页自动过滤黑名单用户发起的预约
黑名单用户无法加入我发起的预约（待实现）
评价页面显示黑名单状态

4. 核心业务流程图

4.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

4.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

4.3 房间时段状态机

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

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

5. 数据模型

5.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
    }

5.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格式，含支付信息等）

6. API接口详解

6.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	需要	发起者签到确认

6.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

6.3 评价相关接口

接口	方法	路径	权限	说明
获取评价	GET	/api/sq/GetEvaluateServices	需要	获取可评价的参与者
添加评价	POST	/api/sq/AddEvaluateServices	需要	评价参与者
信誉记录	GET	/api/sq/GetReputationByUser	需要	我的信誉变化记录
评价给我	GET	/api/sq/GetEvaluateToMe	需要	别人给我的评价

6.4 消息相关接口

接口	方法	路径	权限	说明
消息列表	GET	/api/sq/GetMessageList	需要	站内信列表
未读数量	GET	/api/sq/GetUnreadCount	需要	未读消息数
标记已读	POST	/api/sq/MarkAllAsRead	需要	全部标记已读

6.5 收益相关接口

接口	方法	路径	权限	说明
收益统计	GET	/api/sq/GetEarningsSummary	需要	待提现+已提现
收益记录	POST	/api/sq/GetEarningsRecordList	需要	收益明细
提现记录	POST	/api/sq/GetWithdrawRecordList	需要	提现历史
申请提现	POST	/api/sq/ApplyWithdraw	需要	发起提现
收益规则	GET	/api/sq/GetEarningsRule	无	规则说明

7. 业务规则汇总

7.1 时间规则

规则	值	说明
可预约范围	今天+未来6天	共7天
时段划分	凌晨(0-6h)/上午(6-12h)/下午(12-18h)/晚上(18-24h)	4个时段
营业时间	09:00-23:00	可在后台配置
取消限制	开始前30分钟	30分钟内无法取消

7.2 人数规则

规则	值	说明
最少人数	1人	独享模式
最多人数	4人	麻将标准人数
独享模式	player_count=1	自动设置，不接受其他人加入
人满锁定	达到player_count	状态变为已锁定(1)

7.3 押金规则

规则	值	说明
金额范围	0-50元	可选0/5/10/20或自定义
用途	防止爽约	到场退还，爽约扣除
爽约分配	平分给到场者	由到场者瓜分
退款时机	签到后/取消后	标记待退款，定时任务处理

7.4 信誉规则

情况	变化	说明
初始信誉	5.0分	满分
守约奖励	+0.2分	最高5.0
爽约惩罚	-0.5分	最低0分，鸽子次数+1
信誉限制	发起者设置	低于限制无法加入

7.5 评价规则

规则	值	说明
评价时机	预约完成后	状态为已结束
评价对象	到场的其他参与者	排除自己和未到场
评价维度	牌品/牌技	各1-5分
评价次数	每人一次	不可重复评价
初始分	4分	用于计算平均

7.6 参与限制规则

限制项	可选值	说明
性别限制	不限/男/女	0/1/2
年龄限制	最小-最大	0表示不限
信誉限制	0-5分	最低信誉要求
禁烟	是/否	是否禁止吸烟

8. 状态机定义

8.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

8.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

8.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

8.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 核心功能

会员档案功能
- 微信授权登录，绑定手机号
- 会员行为标签：星级评分、黑名单
- 组局成功率、被投诉次数、消费频次、鸽子次数统计
麻友匹配机制
- 发布组局需求
- 其他客户查看并加入
- 组局成功后自动发送消息
- 鸽子费（押金）机制

v1.0.1 新增功能

站内信功能
- 消息入口，红点提示
- 自动发送通知（组局成功/失败）
- 手动发送通知（后台配置）
预约页优化
- 房间时段展示（4个时段）
- 房间可用状态可视化
- 无需组局选项（独享模式）
- 鸽子费自定义金额（最高50元）
我的收益功能
- 待提现/已提现金额展示
- 收益记录查询
- 提现申请（后台审核，线下打款）
- 佣金规则：房费10%

文档生成时间：2024年 版本：v1.0.1

36 KiB Raw Blame History Unescape Escape

麻将组局预约小程序 - 业务逻辑详解文档

目录

1. 项目概述

1.1 产品定位

1.2 技术栈

1.3 核心功能清单

2. 系统架构

2.1 前端架构

2.2 后端架构

2.3 系统架构图

3. 核心业务模块

3.1 用户认证模块

3.1.1 登录流程

3.1.2 用户信息结构

3.2 预约管理模块

3.2.1 预约生命周期

3.2.2 预约状态说明

3.2.3 发起预约流程

3.2.4 加入预约流程

3.2.5 取消预约流程

3.3 签到模块

3.3.1 签到流程

3.3.2 签到后信誉变化

3.4 评价模块

3.4.1 评价流程

3.4.2 评价规则

3.4.3 评分计算公式

3.5 押金（鸽子费）模块

3.5.1 押金流程总览

3.5.2 押金状态说明

3.5.3 押金分配规则

3.6 消息通知模块

3.6.1 消息类型

3.6.2 自动发送场景

3.6.3 消息流程

3.7 收益模块

3.7.1 收益来源

3.7.2 收益流程

3.7.3 提现状态

3.8 黑名单模块

3.8.1 黑名单功能

3.8.2 黑名单影响

4. 核心业务流程图

4.1 完整预约生命周期

4.2 时序图：完整预约流程

4.3 房间时段状态机

5. 数据模型

5.1 核心数据表关系图

5.2 数据表详细说明

5.2.1 SQReservations（预约表）

5.2.2 SQReservationParticipants（参与者表）

6. API接口详解

6.1 预约相关接口

6.2 房间相关接口

6.3 评价相关接口

6.4 消息相关接口

6.5 收益相关接口

7. 业务规则汇总

7.1 时间规则

7.2 人数规则

7.3 押金规则

7.4 信誉规则

7.5 评价规则

7.6 参与限制规则

8. 状态机定义

8.1 预约状态机

8.2 参与者状态机

8.3 到场状态机

8.4 退款状态机

附录A：前端核心文件路径

附录B：后端核心文件路径

附录C：版本更新记录

v1.0.0 核心功能

v1.0.1 新增功能

36 KiB

Raw Blame History