From 7f9da8aec3fe8e979b5d8b2717a78c24b9454920 Mon Sep 17 00:00:00 2001 From: wikiboss Date: Wed, 16 Sep 2026 15:26:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=9D=E5=A7=8B=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E7=BB=93=E6=9E=84=E5=B9=B6=E6=B7=BB=E5=8A=A0=E9=99=AA?= =?UTF-8?q?=E7=8E=A9=E5=B0=8F=E7=A8=8B=E5=BA=8F=E7=B3=BB=E7=BB=9F=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 31 ++ docs/陪玩小程序开发设计文档.md | 548 +++++++++++++++++++++++++++++++++ 2 files changed, 579 insertions(+) create mode 100644 .gitignore create mode 100644 docs/陪玩小程序开发设计文档.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d940ad5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,31 @@ +# Dependencies +node_modules/ +.pnpm-store/ + +# Build outputs +dist/ +build/ +unpackage/ + +# Environment variables +.env +.env.local +.env.*.local + +# Logs +logs/ +*.log +npm-debug.log* +yarn-debug.log* +pnpm-debug.log* + +# Editor & OS +.DS_Store +Thumbs.db +.vscode/ +.idea/ +*.suo +*.ntvs* +*.njsproj +*.sln +*.sw? diff --git a/docs/陪玩小程序开发设计文档.md b/docs/陪玩小程序开发设计文档.md new file mode 100644 index 0000000..6b5c46c --- /dev/null +++ b/docs/陪玩小程序开发设计文档.md @@ -0,0 +1,548 @@ +# 陪玩小程序系统开发设计文档 + +## 文档基本信息 +- **项目名称**：游戏陪玩小程序（多端互动与活动撮合平台） +- **适用端**：用户端（玩家微信小程序）、服务端（大神微信小程序，支持双身份即时无缝切换）、PC总后台管理端（Web控制台） +- **版本号**：v1.0.0 +- **编制日期**：2026-09-16 +- **设计目标**：构建集“陪玩即时撮合、预约下单、活动拼单（AA制/项目制+4位核销码）、社区动态、分销裂变、资金清算与多端运营管控”于一体的电竞陪玩社交闭环系统。 + +--- + +## 目录 +1. [项目概述与业务架构](#1-项目概述与业务架构) +2. [业务需求清单逐项分解与功能规格](#2-业务需求清单逐项分解与功能规格) +3. [重点特色业务逻辑深度设计](#3-重点特色业务逻辑深度设计) +4. [系统整体技术架构与选型](#4-系统整体技术架构与选型) +5. [数据库模型设计（ER与DDL定义）](#5-数据库模型设计er与ddl定义) +6. [核心 RESTful API 契约设计](#6-核心-restful-api-契约设计) +7. [核心业务流程与时序图](#7-核心业务流程与时序图) +8. [TDD测试驱动开发规范与实施规划](#8-tdd测试驱动开发规范与实施规划) + +--- + +## 1. 项目概述与业务架构 + +### 1.1 项目定位 +本项目致力于打造高效、合规、有趣的泛娱乐游戏陪玩与社交活动平台。系统打破传统单向买卖壁垒，实现**玩家与陪玩双身份一体化切换**，同时创新性引入**活动项目（AA制均摊与项目制发起）与线下/线上4位数字核销码签到**机制，结合二级分销海报裂变和多渠道提现审核，形成稳定的商业变现闭环。 + +### 1.2 角色权限与三端架构 +```mermaid +graph TD + User([玩家 / 大神用户]) -->|微信登录 / 一键授权| Gateway[API 网关 / 身份认证中枢] + + subgraph 小程序端 (uni-app) + PlayerUI[玩家端视图: 浏览/即时匹配/预约/发起活动/下单支付] + ExpertUI[大神端视图: 资质认证/接单工作台/发布服务/收益提现/活动核销] + end + + User -->|身份切换开关| PlayerUI + User -->|身份切换开关| ExpertUI + + subgraph PC运营总后台 (Vue3 Admin) + Admin[运营与风控管理: 用户管理/陪玩认证/服务审核/活动审核/仲裁退款/财务对账/分销设置/敏感词库] + end + + PlayerUI --> Gateway + ExpertUI --> Gateway + Admin --> Gateway + + Gateway --> ServiceCluster[核心业务服务层] + ServiceCluster --> DB[(MySQL 8.0 持久化)] + ServiceCluster --> Cache[(Redis 7.0 缓存/状态机/分布式锁)] +``` + +--- + +## 2. 业务需求清单逐项分解与功能规格 + +基于需求清单，系统划分为三大终端、三大核心角色体系共计 30+ 子功能模块： + +### 2.1 用户端（玩家端 - 微信小程序） + +| 模块分类 | 子模块 | 功能点 | 详细技术/业务规格 | +| :--- | :--- | :--- | :--- | +| **注册与登录** | 微信授权登录 | 一键获取微信昵称、头像 | 基于 `wx.getUserProfile` 或微信头像昵称快速填写组件，静默获取 openid 并注册绑定 | +| | 手机号绑定 | 绑定手机号 | 支持微信手机号快速验证组件 `getPhoneNumber` 快速绑定，保障账户资产安全性 | +| | 角色切换 | 切换至陪玩端（大神身份） | 无需重新登出，通过本地状态与后端权限校验一键平滑切换到服务端操作面板 | +| **首页与发现** | 智能推荐 | 根据历史偏好推荐陪玩 | 统计用户历史常玩游戏、常下单大神类型、常玩时段，在首页推荐位做权重加权推荐 | +| | 游戏分类 | 按游戏筛选（王者、和平等） | 热门游戏标签栏（王者荣耀、和平精英、英雄联盟等），点击分类即时无刷新更新列表 | +| | 陪玩卡片流 | 瀑布流展示头像/标签/价格 | 包含大神头像、认证大V标、擅长段位标签、每小时/每局价格、声音语音试听、当前在线状态 | +| | 搜索功能 | 关键词搜索 ID、昵称 | 支持搜索大神专属靓号ID、昵称，支持历史搜索记录及热搜关键词推荐 | +| | 筛选排序 | 按价格、评分、在线状态筛选 | 多维度组合筛选器：价格区间、评分降序、仅看当前在线、性别筛选 | +| **活动项目 (核心亮点)** | 发起活动 | AA制付费 / 项目制付费 | 1. **AA制付费**：发起人设定活动预算总额与保底参团费用，参与人平摊报名费用。
2. **项目制付费**：发起人一次性支付项目总预算，参与人可免费报名或缴纳保证金。 | +| | 报名签到 | 参与人核销码核销 | 报名人数可不设限或自定义上限；报名成功后为每个参与人生成**唯一 4 位数字核销码（如 8392）**；现场签到由活动发起人或陪玩输入/扫码完成核销。 | +| **陪玩详情** | 个人主页 | 查看技能、服务、评价 | 顶部轮播图与个人语音包播放，技能列表、荣誉勋章、历史评价综合展示 | +| | 服务列表 | 查看提供的陪玩服务明细 | 展示大神上架的具体服务包（如排位上分/局、娱乐陪练/小时、语音连麦等）及细分规则 | +| | 动态/战绩 | 查看大神发布的战绩动态 | 类似朋友圈信息流，支持图文、战绩截图，玩家可点赞、互动 | +| | 评价评分 | 查看历史服务评价与星级 | 真实交易后评价，含综合星级（1-5星）、标签（技术过硬、声音好听等）、买家评价图文 | +| **匹配与下单** | 即时匹配 | 快速匹配当前在线的陪玩 | 玩家选择游戏品类与预算区间后发起“即时派单”，系统广播给匹配范围内的在线接单中大神，先到先得或首位抢单成功进入服务 | +| | 预约下单 | 选择服务、时间、备注要求 | 选择未来服务时间段（预约日历），填写游戏区服、游戏ID、打法段位备注等 | +| | 购物车 | 多选服务合并支付 | 支持将不同服务包或叠加数量加入购物车，一次性合并拉起微信支付统一算税扣减优惠券 | +| | 订单确认 | 确认服务明细、优惠、总价 | 校验优惠券最佳抵扣、展示平台服务费与实际需支付总价 | +| **支付与财务** | 微信支付 | 小程序端调起支付 | 调起 `wx.requestPayment`，后端配置商户密钥与异步通知验签，防超卖与防重复回调 | +| | 优惠券 | 领取、使用平台优惠券 | 平台新人券、满减券、折扣券；结算时支持自动推荐最优券并计算抵扣上限 | +| | 钱包 | 余额充值、消费流水 | 玩家个人虚拟账户，支持微信充值余额；展示完整的消费、充值、活动退款流水账单 | +| **订单中心** | 订单列表 | 进行中、已完成、已取消 | 分 Tab 状态展示订单列表，带有订单倒计时（待接单倒计时、待支付倒计时） | +| | 订单详情 | 服务信息、陪玩信息、沟通入口 | 订单进度看板、双方联系方式、内置即时聊天沟通入口（IM） | +| | 订单操作 | 取消、申请退款、确认完成 | 未接单支持无损全额秒退；服务中或待确认阶段支持申请退款（需说明理由）或确认验收完成 | +| | 售后/申诉 | 提交投诉、申请平台介入 | 对服务态度恶劣、挂机、战绩造假等发起申诉工单，上传凭证截图，进入平台仲裁池 | +| **评价与信用** | 服务评价 | 订单完成后评价星级、标签 | 订单完成后触发好评/差评打分（1~5星），多维打标，计入大神综合评分权重 | +| | 举报 | 举报不良陪玩 | 针对涉黄、涉赌、线下欺诈等行为提供一键举报通道，直接冻结或标记预警 | +| **个人中心** | 资料编辑 | 修改头像、昵称、性别、签名 | 头像/昵称同步更新，接入微信文本及图片安全合规检测接口 | +| | 我的收藏 | 收藏喜欢的陪玩 | 收藏列表一览，实时高亮显示已收藏大神的在接单状态 | +| | 我的动态 | 查看自己发布的动态 | 玩家自身发布的活动动态或游戏圈子动态管理 | +| | 设置 | 隐私设置、通知开关、清除缓存 | 手机号隐藏、订单状态订阅消息订阅开关、本地Storage数据清理 | +| | 分销管理 | 分销海报/团队/佣金/提现 | 生成个人专属推荐太阳码海报；查看下级团队列表、分销订单明细、累计佣金与提现申请 | + +--- + +### 2.2 服务端 / 陪玩端（大神端 - 微信小程序） + +| 模块分类 | 子模块 | 功能点 | 详细技术/业务规格 | +| :--- | :--- | :--- | :--- | +| **注册与认证** | 微信授权登录 | 一键获取微信昵称、头像 | 统一微信账户体系注册登录 | +| | 手机号绑定 | 绑定手机号 | 实名认证与结算资金提现的前置必选条件 | +| | 角色切换 | 切换至用户端（玩家身份） | 一键切回玩家买家身份，共享同一套钱包底层账户 | +| | 实名认证 | 提交身份证信息 | 提交真实姓名、身份证号码、正反面照片，接入腾讯云人脸核身或权威第三方实名三要素验证 | +| | 基本介绍 | 自我介绍、工作业绩、资质 | 录入游戏天梯榜单荣誉、战队经历、专属语音打招呼片段（支持在线录音试听） | +| **服务管理** | 服务发布 | 创建陪玩服务（类型、价格、描述） | 录入擅长游戏品类、支持模式（排位/匹配）、计价维度（元/小时、元/局）、最高接单上限 | +| | 服务编辑 | 修改服务信息、上下架 | 随时编辑上架中的服务包，支持快捷一键“打烊下架” | +| | 服务审核 | 后台审核服务合规性 | 陪玩新发布或修改重要属性的服务，自动提交至 PC 管理后台审核，审核通过后前台展示 | +| **活动项目 (核心亮点)** | 发起活动 | AA制付费 / 项目制付费 | 大神也可主动发起“车队内战”、“线下网咖水友赛”等活动，自定义费用与分配策略 | +| | 报名签到 | 4位数字核销码核销 | **大神作为活动发起人拥有核销权限**，活动现场通过小程序输入参与人的 **4位数字核销码** 进行即时核销，确认签到并释放结算款项 | +| **个人展示** | 个人主页 | 编辑技能标签、自我介绍 | 自定义主页展示封面、高光视频/音频、擅长英雄/位置标签 | +| | 动态发布 | 发布游戏高光、战绩截图 | 支持上传多张游戏高胜率截图、段位证书图文动态 | +| | 动态管理 | 编辑、删除已发布动态 | 支持本人删除或置顶特定精选动态 | +| | 相册管理 | 上传/删除展示照片 | 个人精选生活照与电竞风写真，支持设置主封面，必须经过后台或机器合规安全过滤 | +| **接单中心** | 接单状态 | 设置在线/离线、接单开关 | 快捷开关控制：开启后进入平台派单池；关闭后前台标记为“离线/休息中”，不可发起即时匹配 | +| **订单管理** | 订单列表 | 待接单、进行中、已完成、已取消 | 收到新订单声音推送或微信服务通知；待接单支持接单或拒绝 | +| | 订单详情 | 查看玩家需求、服务信息 | 查看买家指定的游戏ID、预约时段、对局要求等 | +| | 订单操作 | 接单、开始服务、申请完成 | 状态机流转：接单 -> 点击开始服务 -> 计时/计数服务中 -> 上传结算凭证并申请完成 | +| | 预约管理 | 查看预约订单、确认时间 | 对未来时段预约订单进行时间确认排期，防日程冲突冲突检测 | +| **财务中心** | 钱包 | 查看收入余额、流水记录 | 平台抽成后净收益入账，支持查询每笔订单的服务费所得与平台服务费扣除明细 | +| | 提现 | 申请提现至银行卡/支付宝/微信 | 录入提现账号；校验平台单笔最低提现额度与单日上限；支持三种提现目标渠道 | +| | 提现记录 | 查看提现状态与历史 | 状态跟踪：待审核、处理中、已打款、已驳回（显示驳回理由） | +| | 收益统计 | 日/周/月收益图表 | 柱状图/折线图展示近7天、近4周、近6个月的接单总额、总单数及客单价走势 | +| **评价与信用** | 我的评价 | 查看玩家给的评价 | 查看买家给出的历史评分星级与具体留言，支持对评价进行感谢回复 | +| | 信用分 | 查看当前信用分与等级 | 初始基准分（如 100分），履约准时加分；拒单、超时、差评、投诉扣分；低信用限制接单 | +| | 举报处理 | 查看被举报记录与处理结果 | 透明展示自身涉诉记录与平台的最终仲裁判定意见 | +| **个人中心** | 资料编辑 | 修改头像、昵称、性别、签名 | 个人形象与展示信息维护 | +| | 认证状态 | 查看实名/资质认证进度 | 展示待审、通过、驳回状态与重提引导 | +| | 分销管理 | 分销海报/团队/佣金/提现 | 大神自带粉丝属性，具备高效分销推广能力，支持拉新玩家及下级陪玩裂变 | +| | 设置 | 接单偏好、通知开关、隐私设置 | 偏好游戏模式设置、新订单震动与提示音提醒开关 | + +--- + +### 2.3 PC总后台管理端（Web 管理系统） + +| 模块分类 | 子模块 | 功能点 | 详细技术/业务规格 | +| :--- | :--- | :--- | :--- | +| **仪表盘** | 数据概览 | 今日订单数、GMV、新增用户、活跃大神 | 关键经营指标卡片，支持与昨日、上周同期同比环比变动趋势分析 | +| | 趋势图表 | 近 7/30 天订单、收入趋势图 | 折线与面积图，展示平台 GMV 走势、实际入账抽成收益、提现规模走势 | +| | 实时监控 | 当前在线用户、进行中订单 | 实时心跳监控池，掌握当前服务中的订单热度与大神在线接单率 | +| **用户管理** | 用户列表 | 查看所有注册用户（玩家） | 条件检索（UID、手机号、注册时间、状态），查看账户信息与总消费金额 | +| | 用户详情 | 查看用户资料、订单、消费记录 | 包含用户完整履历、充值明细、订单记录、参与活动记录与被投诉历史 | +| | 用户操作 | 禁用、解禁、重置状态 | 针对恶意下单、逃单刷单用户一键封禁账号或设备 | +| **陪玩管理** | 大神列表 | 查看所有陪玩（大神） | 集中查看陪玩身份信息、服务数量、累计订单、历史评分、当前收益 | +| | 认证审核 | 实名认证、资质认证审核 | 查看身份证原图核验、游戏段位凭证截图审查、语音包试听合规校验，给予通过或驳回 | +| | 服务审核 | 陪玩发布的服务审核 | 针对新服务包的价格合理性、文字合规性进行审核控制 | +| | 等级管理 | 设置大神等级标签（优质/新晋等） | 手动或根据单量自动打标：新星大神、金牌陪练、顶流导师，并在前端享有流量倾斜 | +| | 违规处理 | 警告、限制接单、封禁 | 梯队化处罚机制：警告通知 -> 限制接单24h/7天 -> 永久下架封号 | +| **内容管理** | 动态审核 | 陪玩发布的动态审核 | 动态图片及配文审核（可对接微信内容安全API `msgSecCheck` / `mediaCheckAsync` 自动机审 + 人审拦截） | +| | 评价管理 | 查看、隐藏、删除不当评价 | 管理订单买家评价，对含有侮辱诽谤或违禁内容的评价进行隐藏或剔除 | +| | 举报处理 | 查看举报列表、处理违规 | 集中受理买家及陪玩的双向举报，支持查阅聊天凭证与对局结算图，并做违规裁决 | +| | Banner管理 | 配置首页轮播图 | 增删改查前端轮播大图、跳转链接类型（外部小程序、指定游戏分类、指定大神主页、特定活动） | +| **活动项目 (核心亮点)** | 项目列表 | 项目审核 | 审核用户或大神发起的活动项目（防发布非法聚会或赌博性质活动），通过后上架展示 | +| | 发起活动 | AA制付费 / 项目制付费 | 运营后台可直接发起平台级官方大型电竞赛事或狂欢活动，配置统一总预算或AA定价 | +| | 报名签到 | 报名人数限制/自定义/核销追踪 | 查看所有活动报名的明细名单，支持后台人工强制核销、核销状态导出对账 | +| **分销管理** | 分销设置 | 分销等级、分销佣金、团队/佣金列表 | 全局配置一级分销、二级分销佣金返点比例（如 5% / 2%）；查询上下级分销树形结构链条 | +| **订单管理** | 订单列表 | 查看全平台所有订单 | 支持按订单编号、买家ID、大神ID、订单状态、创建时间多维组合搜索全量订单 | +| | 订单详情 | 查看订单完整信息 | 查看对局时长、支付方式、优惠券减免明细、平台抽成、大神实际分润、订单日志轨迹 | +| | 仲裁处理 | 介入纠纷订单、判定责任 | 客服人工仲裁纠纷：判定全额退买家、全额扣大神、或双方按比例协商调解释放资金 | +| | 退款管理 | 审核退款申请、执行退款 | 支持系统调用微信支付退款 API 执行原路退款，资金秒级原路返还买家原账户 | +| **财务管理** | 流水记录 | 全平台交易流水 | 包含充值、支付、退款、分润、提现、服务费扣除的单式记账与双向复核账簿 | +| | 提现审核 | 大神提现申请审核 | 审核大神的提现请求，支持人工手动转账确认，或配置微信企业付款/商户零钱批量打款自动代付 | +| | 分成设置 | 平台抽成比例配置 | 全局服务费抽成比例配置（如平台固定收取 10%~20%），支持为头部明星大神设置个性化折扣费率 | +| | 对账报表 | 日/月对账报表 | 汇总生成每日/每月营收、GMV、净利润、待结算保证金、渠道手续费损耗报表，支持 Excel 一键导出 | +| **运营工具** | 优惠券管理 | 创建、发放、作废优惠券 | 配置优惠券名称、面值、满减门槛、发行总量、每人限领张数、有效起止时间、适用特定游戏品类 | +| | 活动配置 | 配置限时活动、折扣规则 | 首页首单立减、充值返送梯度规则配置 | +| | 消息推送 | 定向推送模板消息 | 基于微信服务通知模版，针对流失用户或待接单大神群发精准促活提醒 | +| **系统设置** | 全局参数 | 最低提现额度、服务费率等 | 配置提现最低门槛（如 50元起提）、提现手续费百分比、订单自动取消超时时限（如 15分钟未支付关闭） | +| | 支付配置 | 微信支付商户号配置 | 微信小程序 AppID、AppSecret、商户号 MCHID、APIv3 密钥、API证书序列号与密钥文件托管 | +| | 敏感词库 | 添加/编辑敏感词 | 聊天与个人简介违禁词过滤库，包含涉黄、涉恐、外部导流（如微信、手机号拼音缩写）自动屏蔽 | +| | 操作日志 | 管理员操作记录 | 详细记录管理员的登录IP、操作时间、变更前后的数据快照，防范内部运营风险 | +| | 权限管理 | 子管理员账号、角色权限分配 | 基于 RBAC 的权限体系，定义超级管理员、运营审核员、财务人员、客服仲裁员角色及菜单级/按钮级权限 | + +--- + +## 3. 重点特色业务逻辑深度设计 + +### 3.1 活动项目（AA制与项目制）+ 4位数字核销码架构 +这是需求清单中标绿突出的核心机制，需特别进行严密的技术与风控设计： + +```mermaid +sequenceDiagram + autonumber + actor Organizer as 发起人(玩家/大神) + actor Participant as 参与者(玩家) + participant Server as 后端服务 + participant Cache as Redis 缓存 + participant DB as MySQL 数据库 + + Organizer->>Server: 发起活动 (AA制/项目制, 总费用/单人费, 人数限制) + Server->>DB: 创建活动表记录 (状态: 待审核/招募中) + Note over Server: 后台审核通过后对外公开 + + Participant->>Server: 报名活动并拉起微信支付 + Server->>DB: 扣款成功，生成参与记录 + Server->>Cache: 随机生成唯一的 4位数字核销码 (例如: 8521) + Note over Cache: 核销码按活动ID+用户ID建立索引，设置TTL防重 + Server-->>Participant: 返回报名凭证与【4位数字核销码】 + + Note over Participant, Organizer: 线下或线上活动开始 + Participant->>Organizer: 出示 4 位数字核销码 (如 8521) + Organizer->>Server: 输入 4 位核销码提交核销验证 + Server->>Cache: 校验核销码有效性 (CAS原子校验) + alt 验证通过 + Server->>DB: 更新参与状态为【已签到/已核销】，记录核销时间 + Server->>DB: 触发费用清算逻辑 (若为AA制，将款项划入发起人或资金池) + Server-->>Organizer: 核销成功提示 + else 验证失败或已使用 + Server-->>Organizer: 提示核销码错误或已签到 + end +``` + +#### 4位数字核销码核心设计规则： +1. **码长与字符**：严格采用 **4 位纯阿拉伯数字**（`1000`~`9999`），界面支持大号字体与条形/二维码展示，极大简化线下交互操作。 +2. **唯一性与碰撞避免**： + - 4位数字空间共 9000 个（1000-9999）。在单个活动内部，参与人数通常在几十到几百人范围内，单活动内生成**绝对唯一的 4 位随机数字码**。 + - 存储结构：Redis Key 为 `act:verify:{activity_id}:{verify_code}` -> 存储 `participant_id`。 +3. **核销权限与防重机制**： + - 仅活动发起人或被授予核销权限的管理员账号有权核销该活动的核销码。 + - 验证成功后立即在同一个数据库事务中将状态从 `UNVERIFIED(0)` 变为 `VERIFIED(1)`，防止二次核销。 + +--- + +### 3.2 角色切换与双身份架构设计 +系统采用**统一账户底座 + 拓展档案**设计： +- 用户只要通过微信一键登录，在 `users` 表中生成全局唯一主键 `id`。 +- 如果用户申请成为大神并通过审核，系统在 `expert_profiles` 表建立关联记录，并赋予身份标识 `role_flags`（玩家为 1，大神为 2，双身份为 3）。 +- 前端小程序通过全局 Pinia 状态树管理当前展示形态 `current_mode: 'player' | 'expert'`。 +- 后端接口通过 JWT Payload 携带 `userId`，并在接口层根据业务场景进行拦截（如接单类接口强制校验大神档案状态必须为 `ACTIVE` 且已实名认证）。 + +--- + +### 3.3 分销裂变（二级分润）逻辑 +1. **关系绑定**：未受邀新用户通过点击带有推荐人标识 `inviter_id` 的小程序太阳码海报进入，首次登录时自动在 `distribution_relations` 表记录父子关联（终身绑定或锁粉周期）。 +2. **佣金计算**：当被邀请用户完成陪玩订单或付费活动并过了售后申诉期（如订单确认后 24 小时）后，系统触发分佣事件： + - 一级推荐人佣金：`order_amount * 平台一级比例`（如 5%） + - 二级推荐人佣金：`order_amount * 平台二级比例`（如 2%） +3. **佣金发放**：自动划入推荐人的钱包 `commission_balance` 字段，可直接申请提现。 + +--- + +## 4. 系统整体技术架构与选型 + +根据“代码必须简洁，最少量代码实现功能，能复用的尽可能复用，控制风险最小化”的开发原则，采用成熟、轻量且高生产力的全栈架构： + +```mermaid +graph LR + subgraph 表现层 + Uni[uni-app (Vue 3 + TS)] -->|微信小程序| Client[玩家/大神双端] + AdminWeb[Vite + Vue 3 + Element Plus] -->|PC后台| Admin[运营管理控制台] + end + + subgraph 服务端架构 (Node.js / NestJS) + Gateway[全局拦截/认证/限流] + ModuleUser[用户与认证模块] + ModuleOrder[订单与匹配引擎] + ModuleActivity[活动与核销模块] + ModuleFinance[钱包/分销/提现模块] + ModuleContent[动态/评价/审核模块] + end + + subgraph 基础设施层 + MySQL[(MySQL 8.0 数据持久化)] + Redis[(Redis 7.0 状态/缓存/锁)] + OSS[(腾讯云COS / 阿里云OSS 存储)] + WxPay[(微信支付 APIv3)] + end + + Client --> Gateway + Admin --> Gateway + Gateway --> ModuleUser & ModuleOrder & ModuleActivity & ModuleFinance & ModuleContent + ModuleUser & ModuleOrder & ModuleActivity & ModuleFinance & ModuleContent --> MySQL & Redis & OSS & WxPay +``` + +### 技术栈选型矩阵 +| 分层 | 技术组件 | 选型理由 | +| :--- | :--- | :--- | +| **移动客户端** | uni-app (Vue 3, TypeScript, Pinia) | 国内小程序开发标准生态，单套工程维护双端交互，生态组件库成熟 | +| **PC运营后台** | Vue 3, Vite, Element Plus, Pinia | 响应迅速，拥有现成开箱即用的后台管理模版与表单表格组件 | +| **后端服务** | Node.js (NestJS 或 Express/Koa) | TypeScript 全栈一致性，模块化强，轻量快速，天生支持高并发 I/O | +| **数据库** | MySQL 8.0 (InnoDB) | 成熟的关系型数据库，事务完整性强，支持行级锁与严密的财务结算原子操作 | +| **缓存与状态** | Redis 7.0 | 支持千万级高频读取、大神在线状态心跳、分布式锁、活动4位核销码原子校验 | +| **对象存储** | 微信云存储 / 腾讯云 COS / 阿里云 OSS | 保存大神高光战绩截图、身份证认证照片、个人写真动态 | + +--- + +## 5. 数据库模型设计（ER与DDL定义） + +系统数据库按模块划分为：**用户与认证**、**陪玩与服务**、**活动与核销**、**订单与支付**、**财务与分销**、**动态与内容安全** 六大核心领域。 + +```sql +-- 1. 用户基础表 +CREATE TABLE `users` ( + `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '用户全局主键ID', + `openid` VARCHAR(64) NOT NULL UNIQUE COMMENT '微信OpenID', + `unionid` VARCHAR(64) NULL DEFAULT NULL COMMENT '微信UnionID', + `nickname` VARCHAR(64) NOT NULL DEFAULT '微信玩家' COMMENT '用户昵称', + `avatar_url` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '头像地址', + `phone` VARCHAR(20) NULL DEFAULT NULL COMMENT '绑定手机号', + `gender` TINYINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '性别: 0未知 1男 2女', + `role_flags` TINYINT UNSIGNED NOT NULL DEFAULT 1 COMMENT '角色位图: 1=玩家, 2=大神, 3=玩家+大神', + `is_active` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '账号状态: 1正常 0封禁', + `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX `idx_phone` (`phone`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户主表'; + +-- 2. 大神资料与认证拓展表 +CREATE TABLE `expert_profiles` ( + `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + `user_id` BIGINT UNSIGNED NOT NULL UNIQUE COMMENT '关联用户ID', + `real_name` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '真实姓名', + `id_card_no` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '加密身份证号', + `cert_status` TINYINT NOT NULL DEFAULT 0 COMMENT '实名认证: 0未提交 1待审核 2已通过 3已驳回', + `reject_reason` VARCHAR(255) NULL DEFAULT '' COMMENT '审核驳回理由', + `voice_intro_url` VARCHAR(255) NULL DEFAULT '' COMMENT '语音介绍录音文件', + `voice_duration` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '语音时长(秒)', + `bio` TEXT NULL COMMENT '个人自我介绍', + `credit_score` INT NOT NULL DEFAULT 100 COMMENT '信用分(初始100)', + `level_tag` VARCHAR(32) NOT NULL DEFAULT '新晋' COMMENT '等级标签: 新晋/金牌/王者等', + `is_online` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '在线心跳状态: 1在线 0离线', + `accept_orders` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '接单总开关: 1开启 0关闭', + `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='大神拓展档案'; + +-- 3. 大神发布的服务表 +CREATE TABLE `expert_services` ( + `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + `expert_id` BIGINT UNSIGNED NOT NULL COMMENT '大神用户ID', + `game_category` VARCHAR(32) NOT NULL COMMENT '游戏类别(王者荣耀/和平精英等)', + `title` VARCHAR(64) NOT NULL COMMENT '服务标题', + `price_cents` INT UNSIGNED NOT NULL COMMENT '单价(分)', + `price_unit` VARCHAR(16) NOT NULL DEFAULT '小时' COMMENT '单位: 小时/局', + `description` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '服务说明', + `audit_status` TINYINT NOT NULL DEFAULT 1 COMMENT '审核状态: 0待审核 1审核通过 2已拒绝', + `is_listed` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '上下架: 1上架 0下架', + `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX `idx_expert_game` (`expert_id`, `game_category`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='大神陪玩服务项目'; + +-- 4. 活动项目表 (核心特色: AA制与项目制) +CREATE TABLE `activities` ( + `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + `creator_id` BIGINT UNSIGNED NOT NULL COMMENT '发起人用户ID', + `title` VARCHAR(128) NOT NULL COMMENT '活动标题', + `game_category` VARCHAR(32) NOT NULL COMMENT '关联游戏/主题', + `pay_type` TINYINT NOT NULL COMMENT '付费方式: 1=AA制付费, 2=项目制付费', + `total_fee_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '活动总预算/项目制费用(分)', + `aa_fee_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 'AA制每人报名费用(分)', + `max_participants` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '人数限制(0为不限人数)', + `current_participants` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '当前已报名人数', + `start_time` DATETIME NOT NULL COMMENT '活动开始时间', + `end_time` DATETIME NOT NULL COMMENT '活动结束时间', + `location_type` TINYINT NOT NULL DEFAULT 1 COMMENT '地点类型: 1线上 2线下网咖/场地', + `location_detail` VARCHAR(255) NULL DEFAULT '' COMMENT '详细地址或语音房间号', + `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态: 0待审核 1招募中 2进行中 3已结单 4已取消', + `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX `idx_creator` (`creator_id`), + INDEX `idx_status` (`status`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='活动项目主表'; + +-- 5. 活动报名参与与 4 位核销码表 +CREATE TABLE `activity_participants` ( + `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + `activity_id` BIGINT UNSIGNED NOT NULL COMMENT '关联活动ID', + `user_id` BIGINT UNSIGNED NOT NULL COMMENT '报名用户ID', + `verify_code` CHAR(4) NOT NULL COMMENT '4位数字签到核销码(如 8392)', + `pay_status` TINYINT NOT NULL DEFAULT 0 COMMENT '支付状态: 0待支付 1已支付 2已退款', + `pay_amount_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '实付金额(分)', + `checkin_status` TINYINT NOT NULL DEFAULT 0 COMMENT '核销状态: 0未核销 1已核销', + `checkin_time` DATETIME NULL DEFAULT NULL COMMENT '核销签到时间', + `verified_by` BIGINT UNSIGNED NULL DEFAULT NULL COMMENT '核销人用户ID', + `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + UNIQUE KEY `uk_act_user` (`activity_id`, `user_id`), + UNIQUE KEY `uk_act_code` (`activity_id`, `verify_code`), + INDEX `idx_user` (`user_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='活动参与与核销明细'; + +-- 6. 陪玩服务订单主表 +CREATE TABLE `orders` ( + `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + `order_sn` VARCHAR(32) NOT NULL UNIQUE COMMENT '全局业务订单号', + `user_id` BIGINT UNSIGNED NOT NULL COMMENT '玩家买家ID', + `expert_id` BIGINT UNSIGNED NOT NULL COMMENT '接单陪玩大神ID', + `service_id` BIGINT UNSIGNED NOT NULL COMMENT '所选服务包ID', + `order_type` TINYINT NOT NULL DEFAULT 1 COMMENT '订单类型: 1即时单 2预约单', + `status` TINYINT NOT NULL DEFAULT 1 COMMENT '状态: 1待付款 2待接单 3服务中 4待确认 5已完成 6已取消 7退款仲裁中 8已退款', + `quantity` INT UNSIGNED NOT NULL DEFAULT 1 COMMENT '购买数量(小时或局数)', + `total_amount_cents` INT UNSIGNED NOT NULL COMMENT '订单总金额(分)', + `coupon_discount_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '优惠券减免(分)', + `pay_amount_cents` INT UNSIGNED NOT NULL COMMENT '用户实付金额(分)', + `platform_fee_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '平台抽成服务费(分)', + `expert_income_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '大神净收入(分)', + `scheduled_start_time` DATETIME NULL COMMENT '预约开始时间', + `service_start_time` DATETIME NULL COMMENT '实际开始服务时间', + `service_end_time` DATETIME NULL COMMENT '服务完成时间', + `cancel_reason` VARCHAR(255) NULL DEFAULT '' COMMENT '取消理由', + `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX `idx_user_status` (`user_id`, `status`), + INDEX `idx_expert_status` (`expert_id`, `status`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='陪玩服务交易主订单'; + +-- 7. 用户钱包与资产账户 +CREATE TABLE `wallets` ( + `user_id` BIGINT UNSIGNED PRIMARY KEY COMMENT '关联用户ID', + `balance_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '可用余额(分)', + `frozen_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '冻结中资金(分)', + `commission_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '分销佣金收益(分)', + `total_income_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '历史累计总收益(分)', + `version` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '乐观锁版本号', + `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户资产钱包'; + +-- 8. 提现申请记录表 +CREATE TABLE `withdraw_requests` ( + `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + `user_id` BIGINT UNSIGNED NOT NULL, + `amount_cents` INT UNSIGNED NOT NULL COMMENT '提现金额(分)', + `fee_cents` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '平台提相手续费(分)', + `channel` TINYINT NOT NULL COMMENT '渠道: 1微信零钱 2支付宝 3银行卡', + `account_info` JSON NOT NULL COMMENT '打款账号与收款人姓名', + `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态: 0待审核 1处理中/打款中 2已完成 3已驳回', + `reject_reason` VARCHAR(255) NULL DEFAULT '', + `transfer_trade_no` VARCHAR(64) NULL DEFAULT '' COMMENT '第三方打款回执流水号', + `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX `idx_user` (`user_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='提现流水申请表'; + +-- 9. 二级分销关系与分润记录表 +CREATE TABLE `distribution_relations` ( + `user_id` BIGINT UNSIGNED PRIMARY KEY COMMENT '被推荐人ID', + `parent_id` BIGINT UNSIGNED NOT NULL COMMENT '直接上级推荐人ID', + `grandparent_id` BIGINT UNSIGNED NULL DEFAULT NULL COMMENT '间接上级推荐人ID', + `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + INDEX `idx_parent` (`parent_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='分销裂变层级绑定'; +``` + +--- + +## 6. 核心 RESTful API 契约设计 + +### 6.1 用户与认证相关接口 +- `POST /api/v1/auth/wechat-login`：微信小程序登录换取 Token（返回 openid、userId、token、当前角色身份标志）。 +- `POST /api/v1/auth/bind-phone`：绑定手机号（解析微信加密手机号向量）。 +- `POST /api/v1/user/switch-role`：切换当前工作角色（`role: 'player' | 'expert'`）。 + +### 6.2 陪玩服务与即时匹配接口 +- `GET /api/v1/experts/list`：首页瀑布流列表（支持按游戏、价格区间、评分、在线状态分页检索）。 +- `GET /api/v1/experts/:id/detail`：获取陪玩大神主页详情（包含服务项目列表、个人战绩动态、历史评价与星级）。 +- `POST /api/v1/match/instant`：即时匹配发起（提交游戏品类与意向要求，系统自动分派并进入撮合会话）。 +- `POST /api/v1/expert/status`：大神设置在线接单状态（切换接单开关，上报心跳）。 + +### 6.3 活动项目与 4 位核销码核心接口 +- `POST /api/v1/activities/create`：发起活动项目。 + - **请求体**： + ```json + { + "title": "王者荣耀S30开黑冲星车队", + "game_category": "王者荣耀", + "pay_type": 1, // 1=AA制, 2=项目制 + "total_fee_cents": 20000, + "aa_fee_cents": 5000, + "max_participants": 4, + "start_time": "2026-09-20 19:00:00", + "location_type": 1 + } + ``` +- `POST /api/v1/activities/:id/join`：报名参加活动，返回预支付订单参数。 +- `GET /api/v1/activities/:id/my-ticket`：查看我的活动门票凭证（返回 **4 位纯数字核销码 `verify_code`**，如 `6729`）。 +- `POST /api/v1/activities/:id/verify-code`：发起人/管理员现场核销签到接口。 + - **请求体**：`{ "verify_code": "6729" }` + - **返回**：`{ "code": 200, "message": "核销成功", "participant": { "userId": 1024, "nickname": "张小凡", "verifiedAt": "..." } }` + +### 6.4 订单中心与交易接口 +- `POST /api/v1/orders/create`：提交预约下单/即时下单。 +- `POST /api/v1/orders/:id/pay`：调起微信支付拉起参数签名。 +- `POST /api/v1/expert/orders/:id/accept`：大神接单。 +- `POST /api/v1/expert/orders/:id/start`：大神开始服务。 +- `POST /api/v1/expert/orders/:id/complete`：大神提交服务完成凭据。 +- `POST /api/v1/orders/:id/confirm`：买家确认完成并评价。 +- `POST /api/v1/orders/:id/dispute`：申请仲裁/退款投诉。 + +### 6.5 财务提现与分销管理接口 +- `GET /api/v1/wallet/overview`：查询钱包余额、分销佣金、可提现额度。 +- `POST /api/v1/wallet/withdraw`：提交提现申请（选择渠道、提现金额）。 +- `GET /api/v1/distribution/my-team`：查看分销团队成员与累计贡献佣金。 +- `GET /api/v1/distribution/poster`：生成专属带参小程序二维码推广海报。 + +--- + +## 7. 核心业务流程与时序图 + +### 7.1 陪玩服务全生命周期状态流转 +```mermaid +stateDiagram-v2 + [*] --> 待付款: 玩家下单 + 待付款 --> 已取消: 15分钟超时未支付 / 玩家主动取消 + 待付款 --> 待接单: 微信支付成功 + 待接单 --> 服务中: 大神接单 + 待接单 --> 已退款: 大神拒单 / 30分钟超时未接单(自动退款) + 服务中 --> 待确认: 大神点击申请完成服务 + 待确认 --> 已完成: 买家确认完成 / 48小时自动确认 + 待确认 --> 仲裁争议中: 买家提出异议与退款申请 + 仲裁争议中 --> 已退款: 客服判定全额或部分退款 + 仲裁争议中 --> 已完成: 客服驳回争议款项划入大神 + 已完成 --> [*]: 买家评价 & 资金解冻结算到钱包 +``` + +--- + +## 8. TDD测试驱动开发规范与实施规划 + +本项目严格遵循 **TDD（Test-Driven Development）** 流程开发，实现代码整洁、模块单一、高复用与低风险： + +### 8.1 TDD 核心三步闭环 +```mermaid +graph LR + Red[1. 编写失败的测试用例 Red] --> Green[2. 编写最简实现代码 Green] + Green --> Refactor[3. 代码重构与清理 Refactor] + Refactor --> Red +``` + +1. **红灯阶段（Red）**：针对每个业务用例（如 4 位核销码生成不重复、AA制平摊费用计算、订单状态机合法流转校验），先编写 Unit Test，执行并断言其失败。 +2. **绿灯阶段（Green）**：用最简单、最少量的代码让测试通过，绝不编写超出测试范围的额外冗余代码。 +3. **重构阶段（Refactor）**：在全部测试保持绿灯的前提下，消除重复代码，优化命名与设计模式，保障代码干净无异味。 + +### 8.2 必须覆盖的核心自动化测试套件 +1. **核销码生成与校验套件（ActivityVerifyServiceSpec）**： + - 验证单活动内随机 4 位数字核销码生成，1000 次生成无重复。 + - 验证正确核销码核销一次成功，二次核销报错阻止。 + - 验证非活动发起人无权执行核销。 +2. **费用与分佣计算套件（FinanceCommissionSpec）**： + - 验证 AA 制费用计算四舍五入精度问题，确保参与者费用总和等于活动总额。 + - 验证一级（5%）、二级（2%）分销佣金精度计算，避免浮点数精度丢失。 + - 验证优惠券抵扣上限与实际支付金额不可为负数。 +3. **订单状态机防并发套件（OrderStateMachineSpec）**： + - 模拟并发接单场景（Redis 分布式锁验证，同一单绝不允许两位陪玩同时抢单成功）。 + - 模拟重复支付回调场景（验证幂等性，不重复入账）。