【壹软V6MAX】全开源盲盒系统/Uniapp前端+PHP后端/一番赏+爬塔+排名榜+无限赏-济南壹软网络科技

授权版本6999元开源源码出售18888元不议价
V6MAX盲盒演示站点：前端：http://v6maxh5.mh.50api.cn
后端https://v6max.mh.50api.cn/yiruanyun/login/index admin 123456
如果需要定制上架APP，需要先采购开源源码，然后设计一套UI，前端进行开发后才可以上架总费用明细如下：开源源码18888+UI全套3000+前端开发7000+安卓上架5家商城2000=30888元
多元玩法集成：融合月榜竞赛、每日福梨、对对碰、领主赏、无尽塔等多种互动模式。
榜单激励体系：设有九月月榜等排名奖励，展示前三名等玩家成就及A赏抽取结果。
活动入口矩阵：集成口令红包、福梨池、排行榜等入口，搭配紧凑的蓝紫渐变视觉设计。
商品推荐模块：热门推荐福袋（如LABUBU系列）、福梨车等商品，即时开启功能。
导航与分类：底部导航首页、商城、福梨房、仓库及个人中心，支持一番赏、无限赏

V6MAX企业商用盲盒系统 – 功能详解与介绍

一、系统概述

V6MAX 是一款功能强大、玩法多样的企业级商用盲盒系统源码。系统采用 Uniapp前端 + PHP后端的技术架构，一次开发可同时发布至App、微信小程序、H5网页端，助力企业快速搭建属于自己的多元化盲盒电商平台。系统核心特色在于集成了八大主流盲盒玩法，并配备了完善的用户运营工具，不仅满足了用户的新鲜感和刺激感，更为运营者提供了丰富的营销和盈利手段。

二、核心功能模块详解

1. 用户与入口

多端登录适配：微信小程序/H5端：支持微信授权一键登录，快速获取用户头像、昵称及手机号。 App端：支持手机号验证码登录，体验流畅。
首页门户：品牌展示：左上角自定义Logo，强化品牌形象。运营位：顶部Banner轮播图，支持配置跳转至活动页或特定盲盒。弹窗公告：启动弹窗功能，用于发布重要公告或引导用户参与活动。内容推荐：具备“热门推荐”、“福袋盲盒”等专属板块，支持后台灵活配置，精准引流。

2. 八大核心盲盒玩法

系统内置了八种截然不同的盲盒模式，满足多样化运营需求。

1. 一番赏玩法介绍：源自日本的经典玩法。每套盲盒设有固定数量和品质的奖品（如A赏、B赏）。核心机制：全透明：实时公示奖池库存、奖品品质和概率，公平公正。排队抽取：用户需先排队，按顺序抽取，抽中奖品后库存相应减少。终结赏：当奖池只剩一件奖品时，抽取者将获得“终结赏”奖励，极具吸引力。
2. 福袋盲盒玩法介绍：一番赏的变种玩法，增加了趣味性。核心机制：在保留一番赏全透明和排队机制的基础上，允许用户自主选择福袋号码进行抽取，满足用户的偏好选择。
3. 无限赏（无限池）玩法介绍：类似泡泡玛特的常规盲盒模式。奖池不设上限，概率恒定。核心机制：保底机制：后台可设置“N抽必中某品质奖品”，保障用户体验，避免极端非酋情况。适合作为平台的基础和主流抽盒模式。
4. 爬塔盲盒玩法介绍：融合了RPG爬塔成长元素的玩法，过程充满悬念。核心机制：塔层结构：盲盒与塔层绑定，登顶即可获得大奖。概率可控：后台可自定义“上升一层”、“维持原层”、“下降一层”的概率。排名激励：设有爬塔排名榜，展示用户冲顶次数，激发竞争欲。
5. 擂台赏玩法介绍：双人实时对战模式，增强互动性与刺激性。核心机制：双方PK：用户选择一方（如黄/绿阵营）下注，等待对手加入。随机判定：系统随机判定胜负，赢家获得实物奖品，输家获得幸运币补偿，参与即有奖。
6. 对对碰玩法介绍：结合了“消消乐”游戏规则的趣味玩法，通常与直播拆盒结合。核心机制：许愿对碰：用户从9个赏品中选择1个作为“许愿赏品”。循环消除：在场上寻找并消除相同赏品，系统会补充新赏品，直至无法消除。次数奖励：根据成功对碰的次数，发放对应等级的奖品。
7. 领主赏玩法介绍：带有社交和“收租”元素的玩法，增加用户粘性。核心机制：争夺领主：用户抽中“领主证明”即可成为当前盲盒的“领主”。被动收益：在24小时的领主任期内，其他用户抽取该盲盒时，领主都能获得幸运币奖励。身份更替：领主身份可被新抽中证明的用户顶替，鼓励持续参与。
8. 福赏（活动营销）玩法介绍：不是一个独立的玩法，而是一套营销活动工具集。核心机制：福池：消费满额即可免费领取奖品，刺激消费。限时活动：支持“每日限定”、“聚划算”、“N倍赠送”、“首单优惠”、“买N送N”等多种促销模式。新人专享：如“0.01元首抽”、“新人买一送一”等，有效拉新。

3. 福房系统

这是一个独立的多人互动开奖模块，分为三种类型：

官方福房：由平台创建，支持“满人即开”或“定时开奖”。
主播福房：授权主播创建，需后台审核，增强平台内容生态。
用户福房：普通用户可创建“定时开奖”房间，放入自有奖品（高价值奖品需审核），促进用户间互动和奖品流通。

4. 运营与营销工具

口令红包：用户可生成专属口令红包，分享给好友。好友复制口令后打开App即可领取。支持短链、防刷机制（如限制用户ID领取），是低成本裂变传播的利器。
荣誉殿堂（排名榜）：设有日榜、周榜等消费排行榜。仅计入现金消费，排名靠前的用户可获得额外奖品，刺激头部用户消费。

5. 支付与资产

支付方式：集成微信支付、支付宝等主流官方支付渠道。
双货币体系：余额：与现金按10：1比例兑换，用于抽、购买商品等核心消费。幸运币：通过活动、奖励、任务等方式获得，用于参与特定活动（如擂台赏）等。

三、系统特点与优势总结

玩法全覆盖：一站式集成市面上主流的8种盲盒玩法，无需二次开发，开箱即用。
技术架构先进：采用流行的Uniapp+PHP组合，多端兼容，维护成本低，扩展性强。
透明度与公平性：核心玩法均强调奖池、概率、库存的透明化，建立用户信任。
强运营属性：内置丰富的营销活动（福赏、红包、排名榜）和互动模块（福房），助力用户增长与留存。
高灵活性：各种玩法的规则、概率、奖品均可通过后台详细配置，适应不同的运营策略。

V6MAX 潮玩盲盒商城
基于 ThinkPHP 6 的多玩法潮玩盲盒电商平台后端，支持一番赏、对对碰、福袋、擂台赏、领主赏等多种盲盒玩法，集成多渠道支付、分销推广、排行榜等运营能力。

# V6MAX 潮玩盲盒商城 

> 基于 ThinkPHP 6 的多玩法潮玩盲盒电商平台后端，支持一番赏、对对碰、福袋、擂台赏、领主赏等多种盲盒玩法，集成多渠道支付、分销推广、排行榜等运营能力。

---

## 目录

- [1. 项目简介](#1-项目简介-project-overview)
- [2. 项目架构与目录结构](#2-项目架构与目录结构-architecture)
- [3. 接口文档](#3-接口文档-api-documentation)
  - [3.1 认证模块 (Login)](#31-认证模块-login)
  - [3.2 会员模块 (Member)](#32-会员模块-member)
  - [3.3 盲盒模块 (BlindBox)](#33-盲盒模块-blindbox)
  - [3.4 支付模块 (Pay)](#34-支付模块-pay)
  - [3.5 订单模块 (Order)](#35-订单模块-order)
  - [3.6 通用模块 (Common)](#36-通用模块-common)
  - [3.7 排行榜模块 (Rank)](#37-排行榜模块-rank)
  - [3.8 奖品记录模块 (PrizeRecord)](#38-奖品记录模块-prizerecord)
  - [3.9 支付回调 (Notify)](#39-支付回调-notify)
  - [3.10 其他模块](#310-其他模块)
  - [3.11 后台管理 (Admin)](#311-后台管理-admin)
  - [3.12 商户端 (Merchant)](#312-商户端-merchant)
- [4. 快速开始](#4-快速开始-getting-started)
- [5. 定时任务](#5-定时任务-scheduled-commands)
- [6. 功能更新日志](#6-功能更新日志)

---

## 1. 项目简介 (Project Overview)

V6MAX 潮玩盲盒商城是一个面向 C 端用户的潮玩盲盒电商平台后端服务。平台提供多种盲盒玩法（一番赏、对对碰、福袋、擂台赏、领主赏等），用户可通过 H5 / 微信小程序 / APP 多端访问。

### 核心功能

| 功能域 | 说明 |
|--------|------|
| **盲盒玩法** | 一番赏、无限赏、对对碰（配对碰撞）、福袋、擂台赏（PK）、领主赏、爬塔等 |
| **商品与订单** | 商品展示、下单购买、卡密发货、物流跟踪 |
| **支付体系** | 微信支付（小程序/H5/APP）、支付宝、易支付、聚合支付、汇付、余额、积分（多多币） |
| **会员体系** | 注册登录、实名认证、签到奖励、任务中心、等级消费 |
| **仓库与奖品** | 奖品管理、兑换回收、转赠、申请发货、保险箱 |
| **运营工具** | 排行榜（日/周）、分销推广、口令红包、优惠券、福利房、专题活动 |
| **后台管理** | 盲盒 / 商品 / 订单 / 会员 / 统计 / 配置全面管理 |

### 技术栈

| 类别 | 技术 |
|------|------|
| **语言** | PHP >= 7.1 |
| **框架** | ThinkPHP 6（多应用模式） |
| **数据库** | MySQL 5.6+（表前缀 `xn_`） |
| **缓存** | Redis / File |
| **认证** | JWT（`thans/tp-jwt-auth`） |
| **文件存储** | 阿里云 OSS / 七牛云 |
| **短信** | 短信宝 |
| **支付 SDK** | 微信支付 / 支付宝 / 易支付 / 聚合支付 / 汇付 |
| **其他** | 阿里云实名认证、快递100物流查询、PHPExcel、淘宝开放平台 |

---

## 2. 项目架构与目录结构 (Architecture)

```
v6max/
├── app/                              # 应用主目录
│   ├── admin/                        # 后台管理应用
│   │   ├── config/route.php          #   路由配置（AdminCheck 中间件）
│   │   ├── controller/               #   后台控制器
│   │   ├── middleware/AdminCheck.php  #   登录 & 安全码校验
│   │   └── view/                     #   后台视图模板（HTML）
│   ├── api/                          # API 应用（前端 H5/小程序/APP 调用）
│   │   ├── config/route.php          #   路由配置（跨域中间件）
│   │   ├── controller/               #   API 控制器
│   │   └── middleware/
│   │       ├── AllowCrossDomain.php  #   跨域处理
│   │       └── Jwt.php               #   JWT 认证 & Token 刷新
│   ├── index/                        # 前台入口应用
│   │   ├── controller/               #   前台控制器
│   │   └── middleware/TemplateCheck   #   模板切换中间件
│   ├── merchant/                     # 商户/分销端
│   │   ├── controller/               #   商户控制器
│   │   └── view/                     #   商户端视图
│   ├── common/                       # 公共模块
│   │   ├── controller/               #   基类控制器
│   │   │   ├── ApiBase.php           #     API 基类（认证、响应封装）
│   │   │   ├── AdminBase.php         #     后台基类（RBAC、权限）
│   │   │   └── MerchantBase.php      #     商户基类
│   │   ├── model/                    #   数据模型（ORM）
│   │   └── lib/                      #   工具库
│   │       ├── Pay/                  #     支付集成（13 种支付方式）
│   │       ├── Sms/Duanxinbao.php    #     短信服务
│   │       ├── Oss.php               #     阿里云 OSS
│   │       ├── Qiniu.php             #     七牛云存储
│   │       ├── WxLogin.php           #     微信登录
│   │       └── PairMatchLogger.php   #     对对碰日志
│   ├── command/                      # CLI 定时任务命令
│   ├── lang/                         # 多语言包（zh-cn / en-us）
│   ├── common.php                    # 全局辅助函数
│   └── middleware.php                # 全局中间件注册
├── config/                           # 全局配置
│   ├── database.php                  #   数据库配置
│   ├── cache.php                     #   缓存配置（File / Redis）
│   ├── jwt.php                       #   JWT 配置
│   ├── console.php                   #   CLI 命令注册
│   └── ...                           #   其他框架配置
├── public/                           # Web 根目录（对外暴露）
│   ├── index.php                     #   HTTP 入口
│   └── static/                       #   静态资源
├── route/app.php                     # 全局路由
├── extend/                           # 第三方扩展
├── vendor/                           # Composer 依赖
├── .env                              # 环境变量配置
├── composer.json                     # PHP 依赖声明
└── think                             # ThinkPHP CLI 入口
```

### 路由规则

项目使用 ThinkPHP 默认路由模式，URL 格式为：

```
/{应用名}/{控制器}/{方法}
```

示例：`/api/member/get_user_info` → `app\api\controller\Member::get_user_info()`

### 中间件体系

| 层级 | 中间件 | 作用 |
|------|--------|------|
| 全局 | `SessionInit` | Session 初始化 |
| 全局 | `Check` | 动态后台 URL 映射 |
| API 应用 | `AllowCrossDomain` | 跨域请求处理 |
| API 控制器 | `Jwt` | JWT Token 认证、自动刷新、注入 `member_id` |
| Admin 应用 | `AdminCheck` | 管理员登录校验、安全码验证 |
| Index 应用 | `TemplateCheck` | 前台模板切换 |

---

## 3. 接口文档 (API Documentation)

> 基础路径：`/api`  
> 认证方式：JWT Bearer Token（Header: `Authorization: Bearer {token}`）  
> 通用响应格式：`{ "code": 1, "msg": "success", "data": {...} }`  
> 多语言：请求参数或 Header 中传递 `lang=en-us` / `lang=zh-cn`

### 3.1 认证模块 (Login)

**Endpoint 前缀**：`/api/login`  
**认证要求**：无需 Token

| 接口名称 | Method | Endpoint | 关键参数 | 功能描述 |
|----------|--------|----------|----------|----------|
| 发送短信验证码 | POST | `/api/login/send_sms` | `mobile`, `event` | 发送手机短信验证码 |
| 号码认证获取手机号 | POST | `/api/login/getMobile` | `token` | 通过运营商一键登录 Token 获取手机号 |
| 手机号登录/注册 | POST | `/api/login/mobile_login` | `mobile`, `code`, `pid` | 短信验证码登录，新用户自动注册 |
| 微信小程序登录 | POST | `/api/login/mp_wechat_login` | `code`, `nickName`, `share_ma` | 小程序 `wx.login` code 换取登录态 |
| 获取小程序手机号 | POST | `/api/login/get_mp_wechat_phone` | `code` | 小程序获取用户手机号 |
| APP 微信登录 | POST | `/api/login/get_wechat_info_by_app` | `code`, `share_ma` | APP 端微信授权登录 |
| H5 微信登录 | GET | `/api/login/h5_wx_login` | `code`, `openid`, `share_ma` | H5 端微信 OAuth 登录 |
| 退出登录 | POST | `/api/login/logout` | `token` | 注销当前 Token |

---

### 3.2 会员模块 (Member)

**Endpoint 前缀**：`/api/member`  
**认证要求**：JWT Token（全部接口）

| 接口名称 | Method | Endpoint | 关键参数 | 功能描述 |
|----------|--------|----------|----------|----------|
| 获取用户信息 | GET | `/api/member/get_user_info` | — | 返回当前用户完整信息 |
| 修改个人信息 | POST | `/api/member/change_info` | `image`, `nickname` | 修改头像和昵称 |
| 绑定手机号 | POST | `/api/member/bind_mobile` | `mobile`, `code` | 绑定 / 更换手机号 |
| 绑定邀请码 | POST | `/api/member/bind_invite_code` | `invite_code` | 绑定上级推广码 |
| 获取实名认证状态 | GET | `/api/member/get_real_name_status` | — | 查询实名认证状态 |
| 提交实名认证 | POST | `/api/member/update_real_name_status` | `real_name`, `real_id_card`, `certify_id` | 提交身份证实名信息 |
| 获取银行卡信息 | GET | `/api/member/get_my_bank` | — | 查询已绑定银行卡 |
| 申请提现 | POST | `/api/member/withdrawal` | `number`, `bank_fullname`, `bank_card`, `bank_type` | 余额提现申请 |
| 提现记录 | GET | `/api/member/withdrawal_log` | `page`, `limit` | 分页查询提现记录 |
| 资金变动日志 | GET | `/api/member/money_log` | `type`, `page`, `change_type`, `year_month` | 余额/积分/佣金变动流水 |
| 今日消费 | GET | `/api/member/get_day_money` | — | 查询当日消费金额 |
| 我的优惠券 | GET | `/api/member/get_my_coupon` | — | 查询已领取优惠券 |
| 领取优惠券 | POST | `/api/member/receive_coupon` | `cid`, `a_type` | 领取指定优惠券 |
| 查询可用优惠券 | GET | `/api/member/find_coupon` | `box_id`, `price` | 根据盲盒和价格查可用券 |
| 收货地址列表 | GET | `/api/member/my_address` | — | 获取用户收货地址 |
| 添加收货地址 | POST | `/api/member/add_address` | `fullname`, `mobile`, `province`, `city`, `area`, `detailed`, `is_default` | 新增收货地址 |
| 编辑收货地址 | POST | `/api/member/edit_address` | `address_id`, `fullname`, `mobile`, ... | 修改收货地址 |
| 删除收货地址 | POST | `/api/member/delete_address` | `address_id` | 删除收货地址 |
| 获取单条地址 | GET | `/api/member/get_address` | `address_id` | 获取单条地址详情 |
| 每日签到 | POST | `/api/member/qiandao` | — | 执行每日签到领取奖励 |
| 获取签到配置 | GET | `/api/member/get_qiandao_set_list` | — | 签到规则及奖励配置 |
| 兑换 CDKEY | POST | `/api/member/cdkey` | `kahao` | 输入卡号兑换奖励 |
| 获取分享配置 | GET | `/api/member/get_share_config` | — | 分享奖励规则 |
| 分享奖励 | POST | `/api/member/share` | `share_type` | 分享成功后领取奖励 |
| 我的团队 | GET | `/api/member/get_my_team` | `type`, `page` | 查看推广下级列表 |
| 推广记录 | GET | `/api/member/get_popularize_log` | `page` | 推广佣金记录 |
| 系统通知 | GET | `/api/member/get_notice` | — | 获取通知列表 |
| 通知详情 | GET | `/api/member/get_notice_info` | `id` | 查看通知详情 |
| 一键已读通知 | POST | `/api/member/set_allread_notice` | — | 标记所有通知已读 |
| 任务中心 | POST | `/api/member/get_task_info` | `task_id`, `type` | 查看 / 解锁每日任务 |
| 小程序邀请二维码 | GET | `/api/member/get_wxamp_share_qrcode` | — | 生成小程序分享海报二维码 |
| 注销账号 | POST | `/api/member/logoff` | — | 永久注销账号 |

---

### 3.3 盲盒模块 (BlindBox)

**Endpoint 前缀**：`/api/blind_box`  
**认证要求**：部分接口需要 JWT Token（标注 🔒）

| 接口名称 | Method | Endpoint | 关键参数 | 功能描述 |
|----------|--------|----------|----------|----------|
| 🔒 开启盲盒抽奖 | POST | `/api/blind_box/open` | `order_no` | 根据订单号执行开盒抽奖 |
| 🔒 对对碰-选择心愿商品 | POST | `/api/blind_box/choose_wish_goods` | `goods_id`, `box_id` | 对对碰选择想要的商品 |
| 对对碰-获取商品池 | GET | `/api/blind_box/get_pair_match_box_goods` | `record_id`, `box_id` | 获取当前对对碰商品池 |
| 🔒 对对碰-执行碰撞 | POST | `/api/blind_box/pair_box_collision` | `record_id`, `positions` | 执行配对碰撞翻牌 |
| 🔒 对对碰-开启心愿卡 | POST | `/api/blind_box/open_wish_card` | `record_id` | 使用心愿卡直接获得商品 |
| 一番赏-获取箱列表 | GET | `/api/blind_box/get_yfs_box_xiang_list` | `blind_box_id` | 获取一番赏所有箱号 |
| 一番赏-获取盒子详情 | GET | `/api/blind_box/get_yfs_box_detail` | `blind_box_id`, `xiang_number` | 获取指定箱的剩余商品 |
| 福袋-获取列表 | GET | `/api/blind_box/get_fukubukuro_list` | — | 福袋活动列表 |
| 福袋-获取详情 | GET | `/api/blind_box/get_fukubukuro_detail` | `blind_box_id`, `xiang_number` | 福袋详情信息 |
| 福袋-获取箱列表 | GET | `/api/blind_box/get_fukubukuro_box_xiang_list` | `blind_box_id` | 福袋箱号列表 |
| 福袋-购买记录 | GET | `/api/blind_box/get_fukubukuro_purchase_record` | `blind_box_id`, `xiang_number` | 福袋某箱购买记录 |
| 获取挑战者数量 | GET | `/api/blind_box/get_challengers_count` | `blind_box_id` | 擂台赏挑战人数 |
| 获取保底商品列表 | GET | `/api/blind_box/box_match_guarantee_goods` | `blind_box_id` | 对对碰保底商品池 |
| 🔒 加入排队 | POST | `/api/blind_box/join_queue` | `blind_box_id`, `xiang_number` | 一番赏/福袋排队购买 |
| 🔒 取消排队 | POST | `/api/blind_box/cancel_queue` | `blind_box_id`, `xiang_number` | 取消排队 |
| 查询排队状态 | GET | `/api/blind_box/get_queue_status` | `blind_box_id`, `xiang_number` | 查看当前排队位置 |
| 🔒 锁定箱子 | POST | `/api/blind_box/lock_box` | `blind_box_id`, `xiang_number` | 紧急暂停箱子 |
| 🔒 解锁箱子 | POST | `/api/blind_box/unlock_box` | `blind_box_id`, `xiang_number` | 恢复箱子可购买 |

---

### 3.4 支付模块 (Pay)

**Endpoint 前缀**：`/api/pay`  
**认证要求**：大部分需要 JWT Token

| 接口名称 | Method | Endpoint | 关键参数 | 功能描述 |
|----------|--------|----------|----------|----------|
| 🔒 盲盒购买支付 | POST | `/api/pay/go_pay` | `boxid`, `num`, `paymode`, `client`, `xiang_number`, `fukubukuro_numbers` | 创建盲盒支付订单 |
| 🔒 获取盲盒价格 | POST | `/api/pay/get_box_price` | `boxid`, `num`, `paymode`, `is_pk`, `xiang_number` | 计算盲盒价格（含优惠） |
| 🔒 新人专享支付 | POST | `/api/pay/newer_pay` | `source`, `blind_box_id`, `zid`, `couponid`, `paymode` | 新用户专属优惠购买 |
| 🔒 商品购买入仓库 | POST | `/api/pay/buy_goods_to_warehouse` | `goods_id`, `num`, `paymode`, `client` | 购买商品存入仓库 |
| 🔒 商品购买支付 | POST | `/api/pay/go_goods_pay` | `goods_id`, `num`, `address_id`, `paymode`, `client` | 购买商品直接发货 |
| 🔒 余额充值 | POST | `/api/pay/recharge_balance` | `amount`, `paymode`, `client` | 充值余额 |
| 🔒 查询订单状态 | GET | `/api/pay/get_order_status` | `order_no` | 轮询支付结果 |
| 订单详情/价格活动 | GET | `/api/pay/order_details` | `boxid`, `zid`, `type`, `source` | 获取订单价格和活动信息 |
| 易支付跳转 | GET | `/api/pay/go_epay` | `order_no` | 易支付收银台页面跳转 |
| 聚合支付查询 | GET | `/api/pay/juhepay_query` | `order_no`, `pay_order_id` | 查询聚合支付结果 |
| 汇付支付查询 | GET | `/api/pay/heepay_query` | `agent_bill_id` | 查询汇付支付结果 |

**支持的支付方式（paymode）**：

| paymode | 支付方式 |
|---------|----------|
| 1 | 微信小程序支付 |
| 2 | APP 支付宝 |
| 3 | APP 微信支付 |
| 4/5 | 易支付（H5 微信/支付宝） |
| 6 | 多多币（积分支付） |
| 7 | H5 微信支付 |
| 8 | H5 支付宝 |
| 9 | 付呗 |
| 10 | 聚合支付 |
| 11 | 余额支付 |
| 12 | APP 支付宝 v2 |
| 13 | 汇付（云闪付） |

---

### 3.5 订单模块 (Order)

**Endpoint 前缀**：`/api/order`  
**认证要求**：JWT Token

| 接口名称 | Method | Endpoint | 关键参数 | 功能描述 |
|----------|--------|----------|----------|----------|
| 中奖记录 | GET | `/api/order/get_prize_record` | `status`, `in_safe_box`, `goods_source_type`, `except_box_type` | 用户奖品仓库列表 |
| 未开盒盲盒订单 | GET | `/api/order/get_blind_box_order` | `page` | 已购但未开的盲盒 |
| 商品订单列表 | GET | `/api/order/get_goods_order` | `status`, `page` | 商品订单分页列表 |
| 商品订单详情 | GET | `/api/order/get_goods_order_info` | `order_id` | 订单详细信息 |
| 订单状态统计 | GET | `/api/order/get_order_status_count` | — | 各状态订单数量统计 |
| 查询物流 | GET | `/api/order/get_express_data` | `express_company`, `express_number` | 快递100 物流追踪 |
| 奖品兑换回收 | POST | `/api/order/prize_exchange` | `id`（逗号分隔多个） | 将奖品兑换为余额/积分 |
| 奖品转赠 | POST | `/api/order/prize_give` | `id`, `receive_username`, `reason_type`, `reason_text` | 向指定用户转赠奖品 |
| 转赠记录 | GET | `/api/order/prize_give_log` | `page`, `type` | 转赠操作记录 |
| 重抽奖品 | POST | `/api/order/redraw_prize` | `card_id`, `id` | 使用重抽卡重新抽奖 |
| 获取发货运费 | GET | `/api/order/get_apply_deliver_price` | `ids` | 计算发货运费 |
| 申请发货 | POST | `/api/order/apply_deliver` | `ids`, `address_id`, `remarks`, `paymode` | 提交奖品发货申请 |
| 确认收货 | POST | `/api/order/confirm_deliver` | `id` | 确认收货完成 |

---

### 3.6 通用模块 (Common)

**Endpoint 前缀**：`/api/common`  
**认证要求**：大部分无需 Token

<details>
<summary>点击展开完整列表（35+ 接口）</summary>

| 接口名称 | Method | Endpoint | 关键参数 | 功能描述 |
|----------|--------|----------|----------|----------|
| 首页盲盒列表 | GET | `/api/common/get_index_list` | `uid`, `type` | 首页盲盒分类列表 |
| 获取盲盒分类 | GET | `/api/common/get_blind_box` | — | 盲盒分类信息 |
| 按类型获取盲盒 | GET | `/api/common/get_blind_box_by_type` | `type` | 指定类型盲盒列表 |
| 热门盲盒 | GET | `/api/common/get_hot_blind_box` | — | 热门推荐盲盒 |
| 盲盒商品列表 | GET | `/api/common/get_blind_box_goods` | `blind_box_id`, `uid` | 盲盒内商品列表 |
| 盲盒商品（优化版） | GET | `/api/common/optimize_get_blind_box_goods` | `blind_box_id`, `uid` | 缓存优化的商品列表 |
| 盲盒商品（按来源） | GET | `/api/common/get_blind_source_box_goods` | `blind_box_id`, `source`, `zid` | 新人/活动来源商品 |
| 盲盒概率配置 | GET | `/api/common/get_blind_box_odds` | `blind_box_id` | 各档位概率设置 |
| 盲盒概率商品 | GET | `/api/common/get_blind_box_odds_goods` | `blind_box_id` | 按概率分组的商品 |
| 开盒记录 | GET | `/api/common/get_blind_box_open_log` | — | 全站最近开盒滚动 |
| 一番赏详情 | GET | `/api/common/get_yfsbox_detail` | `id`, `type` | 一番赏盲盒详情 |
| 一番赏中奖信息 | GET | `/api/common/get_yfsinfo_list` | `box_id` | 一番赏中奖展示 |
| 一番赏记录 | GET | `/api/common/get_yfs_log` | `blind_box_id`, `odds_id` | 一番赏开奖记录 |
| 擂台赏详情 | GET | `/api/common/get_pxbox_detail` | `id`, `type` | 擂台赏盲盒详情 |
| PK 房间列表 | GET | `/api/common/get_pkhouse_list` | `box_id`, `status` | 擂台 PK 房间 |
| 爬塔配置 | GET | `/api/common/pata_config` | — | 爬塔玩法配置 |
| 爬塔层级详情 | GET | `/api/common/pata_level_detail` | `level` | 指定层级详情 |
| 爬塔开盒记录 | GET | `/api/common/get_pata_blind_box_open_log` | `level`, `odds_id` | 爬塔层开盒记录 |
| 爬塔排行榜 | GET | `/api/common/towerRank` | — | 爬塔玩家排行 |
| 试玩开奖 | GET | `/api/common/test_open_prize` | `boxid`, `num` | 无需登录模拟开盒 |
| 系统配置 | GET | `/api/common/get_general` | — | 全局系统配置信息 |
| 指定配置 | GET | `/api/common/get_config` | `key` | 获取指定配置项 |
| 协议内容 | GET | `/api/common/get_agreement` | `name` | 用户协议/隐私政策 |
| 新闻详情 | GET | `/api/common/get_news` | `id` | 资讯详情 |
| 广告列表 | GET | `/api/common/get_advert` | `type` | Banner / 弹窗广告 |
| 商品列表 | GET | `/api/common/get_goods_list` | `pid`, `goods_tj`, `order`, `page` | 商品商城列表 |
| 商品详情 | GET | `/api/common/get_goods_info` | `id` | 商品详情信息 |
| 商品分类 | GET | `/api/common/get_goods_menu` | — | 商品分类菜单 |
| 优惠券列表 | GET | `/api/common/get_coupon` | `a_type`, `uid` | 可领优惠券列表 |
| 卡片列表 | GET | `/api/common/get_card` | — | 重抽卡等卡片 |
| 签到数据 | GET | `/api/common/get_qiandao_data` | — | 签到统计信息 |
| 新人专享活动 | GET | `/api/common/get_new_user_buy_open` | `uid` | 新用户专享活动 |
| 一周限定 | GET | `/api/common/get_present_list` | `week_day`, `type` | 每周限定活动 |
| 专题活动 | GET | `/api/common/get_zhuanti` | — | 专题活动列表 |
| 任务列表 | GET | `/api/common/get_user_tasks` | `uid` | 用户可做任务 |
| 消费统计 | GET | `/api/common/get_xiaofei_count` | `uid` | 用户消费汇总 |
| 分享邀请链接 | GET | `/api/common/get_my_share` | `share_ma`, `type`, `st`, `uid` | 生成邀请链接/活码 |
| 银行列表 | GET | `/api/common/get_sys_bank` | — | 系统支持银行 |
| 判断小程序版本 | GET | `/api/common/pd_amp` | `amp_appid` | 判断是否更换新小程序 |
| 身份认证发起 | POST | `/api/common/identity_verify` | `cert_name`, `cert_no`, `outer_order_no` | 阿里云身份核验 |
| 查询认证结果 | POST | `/api/common/query_identity_verify` | `certify_id` | 查询核验结果 |
| APP 版本检查 | GET | `/api/common/getAppVersion` | `app_ident` | 获取最新 APP 版本号 |

</details>

---

### 3.7 排行榜模块 (Rank)

**Endpoint 前缀**：`/api/rank`  
**认证要求**：JWT Token

| 接口名称 | Method | Endpoint | 关键参数 | 功能描述 |
|----------|--------|----------|----------|----------|
| 排行榜奖品信息 | GET | `/api/rank/get_rank_prize_info` | `interval`（daily/weekly） | 获取排行榜奖品配置 |
| 排行榜数据 | GET | `/api/rank/get_rank_info` | `interval`, `uid` | 查看日榜/周榜排名 |
| 发放日榜奖励 | POST | `/api/rank/sendDayRankPrize` | — | 手动触发日排行奖励 |
| 发放周榜奖励 | POST | `/api/rank/sendWeekRankPrize` | — | 手动触发周排行奖励 |

---

### 3.8 奖品记录模块 (PrizeRecord)

**Endpoint 前缀**：`/api/prize_record`  
**认证要求**：JWT Token

| 接口名称 | Method | Endpoint | 关键参数 | 功能描述 |
|----------|--------|----------|----------|----------|
| 福利房中奖记录 | GET | `/api/prize_record/get_welfare_room_winners` | `room_id`, `page`, `limit` | 福利房开奖结果 |
| 中奖记录列表 | GET | `/api/prize_record/get_prize_records` | — | 个人中奖记录 |
| 最新中奖记录 | GET | `/api/prize_record/get_latest_prize_records` | — | 全站最新中奖滚动 |
| 高级兑换 | POST | `/api/prize_record/advanced_exchange` | — | 奖品高级兑换 |
| 移入保险箱 | POST | `/api/prize_record/move_to_safe_box` | — | 将奖品移入保险箱 |

---

### 3.9 支付回调 (Notify)

**Endpoint 前缀**：`/api/notify`  
**认证要求**：无（支付平台服务器回调）

| 接口名称 | Method | Endpoint | 功能描述 |
|----------|--------|----------|----------|
| 易支付同步回调 | GET/POST | `/api/notify/recharge_epay_return` | 用户支付后前端跳回 |
| 易支付异步回调 | POST | `/api/notify/recharge_epay_notify` | 易支付服务端通知 |
| 小程序微信支付回调 | POST | `/api/notify/recharge_amp_wxpay_notify` | 微信小程序支付回调 |
| H5 微信支付回调 | POST | `/api/notify/recharge_h5wxpay_notify` | H5 微信支付回调 |
| 付呗支付回调 | POST | `/api/notify/recharge_fbalipay_notify` | 付呗支付回调 |
| APP 支付宝回调 | POST | `/api/notify/recharge_app_alipay_notify` | APP 支付宝回调 |
| APP 支付宝 v2 回调 | POST | `/api/notify/recharge_app_alipay2_notify` | APP 支付宝 v2 回调 |
| 聚合支付回调 | POST | `/api/notify/recharge_juhepay_notify` | 聚合支付服务端通知 |
| 汇付支付回调 | POST | `/api/notify/recharge_heepay_notify` | 汇付（云闪付）回调 |

---

### 3.10 其他模块

| 模块 | Endpoint 前缀 | 接口 | 功能描述 |
|------|---------------|------|----------|
| **文件上传** | `/api/upload` | `POST /api/upload/upload` | 图片/文件上传（支持水印） |
| **红包** | `/api/red_packet` | `GET get_info` / `POST use_code` | 口令红包查询与使用 |
| **评论** | `/api/comment` | `POST add` / `GET getListByGoodsId` / `GET getListByBlindBoxId` / `GET detail` | 商品/盲盒评论管理 |
| **身份核验** | `/api/identity` | `POST verify` / `GET history` | 身份证核验服务 |
| **合作申请** | `/api/cooperation` | `POST submit` | 提交商务合作申请 |
| **福利池** | `/api/welfare_pool` | `GET list` / `GET detail` / `POST join` | 福利池活动 |
| **福利房** | `/api/welfare_room` | `GET list` / `POST create` / `POST join` / `GET detail` | 福利房创建与参与 |
| **积分优惠券** | `/api/integral_points_coupon` | `GET index` / `GET detail` / `POST exchange` / `GET my` | 积分兑换优惠券 |
| **积分商品** | `/api/integral_points_goods` | `GET goods_list` / `GET goods_detail` / `POST exchange_goods` / `GET get_categories` | 积分商城 |
| **领主记录** | `/api/lord_record` | `GET list` | 领主赏记录 |
| **充值** | `/api/recharge` | — | 充值相关（通过 Pay 模块入口） |

---

### 3.11 后台管理 (Admin)

**Endpoint 前缀**：`/admin`  
**认证要求**：AdminCheck 中间件（登录 + 安全码）

| 模块 | 主要功能 |
|------|----------|
| **首页 (Index)** | 后台仪表盘、数据统计、清除缓存、SQL 更新 |
| **登录 (Login)** | 管理员登录、安全码校验、验证码 |
| **会员 (Member)** | 用户列表、查看手机号、编辑上级、调整余额、封禁/解封、设置星标 |
| **盲盒 (BlindBox)** | 盲盒 CRUD、概率配置、保底设置、奖池重置、试开测试 |
| **商品 (Goods)** | 商品 CRUD、SKU 管理、淘宝同步、上下架 |
| **统计 (Statistics)** | 用户游戏汇总、整体经营统计、盲盒利润分析 |
| **系统配置 (General)** | 网站设置、参数配置、分销设置、运费设置、转赠设置、排行规则 |
| **充值管理 (Recharge)** | 充值订单列表 |
| **红包 (RedPacket)** | 口令红包 CRUD、使用记录 |
| **排行榜 (Rank)** | 排行榜奖品配置 |
| **任务 (Task)** | 每日任务配置 |
| **优惠券 (Coupon)** | 优惠券 CRUD、绑定盲盒 |
| **福利池 (WelfarePool)** | 福利池管理、参与记录 |
| **福利房 (WelfareRoom)** | 福利房管理、参与者、状态切换 |
| **转赠审核 (PrizeGiveLog)** | 奖品转赠申请审核（通过/驳回） |
| **提现审核 (Withdrawal)** | 用户提现申请审核、批量处理、导出 |

---

### 3.12 商户端 (Merchant)

**Endpoint 前缀**：`/merchant`  
**认证要求**：MerchantBase 登录校验

| 接口名称 | Method | Endpoint | 功能描述 |
|----------|--------|----------|----------|
| 商户首页 | GET | `/merchant/index/index` | 商户控制台首页 |
| 商户统计 | GET | `/merchant/index/home` | 经营数据统计 |
| 个人资料 | GET/POST | `/merchant/member/user_info` | 查看/编辑个人信息 |
| 我的团队 | GET | `/merchant/member/my_team` | 查看推广下级 |
| 多多币充值 | GET/POST | `/merchant/member/my_up_xyb` | 给下级充值多多币 |

---

## 4. 快速开始 (Getting Started)

### 环境要求

| 组件 | 版本要求 |
|------|----------|
| PHP | >= 7.1（推荐 7.4） |
| MySQL | >= 5.6 |
| Redis | 可选（用于缓存加速） |
| Composer | 最新版 |
| Web 服务器 | Nginx / Apache |

### 安装步骤

**1. 克隆项目**

```bash
git clone <repository-url>
cd v6max
```

**2. 安装 PHP 依赖**

```bash
composer install
```

**3. 配置环境变量**

复制并编辑 `.env` 文件：

```ini
[APP]
DEBUG = true
DEFAULT_TIMEZONE = Asia/Shanghai

[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = your_database_name
USERNAME = your_username
PASSWORD = your_password
HOSTPORT = 3306
CHARSET = utf8
PREFIX = xn_

[REDIS]
HOSTNAME = 127.0.0.1
PASSWORD =
PORT = 6379

[JWT]
SECRET = your_jwt_secret_key
TTL = 604800
```

**4. 导入数据库**

创建 MySQL 数据库（字符集 `utf8mb4`），导入项目提供的 SQL 文件：

```bash
mysql -u root -p your_database_name < public/sql.txt
```

**5. 设置 Web 根目录**

将 Web 服务器根目录指向 `public/` 目录。

Nginx 示例配置：

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/project/public;
    index index.php;

    location / {
        if (!-e $request_filename) {
            rewrite ^(.*)$ /index.php?s=/$1 last;
        }
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

**6. 启动开发服务器（可选）**

```bash
php think run
```

访问 `http://localhost:8000` 即可。

**7. 配置定时任务**

```bash
# 日榜奖励发放（每日零点）
0 0 * * * cd /path/to/project && php think send:daily-rank-prize

# 周榜奖励发放（每周一零点）
0 0 * * 1 cd /path/to/project && php think send:weekly-rank-prize

# 福利房开奖
* * * * * cd /path/to/project && php think welfare:lottery

# 领主过期检查
0 */1 * * * cd /path/to/project && php think check:lord-expiration

# 每日推广统计
0 1 * * * cd /path/to/project && php think day_popularize_log

# 排行数据清理
0 0 * * * cd /path/to/project && php think clearRankingData
```

---

## 5. 定时任务 (Scheduled Commands)

| 命令 | 类 | 功能说明 |
|------|----|----------|
| `php think send:daily-rank-prize` | SendDailyRankPrize | 发放日排行榜奖励 |
| `php think send:weekly-rank-prize` | SendWeeklyRankPrize | 发放周排行榜奖励 |
| `php think welfare:lottery` | WelfareRoomLottery | 福利房自动开奖 |
| `php think check:lord-expiration` | CheckLordExpiration | 检查领主赏过期 |
| `php think day_popularize_log` | DayPopularizeLog | 统计每日推广数据 |
| `php think clearRankingData` | ClearRankingData | 清理过期排行数据 |
| `php think caiji` | Caiji | 数据采集 |
| `php think migrate:yifanshang` | MigrateYifanshangBox | 一番赏数据迁移 |
| `php think clean:queue` | CleanQueue | 清理超时排队记录 |

---

## 6. 功能更新日志

### 接口返回中英文多语言支持 (2025-12-11)

- 开启了 ThinkPHP 多语言中间件
- `ApiBase` 基类的 `success()` / `error()` 自动支持翻译
- 建立了 `zh-cn.php` 和 `en-us.php` 语言包
- 前端可通过 `?lang=en-us` 或 Header `lang` 参数切换语言

---

> 📌 本文档由代码库自动分析生成，如需补充具体接口的请求/响应示例，请指定模块名称。

# 项目源码结构与功能说明书

> **项目名称**: V6MAX 潮玩盲盒商城后端  
> **文档版本**: v1.0  
> **生成日期**: 2026-03-06  

---

## 第一部分：项目概览

### 1.1 核心技术栈

| 类别 | 技术 |
|------|------|
| **语言** | PHP >= 7.1（推荐 7.4） |
| **框架** | ThinkPHP 6.x（多应用模式） |
| **数据库** | MySQL 5.6+，表前缀 `xn_` |
| **缓存** | Redis（Predis 扩展） |
| **认证** | JWT（API 端）/ Session（后台管理端） |
| **存储** | 阿里云 OSS / 七牛云 |
| **短信** | 短信宝（api.smsbao.com） |
| **支付** | 微信支付（小程序/APP/H5）、支付宝（APP/H5）、易支付、聚合支付、汇付支付、付呗、余额支付、积分支付 |
| **身份核验** | 阿里云 Cloudauth（二要素：姓名+身份证） |
| **微信生态** | 小程序登录、APP 微信登录、H5 微信 OAuth |
| **前端对接** | uni-app + Vue3（H5/小程序/APP） |

### 1.2 关键依赖库

| 包名 | 用途 |
|------|------|
| `topthink/framework` ^6.0.0 | ThinkPHP 核心框架 |
| `topthink/think-orm` ^2.0 | ORM 数据库操作 |
| `topthink/think-multi-app` ^1.0 | 多应用支持 |
| `topthink/think-view` ^1.0 | 模板视图引擎 |
| `thans/tp-jwt-auth` | JWT 认证 |
| `aliyuncs/oss-sdk-php` | 阿里云 OSS 存储 |
| `qiniu/php-sdk` | 七牛云存储 |
| `alibabacloud/sdk` | 阿里云 SDK（身份核验） |
| `alibabacloud/dypnsapi-20170525` | 阿里云号码认证 |
| `dtk-developer/openapi-sdk-php` | 淘宝联盟/大淘客 API（商品采集） |
| `jianyan74/php-excel` | Excel 导入导出 |
| `phpmailer/phpmailer` | 邮件发送 |
| `topthink/think-image` | 图片处理 |
| `topthink/think-captcha` | 验证码生成 |

### 1.3 主要业务目标

本项目是一个**潮玩盲盒电商平台后端系统**，核心业务包括：

1. **盲盒抽奖** — 支持普通盲盒、一番赏、福袋、对对碰（54 张卡牌配对）、擂台赏、领主赏等多种玩法
2. **商品商城** — 实体商品销售、淘宝商品同步、积分商城兑换
3. **福利系统** — 福利房（多人拼奖）、福利池（消费抽奖）、红包口令、签到、任务系统
4. **分销推广** — 邀请注册返佣、团队管理、推广日志、消费等级体系
5. **排行榜** — 日榜/周榜消费排名及奖励发放
6. **后台管理** — 管理员 RBAC 权限、盲盒/商品/会员/订单/财务全方位管理
7. **商户端** — 分销代理后台、团队收益统计

---

## 第二部分：目录结构树

```
v6max.mh.50api.cn_RdfGT/
├── app/                                 # 应用主目录（ThinkPHP 多应用架构）
│   ├── admin/                           # 后台管理端应用
│   │   ├── config/                      # Admin 应用级配置
│   │   │   ├── route.php                #   路由中间件配置（AdminCheck）
│   │   │   ├── rank_prize.php           #   排行榜奖励配置（日/周榜多多币）
│   │   │   └── crontab.php              #   定时任务配置
│   │   ├── controller/                  # Admin 控制器（50+ 个）
│   │   │   ├── Index.php                #   后台首页、菜单、缓存管理
│   │   │   ├── Login.php                #   后台登录认证
│   │   │   ├── BlindBox.php             #   盲盒分类管理
│   │   │   ├── blind_box/               #   盲盒子模块（商品/概率/订单/奖品等）
│   │   │   ├── Goods.php                #   商品管理、淘宝同步
│   │   │   ├── goods/                   #   商品子模块（分类/订单）
│   │   │   ├── Member.php               #   会员管理
│   │   │   ├── member/                  #   会员子模块（提现/地址/资金等）
│   │   │   ├── General.php              #   系统配置管理
│   │   │   ├── general/                 #   配置子模块（签到/爬塔/银行等）
│   │   │   ├── Statistics.php           #   数据统计
│   │   │   ├── Rank.php                 #   排行榜管理
│   │   │   ├── Task.php                 #   任务管理
│   │   │   ├── RedPacket.php            #   红包管理
│   │   │   ├── WelfareRoom.php          #   福利房管理
│   │   │   ├── WelfarePool.php          #   福利池管理
│   │   │   ├── Auth.php                 #   权限规则管理
│   │   │   ├── AuthGroup.php            #   角色组管理
│   │   │   ├── Admin.php                #   管理员管理
│   │   │   └── ...                      #   更多管理控制器
│   │   ├── middleware/                  # Admin 中间件
│   │   │   └── AdminCheck.php           #   敏感操作安全码校验
│   │   └── view/                        # Admin 视图模板（HTML）
│   │       ├── blind_box/               #   盲盒相关页面
│   │       ├── goods/                   #   商品相关页面
│   │       ├── general/                 #   系统设置页面
│   │       ├── member/                  #   会员相关页面
│   │       ├── index/                   #   首页/仪表盘
│   │       ├── login/                   #   登录页
│   │       └── ...                      #   更多管理页面
│   │
│   ├── api/                             # API 应用（H5/小程序/APP 接口）
│   │   ├── controller/                  # API 控制器（20+ 个）
│   │   │   ├── Login.php                #   用户登录/注册（短信/微信/手机号）
│   │   │   ├── Member.php               #   用户中心（信息/提现/签到等）
│   │   │   ├── Common.php               #   公共接口（首页/配置/商品列表等）
│   │   │   ├── BlindBox.php             #   盲盒开箱/对对碰/一番赏/福袋
│   │   │   ├── Pay.php                  #   支付入口（多种支付方式）
│   │   │   ├── Order.php                #   订单管理（兑换/回收/转赠/发货）
│   │   │   ├── PrizeRecord.php          #   奖品记录/进阶兑换/保险箱
│   │   │   ├── Notify.php               #   支付异步回调处理
│   │   │   ├── WelfareRoom.php          #   福利房（创建/加入/开奖）
│   │   │   ├── WelfarePool.php          #   福利池（列表/加入/抽奖）
│   │   │   ├── Rank.php                 #   排行榜与奖励
│   │   │   ├── RedPacket.php            #   红包口令
│   │   │   ├── Comment.php              #   评论系统
│   │   │   ├── Identity.php             #   实名认证
│   │   │   ├── IntegralPointsGoods.php  #   积分商品兑换
│   │   │   ├── IntegralPointsCoupon.php #   积分优惠券兑换
│   │   │   ├── Upload.php               #   文件上传
│   │   │   ├── Recharge.php             #   充值（模型复用）
│   │   │   ├── Cooperation.php          #   合作申请
│   │   │   ├── LordRecord.php           #   领主记录
│   │   │   └── Index.php                #   测试/首页
│   │   └── middleware/                  # API 中间件
│   │       └── Jwt.php                  #   JWT 认证校验与自动刷新
│   │
│   ├── index/                           # PC 端/默认站点应用
│   │   ├── controller/                  # 首页控制器
│   │   │   └── Index.php                #   首页、注册、分享跳转
│   │   ├── route/                       # 自定义路由
│   │   │   └── app.php                  #   注册页路由
│   │   └── view/                        # 视图
│   │       └── index/index.html         #   首页模板
│   │
│   ├── merchant/                        # 商户/代理端应用
│   │   ├── controller/                  # 商户控制器
│   │   │   ├── Index.php                #   商户后台首页
│   │   │   └── Member.php               #   团队/下级/收益管理
│   │   └── view/                        # 商户端视图
│   │       ├── index/index.html         #   商户首页
│   │       └── member/                  #   团队/用户详情页
│   │
│   ├── common/                          # 公共模块（跨应用共享）
│   │   ├── controller/                  # 基础控制器
│   │   │   ├── Base.php                 #   全局基类（validate/success/error）
│   │   │   ├── AdminBase.php            #   Admin 基类（RBAC/登录检查）
│   │   │   ├── ApiBase.php              #   API 基类（JWT uid/统一响应）
│   │   │   ├── IndexBase.php            #   Index 基类
│   │   │   └── MerchantBase.php         #   商户端基类
│   │   ├── model/                       # 数据模型（60+ 个）
│   │   │   ├── Member.php               #   会员模型（登录/注册/信息）
│   │   │   ├── BlindBox.php             #   盲盒模型（列表/详情/缓存）
│   │   │   ├── BlindBoxOrder.php        #   盲盒订单（下单/开奖逻辑）
│   │   │   ├── BlindBoxPrizeRecord.php  #   奖品记录（抽奖核心逻辑）
│   │   │   ├── GoodsOrder.php           #   商品订单
│   │   │   ├── MemberMoneyLog.php       #   资金流水（余额/积分/佣金变动）
│   │   │   ├── Recharge.php             #   充值订单
│   │   │   ├── WelfareRoom.php          #   福利房
│   │   │   ├── WelfarePool.php          #   福利池
│   │   │   ├── General.php              #   系统配置（K-V 存储+缓存）
│   │   │   └── ...                      #   更多数据模型
│   │   └── lib/                         # 工具/服务类库
│   │       ├── Pay/                     #   支付集成（10+ 支付方式）
│   │       │   ├── AmpWxPay.php         #     小程序微信支付
│   │       │   ├── AppWxPay.php         #     APP 微信支付
│   │       │   ├── AppAliPay.php        #     APP 支付宝
│   │       │   ├── H5Wxpay.php          #     H5 微信支付
│   │       │   ├── H5Alipay.php         #     H5 支付宝
│   │       │   ├── Epay.php             #     易支付网关
│   │       │   ├── JuhePay.php          #     聚合支付
│   │       │   ├── HeePay.php           #     汇付支付
│   │       │   ├── FbPay.php            #     付呗支付
│   │       │   ├── BalancePay.php       #     余额支付
│   │       │   ├── IntegralPay.php      #     积分支付
│   │       │   └── SDK/                 #     微信/支付宝 SDK 封装
│   │       ├── Aliyun/
│   │       │   └── IdentityVerify.php   #   阿里云身份核验（二要素）
│   │       ├── Sms/
│   │       │   └── Duanxinbao.php       #   短信宝短信发送
│   │       ├── Oss.php                  #   阿里云 OSS 文件操作
│   │       ├── Qiniu.php               #   七牛云文件操作
│   │       ├── WxLogin.php             #   微信登录（小程序/APP/H5）
│   │       ├── PairMatchLogger.php     #   对对碰游戏日志
│   │       ├── SendEmail.php           #   邮件发送（PHPMailer）
│   │       ├── SendCode.php            #   后台安全码邮件验证
│   │       └── ShortLink/
│   │           └── Bslyun.php          #   短链接生成（变色龙云）
│   │
│   ├── command/                         # CLI 命令（定时任务）
│   │   ├── SendDailyRankPrize.php       #   每日排行榜奖励发放
│   │   ├── SendWeeklyRankPrize.php      #   每周排行榜奖励发放（周一执行）
│   │   ├── WelfareRoomLottery.php       #   福利房定时开奖
│   │   ├── CleanQueue.php               #   清理超时排队记录（3 分钟）
│   │   ├── CheckLordExpiration.php      #   领主过期检查（24 小时）
│   │   ├── ClearRankingData.php         #   清理排行榜/爬塔缓存数据
│   │   ├── DayPopularizeLog.php         #   每日邀请推广统计
│   │   ├── Caiji.php                    #   商品采集（外部 API + OSS 上传）
│   │   └── MigrateYifanshangBox.php     #   一番赏数据迁移
│   │
│   ├── common.php                       # 全局公共函数
│   ├── middleware.php                   # 全局中间件注册
│   ├── service.php                      # 服务注册
│   ├── event.php                        # 事件定义
│   ├── AppService.php                   # 应用服务
│   ├── ExceptionHandle.php              # 异常处理
│   └── Request.php                      # 请求对象
│
├── config/                              # 全局配置
│   ├── app.php                          #   应用配置（时区/默认应用/URL 后缀）
│   ├── database.php                     #   数据库配置（MySQL/前缀 xn_）
│   ├── cache.php                        #   缓存配置
│   ├── redis.php                        #   Redis 配置
│   ├── jwt.php                          #   JWT 配置（密钥/TTL/获取方式）
│   ├── middleware.php                   #   中间件别名
│   ├── route.php                        #   路由全局配置
│   ├── filesystem.php                   #   文件系统（本地/OSS）
│   ├── session.php                      #   Session 配置
│   ├── cookie.php                       #   Cookie 配置
│   ├── log.php                          #   日志配置
│   ├── console.php                      #   命令行注册
│   ├── view.php                         #   视图引擎配置
│   ├── captcha.php                      #   验证码配置
│   ├── lang.php                         #   多语言配置
│   └── trace.php                        #   调试追踪配置
│
├── route/                               # 路由目录
│   └── app.php                          #   全局路由（以约定路由为主）
│
├── extend/                              # 扩展库
│   ├── alipay/                          #   支付宝 SDK（Wap/App/转账/退款）
│   ├── Predis.php                       #   Redis 客户端封装
│   ├── OpenApi.php                      #   开放 API 接口
│   └── NotifyApi.php                    #   通知 API 接口
│
├── public/                              # Web 根目录（文档根）
│   ├── index.php                        #   应用入口文件
│   ├── favicon.ico                      #   站点图标
│   ├── static/                          #   静态资源（JS/CSS/图片）
│   ├── uploads/                         #   上传文件存储
│   ├── share_code/                      #   分享码图片
│   ├── sql.txt                          #   数据库结构文件
│   └── .well-known/                     #   SSL 证书验证
│
├── vendor/                              # Composer 依赖
├── view/                                # 全局视图
├── runtime/                             # 运行时缓存/日志
├── .env                                 # 环境变量配置
├── composer.json                        # Composer 依赖管理
├── think                                # CLI 入口脚本
├── README.md                            # 项目说明
└── API接口文档.md                        # API 接口文档
```

---

## 第三部分：详细功能解析

### 3.1 应用层 — `app/admin/`（后台管理端）

#### 3.1.1 `app/admin/controller/`

**路径**: `app/admin/controller/`  
**核心职责**: 提供后台管理的全部 Web 操作接口，基于 Session 认证 + RBAC 权限控制。  
**具体功能点**:

| 控制器文件 | 核心功能 |
|-----------|----------|
| `Index.php` | 后台首页仪表盘、左侧菜单渲染、缓存清理、系统信息展示 |
| `Login.php` | 管理员登录、验证码校验、Session 管理 |
| `BlindBox.php` | 盲盒分类 CRUD、类型管理（普通/一番赏/福袋/对对碰/擂台赏）、启停控制 |
| `blind_box/Goods.php` | 盲盒关联商品管理、库存、价格、图片配置 |
| `blind_box/Odds.php` | 盲盒概率配置（各赏级中奖率设置） |
| `blind_box/OddsGroup.php` | 概率分组管理（多概率方案切换） |
| `blind_box/Buy.php` | 购买方案管理（单抽/多抽/包抽价格配置） |
| `blind_box/Order.php` | 盲盒订单列表、订单详情、状态管理、数据导出 |
| `blind_box/PrizeRecord.php` | 奖品记录管理、发货状态、回收管理 |
| `blind_box/PrizeGiveLog.php` | 奖品转赠审核（通过/拒绝）、转赠日志查询 |
| `blind_box/LordRecord.php` | 领主记录管理（领主赏玩法） |
| `Goods.php` | 实体商品 CRUD、淘宝商品同步（大淘客 API）、商品上下架 |
| `goods/Order.php` | 商品订单管理、发货操作、物流跟踪、退款处理 |
| `goods/Menu.php` | 商品分类管理 |
| `Member.php` | 会员列表、搜索、禁用/启用、详情、余额调整 |
| `member/Withdrawal.php` | 提现申请审核（通过/拒绝）、提现记录查询 |
| `member/MoneyLog.php` | 资金流水查询、按类型/时间筛选 |
| `member/CommissionLog.php` | 佣金记录查询 |
| `member/PopularizeLog.php` | 推广邀请记录、下级关系查询 |
| `member/Level.php` | 会员等级配置（权益/折扣） |
| `member/ConsumptionLevel.php` | 消费等级配置（积分门槛/特权） |
| `member/Coupon.php` | 用户优惠券管理 |
| `member/Card.php` | 道具卡管理（重抽卡等） |
| `member/Address.php` | 收货地址管理 |
| `member/Bank.php` | 银行卡绑定管理 |
| `member/QiandaoLog.php` | 签到记录查询 |
| `General.php` | 系统全局配置管理（站点名称/域名/支付参数/短信参数/上传配置等） |
| `general/QiandaoSet.php` | 签到奖励配置（连续签到/奖励递增） |
| `general/TowerLevels.php` | 爬塔层级配置（难度/奖品） |
| `general/Bank.php` | 系统银行列表管理 |
| `general/ShortLink.php` | 短链接管理 |
| `general/SysDataDel.php` | 系统数据清理工具 |
| `Statistics.php` | 数据统计报表（盲盒利润、营收分析、用户数据） |
| `Rank.php` | 排行榜管理、日榜/周榜奖励配置与发放 |
| `Task.php` | 任务系统管理（每日任务配置/奖励设置） |
| `RedPacket.php` | 红包口令管理（创建/编辑/日志查询） |
| `Recharge.php` | 充值记录查询与管理 |
| `WelfareRoom.php` | 福利房管理（官方房/用户房控制） |
| `WelfarePool.php` | 福利池管理（奖池配置/奖品设置） |
| `WelfarePoolRecord.php` | 福利池参与记录查询 |
| `WelfareRoomGoods.php` | 福利房商品管理 |
| `Coupon.php` | 优惠券模板管理（创建/发放/状态管理） |
| `Cdkey.php` | 兑换码管理（批量生成/查询/状态管理） |
| `IntegralPointsGoods.php` | 积分商品管理（上下架/库存/积分价格） |
| `IntegralPointsGoodsCategory.php` | 积分商品分类管理 |
| `IntegralPointsCoupon.php` | 积分优惠券管理 |
| `Advert.php` | 广告位管理（Banner/弹窗等） |
| `Notice.php` | 公告管理（系统通知推送） |
| `News.php` | 新闻/资讯管理 |
| `Agreement.php` | 协议管理（用户协议/隐私政策/转赠协议等） |
| `Comment.php` | 用户评论管理（审核/删除） |
| `Auth.php` | 权限规则管理（菜单/操作权限配置） |
| `AuthGroup.php` | 角色组管理（角色创建/权限分配） |
| `Admin.php` | 管理员账号管理（增删改/角色分配） |
| `AdminLog.php` | 管理员操作日志查询 |
| `Newer.php` | 新人活动配置 |
| `Zhuanti.php` | 专题活动管理 |
| `Lucky.php` | 幸运活动配置（新人/活动盲盒绑定） |
| `Cooperation.php` | 合作申请管理（审核/处理） |
| `VersionManager.php` | APP 版本管理（版本号/更新内容/强制更新） |
| `UploadFiles.php` | 上传文件管理 |
| `SysReward.php` | 系统奖励配置 |
| `BlindBoxMatchProbability.php` | 对对碰匹配概率配置 |
| `BlindBoxMatchGuaranteeGoods.php` | 对对碰保底商品配置 |
| `Kuaidi100Code.php` | 快递 100 编码管理 |
| `FriendlyLink.php` | 友情链接管理 |

#### 3.1.2 `app/admin/middleware/AdminCheck.php`

**核心职责**: 后台敏感操作安全码校验中间件。  
**具体功能点**:
1. 拦截指定的敏感操作请求（如提现审核、数据删除等）
2. 校验请求中携带的安全码是否与管理员邮箱验证码匹配
3. 验证通过后放行请求，失败则返回错误提示
4. 与 `SendCode` 邮件服务配合使用

#### 3.1.3 `app/admin/view/`

**核心职责**: 后台管理端的 HTML 视图模板层。  
**具体功能点**:
1. 基于 ThinkPHP 模板引擎渲染后台管理页面
2. 使用 layui/element-ui 等 UI 组件构建管理界面
3. 包含表单（form.html）、列表（index.html）、弹窗等页面模板
4. 支持数据可视化图表展示（统计页面）

---

### 3.2 应用层 — `app/api/`（API 接口端）

#### 3.2.1 `app/api/controller/Login.php`

**核心职责**: 用户登录、注册与第三方授权认证。  
**具体功能点**:
1. **短信验证码登录** — 发送短信（60 秒限制）、验证码校验、自动注册/登录，颁发 JWT
2. **手机号一键登录** — 运营商号码认证（阿里云 GetMobile），免短信登录
3. **微信小程序登录** — `jscode2session` 获取 openid，绑定/创建用户
4. **微信 APP 登录** — 通过 `WxLogin::threeLogin()` 实现第三方登录
5. **H5 微信 OAuth** — 网页授权获取用户信息登录

#### 3.2.2 `app/api/controller/Member.php`

**核心职责**: 用户中心全部个人操作接口。  
**具体功能点**:
1. **个人信息** — 获取/修改用户信息、头像、昵称
2. **实名认证** — 查询/提交实名认证状态（关联阿里云身份核验）
3. **提现** — 余额提现申请（5 秒防重、余额校验、银行卡信息）
4. **收货地址** — 地址 CRUD（增删改查、默认地址设置）
5. **签到** — 每日签到领奖（连续签到递增奖励）
6. **分享** — 每日分享领奖（限次）
7. **优惠券** — 查看/领取优惠券
8. **CDKEY 兑换** — 输入兑换码领取对应奖励
9. **道具卡** — 查看我的道具卡（重抽卡等）
10. **团队** — 邀请关系、下级列表、团队统计
11. **消息通知** — 系统公告列表
12. **任务中心** — 每日任务进度查询
13. **账号注销** — 用户自主注销账号
14. **绑定邀请码** — 绑定上级邀请码

#### 3.2.3 `app/api/controller/Common.php`

**核心职责**: 面向前端的公共数据接口（大部分无需登录）。  
**具体功能点**:
1. **首页数据** — 盲盒列表、广告 Banner、公告、热门盲盒
2. **盲盒详情** — 商品列表、概率列表、购买方案、一番赏/福袋详情
3. **商品数据** — 商品列表、详情、分类菜单
4. **系统配置** — 站点名称、联系方式、功能开关等通用配置
5. **协议/新闻** — 用户协议、隐私政策、新闻资讯
6. **签到配置** — 签到规则与奖励展示
7. **任务列表** — 用户可完成的每日任务
8. **爬塔系统** — 爬塔配置、层级详情、爬塔排行榜
9. **专题/活动** — 专题页数据、新人活动配置
10. **身份核验** — 发起实名认证请求、查询认证结果
11. **版本检查** — APP 版本号与更新提示

#### 3.2.4 `app/api/controller/BlindBox.php`

**核心职责**: 盲盒核心开箱与游戏逻辑。  
**具体功能点**:
1. **普通开箱** — 验证订单 → 概率抽奖 → 生成奖品记录，支持首次开箱奖励
2. **对对碰** — 54 张卡牌匹配游戏（选择心愿商品 → 翻牌碰撞 → 0/3/6/9/14 次保底机制 → 心愿卡触发）
3. **一番赏** — 查看赏箱列表 → 选择赏箱 → 排队 → 抽取（库存递减）
4. **福袋** — 福袋列表/详情 → 购买 → 随机获取福袋内商品
5. **排队系统** — 加入/取消/查询排队状态（一番赏/福袋）
6. **锁箱** — 盲盒锁定/解锁（防止并发操作冲突）

#### 3.2.5 `app/api/controller/Pay.php`

**核心职责**: 统一支付入口，对接多种支付渠道。  
**具体功能点**:
1. **盲盒支付** — 计算价格（含优惠券/积分抵扣）→ 生成充值订单 → 调用对应支付渠道
2. **商品支付** — 实体商品下单支付
3. **余额充值** — 向平台账户充值余额
4. **运费支付** — 单独支付发货运费
5. **支付方式映射** — 根据 `pay_method` 字段路由到：小程序微信(1)、APP 支付宝(2)、APP 微信(3)、易支付(4/5)、积分(6)、H5 微信(7)、H5 支付宝(8)、付呗(9)、聚合支付(10)、余额(11)、APP 支付宝 2(12)、汇付(13)
6. **新人专享支付** — 特殊价格的新人盲盒购买通道

#### 3.2.6 `app/api/controller/Notify.php`

**核心职责**: 各支付渠道的异步回调统一处理。  
**具体功能点**:
1. **签名验证** — 验证各支付渠道回调签名的合法性
2. **订单状态更新** — 支付成功后更新充值订单状态为已支付
3. **业务分发** — 根据订单类型执行不同业务逻辑：
   - `add_blind_box_order` — 创建盲盒订单
   - `add_goods_order` — 创建商品订单
   - `batch_apply_deliver` — 批量发货申请
   - `add_balance_recharge` — 余额充值到账
   - `add_goods_to_warehouse` — 商品入仓库
4. **消费等级升级** — 支付成功后检查并升级用户消费等级
5. **分销佣金** — 触发上级推广佣金结算
6. **爬塔逻辑** — 消费后触发爬塔进度更新

#### 3.2.7 `app/api/controller/Order.php`

**核心职责**: 订单与奖品的全生命周期管理。  
**具体功能点**:
1. **订单查询** — 商品订单列表/详情、未开箱盲盒订单列表
2. **奖品兑换** — 将奖品兑换为积分/余额（按 `exchange_integral` 价格）
3. **奖品转赠** — 赠送奖品给其他用户（需实名认证、消费门槛、月/周限额、协议确认）
4. **申请发货** — 选择收货地址、计算运费、提交发货申请
5. **确认收货** — 用户确认收到实物商品
6. **重抽** — 使用重抽卡对奖品进行重新抽取
7. **物流查询** — 通过快递 100 接口查询物流信息
8. **订单状态统计** — 各状态订单数量（用于前端角标显示）

#### 3.2.8 `app/api/controller/PrizeRecord.php`

**核心职责**: 奖品仓库操作与进阶兑换。  
**具体功能点**:
1. **奖品记录查询** — 按类型/状态查询用户的奖品列表
2. **进阶兑换** — 多个低价值奖品合成一个高价值奖品（价值差额校验/退还）
3. **保险箱** — 将奖品移入/移出保险箱（防误操作保护）
4. **福利房中奖记录** — 查询福利房的中奖详情
5. **最新奖品滚动** — 获取最近的中奖记录（用于前端滚动展示）

#### 3.2.9 `app/api/controller/WelfareRoom.php`

**核心职责**: 福利房的创建、参与和开奖。  
**具体功能点**:
1. **房间列表** — 获取可加入的福利房列表
2. **创建房间** — 从仓库选择奖品作为奖池，设置人数/密码/开奖方式（人满/定时）
3. **加入房间** — 验证消费门槛/密码/容量，扣除参与费用，人满自动开奖
4. **房间详情** — 参与者列表、奖品信息、开奖状态
5. **开奖逻辑** — 单人房直接发放、多人房随机抽取中奖者、官方房指定奖品发放

#### 3.2.10 `app/api/controller/WelfarePool.php`

**核心职责**: 福利池抽奖玩法。  
**具体功能点**:
1. **池列表** — 获取活跃的福利池列表
2. **池详情** — 奖品列表、剩余库存、参与条件
3. **加入抽奖** — 验证当日消费额 → Redis 库存扣减 → 按权重随机抽取奖品 → 生成奖品记录

#### 3.2.11 `app/api/controller/Rank.php`

**核心职责**: 消费排行榜与排名奖励。  
**具体功能点**:
1. **排行数据** — 按日/周统计充值消费金额排名（排除积分支付和余额支付）
2. **奖励配置** — 获取日榜/周榜各名次的奖励信息
3. **发放日榜奖励** — 结算前一日排行，发放多多币/商品/优惠券/道具卡
4. **发放周榜奖励** — 结算上周排行，仅周一可执行

#### 3.2.12 `app/api/controller/RedPacket.php`

**核心职责**: 红包口令系统。  
**具体功能点**:
1. **红包信息** — 通过口令查询红包详情（金额/状态/剩余）
2. **使用口令** — 校验口令有效性、防止自领、单人单次限制、到账余额

#### 3.2.13 其他 API 控制器

| 控制器 | 核心功能 |
|--------|----------|
| `Comment.php` | 评论发布（关联订单/商品评级）、评论列表查询（按商品/订单/盲盒）、用户名脱敏 |
| `Identity.php` | 二要素身份核验（姓名+身份证）、每日限额 1000 次、阿里云 Cloudauth 对接、防重复绑定 |
| `IntegralPointsGoods.php` | 积分商品列表/详情、消费等级过滤、积分兑换（扣积分+生成奖品记录） |
| `IntegralPointsCoupon.php` | 积分优惠券列表/详情、积分兑换优惠券（扣积分+发券） |
| `Upload.php` | 文件上传（禁 PHP 文件、支持水印）、存储到 OSS/七牛/本地 |
| `Cooperation.php` | 合作申请提交（姓名/手机/微信/备注）、24 小时去重 |
| `LordRecord.php` | 领主赏记录查询（当前领主/收益/任期/抽取次数/排名） |
| `Recharge.php` | 充值模型（非独立控制器，充值逻辑在 Pay 中实现） |

#### 3.2.14 `app/api/middleware/Jwt.php`

**核心职责**: API 请求的 JWT 认证中间件。  
**具体功能点**:
1. 从请求头/参数中提取 JWT Token
2. 校验 Token 有效性，解析出 `member_id`
3. 过期 Token 自动刷新机制
4. 将 `member_id` 注入到请求对象中供控制器使用
5. 白名单路由免认证放行

---

### 3.3 应用层 — `app/index/`（PC 端/默认站点）

**路径**: `app/index/`  
**核心职责**: PC 端首页与注册分享页面。  
**具体功能点**:
1. 首页展示 — 平台介绍/引导下载
2. 注册页面 — 带邀请码的注册入口
3. 分享跳转 — 从分享链接跳转到 H5/小程序

---

### 3.4 应用层 — `app/merchant/`（商户/代理端）

**路径**: `app/merchant/`  
**核心职责**: 分销代理的后台管理面板。  
**具体功能点**:
1. 商户首页 — 个人收益概览、团队数据统计
2. 团队管理 — 下级用户列表、层级关系展示
3. 用户详情 — 查看下级用户的消费/充值/收益详情
4. 收益管理 — 推广佣金记录、下级贡献统计

---

### 3.5 公共模块 — `app/common/model/`（数据模型）

#### 3.5.1 核心业务模型

| 模型文件 | 对应表 | 核心业务逻辑 |
|---------|--------|-------------|
| `Member.php` | `xn_member` | 用户登录/注册（`mobile_login_or_reg`）、用户信息获取（`get_info`）、邀请码生成、分享码图片生成（`create_share_ma`）、消费等级关联 |
| `BlindBox.php` | `xn_blind_box` | 盲盒列表查询（`get_index_blind_box`/`get_blind_box`）、缓存优化、购买方案关联（`buy_data`）、擂台赏详情 |
| `BlindBoxOrder.php` | `xn_blind_box_order` | 订单创建（`add_order`）、开奖核心逻辑（`order_open`，区分普通/一番赏/福袋/对对碰模式） |
| `BlindBoxPrizeRecord.php` | `xn_blind_box_prize_record` | **抽奖核心** — 概率计算（`get_open_prize`）、一番赏开奖（`yfs_open`）、福袋抽取（`get_fukubukuro_prizes`）、保底机制、领主赏触发、奖品兑换/转赠/发货流程 |
| `BlindBoxMatchRecord.php` | `xn_blind_box_match_record` | 对对碰游戏记录、碰撞匹配逻辑、卡牌状态管理 |
| `MemberMoneyLog.php` | `xn_member_money_log` | **资金核心** — `set_money()` 方法处理所有余额/积分/佣金的增减操作，记录流水明细 |
| `Recharge.php` | `xn_recharge` | 充值订单管理（创建/查询/状态更新） |
| `GoodsOrder.php` | `xn_goods_order` | 商品订单管理（创建/发货/物流/确认收货） |
| `General.php` | `xn_general` | 系统配置 K-V 存储（`getConfig`/`confSave`），缓存刷新（`reflash`），被 `xn_cfg()` 函数调用 |

#### 3.5.2 盲盒相关模型

| 模型文件 | 对应表 | 说明 |
|---------|--------|------|
| `BlindBoxGoods.php` | `xn_blind_box_goods` | 盲盒关联商品数据 |
| `BlindBoxOdds.php` | `xn_blind_box_odds` | 概率配置 |
| `BlindBoxOddsGroup.php` | `xn_blind_box_odds_group` | 概率分组 |
| `BlindBoxBuy.php` | `xn_blind_box_buy` | 购买方案 |
| `BlindBoxQueue.php` | `xn_blind_box_queue` | 一番赏/福袋排队 |
| `BlindBoxLock.php` | `xn_blind_box_lock` | 盲盒锁定 |
| `BlindBoxXiang.php` | `xn_blind_box_xiang` | 一番赏赏箱（含 `initBoxXiang` 初始化方法） |
| `BlindBoxFukubukuro.php` | `xn_blind_box_fukubukuro` | 福袋数据 |
| `BlindBoxPrizeGiveLog.php` | `xn_blind_box_prize_give_log` | 奖品转赠日志/审核 |
| `BlindBoxLordRecord.php` | `xn_blind_box_lord_record` | 领主赏记录 |
| `BlindBoxMatchGuaranteeGoods.php` | `xn_blind_box_match_guarantee_goods` | 对对碰保底商品 |

#### 3.5.3 会员相关模型

| 模型文件 | 对应表 | 说明 |
|---------|--------|------|
| `MemberAddress.php` | `xn_member_address` | 收货地址 |
| `MemberBank.php` | `xn_member_bank` | 银行卡绑定 |
| `MemberLevel.php` | `xn_member_level` | 会员等级 |
| `MemberConsumptionLevel.php` | `xn_member_consumption_level` | 消费等级 |
| `MemberMoneyLog.php` | `xn_member_money_log` | 资金流水 |
| `MemberCommissionLog.php` | `xn_member_commission_log` | 佣金记录 |
| `MemberPopularizeLog.php` | `xn_member_popularize_log` | 推广日志 |
| `MemberShareLog.php` | `xn_member_share_log` | 分享日志 |
| `MemberQiandaoLog.php` | `xn_member_qiandao_log` | 签到日志 |
| `MemberWithdrawal.php` | `xn_member_withdrawal` | 提现记录 |
| `MemberCouponList.php` | `xn_member_coupon_list` | 用户优惠券 |
| `MemberCdkeyLog.php` | `xn_member_cdkey_log` | CDKEY 兑换日志 |
| `MemberCard.php` | `xn_member_card` | 用户道具卡 |
| `MemberToken.php` | `xn_member_token` | 用户 Token |

#### 3.5.4 福利/活动模型

| 模型文件 | 对应表 | 说明 |
|---------|--------|------|
| `WelfareRoom.php` | `xn_welfare_room` | 福利房 |
| `WelfareRoomParticipant.php` | `xn_welfare_room_participants` | 福利房参与者 |
| `WelfareRoomWinner.php` | `xn_welfare_room_winners` | 福利房中奖者 |
| `WelfareRoomGoods.php` | `xn_welfare_room_goods` | 福利房商品 |
| `WelfarePool.php` | `xn_welfare_pool` | 福利池 |
| `WelfarePoolRecord.php` | `xn_welfare_pool_record` | 福利池参与记录 |
| `WelfarePoolPrize.php` | `xn_welfare_pool_prize` | 福利池奖品 |
| `RedPacket.php` | `xn_red_packet` | 红包模板 |
| `RedPacketLog.php` | `xn_red_packet_log` | 红包领取记录 |
| `SysReward.php` | `xn_sys_reward` | 系统奖励配置 |

#### 3.5.5 商品/内容/其他模型

| 模型文件 | 对应表 | 说明 |
|---------|--------|------|
| `Goods.php` | `xn_goods` | 商品目录 |
| `GoodsMenu.php` | `xn_goods_menu` | 商品分类 |
| `GoodsKami.php` | `xn_goods_kami` | 虚拟卡密商品 |
| `Coupon.php` | `xn_coupon` | 优惠券模板 |
| `Cdkey.php` | `xn_cdkey` | 兑换码 |
| `TaskList.php` | `xn_task_list` | 任务列表 |
| `TaskUserLog.php` | `xn_task_user_log` | 任务完成日志 |
| `QiandaoSet.php` | `xn_qiandao_set` | 签到配置 |
| `IntegralPointsGoods.php` | `xn_integral_points_goods` | 积分商品 |
| `IntegralPointsGoodsCategory.php` | `xn_integral_points_goods_category` | 积分商品分类 |
| `IntegralPointsCoupon.php` | `xn_integral_points_coupon` | 积分优惠券 |
| `TowerLevels.php` | `xn_tower_levels` | 爬塔层级 |
| `TowerLogs.php` | `xn_tower_logs` | 爬塔日志 |
| `TowerUserStatus.php` | `xn_tower_user_status` | 用户爬塔状态 |
| `UserpkLog.php` | `xn_userpk_log` | 擂台 PK 日志 |
| `Comment.php` | `xn_comment` | 评论 |
| `Notice.php` | `xn_notice` | 系统公告 |
| `Advert.php` | `xn_advert` | 广告 |
| `News.php` | `xn_news` | 新闻 |
| `Agreement.php` | `xn_agreement` | 协议 |
| `Cooperation.php` | `xn_cooperation` | 合作申请 |
| `SmsLog.php` | `xn_sms_log` | 短信日志 |

---

### 3.6 公共模块 — `app/common/lib/`（类库与集成）

#### 3.6.1 支付集成（`app/common/lib/Pay/`）

**核心职责**: 统一封装多种支付渠道的下单、回调、退款逻辑。

| 类文件 | 支付方式 | 关键方法 |
|--------|----------|---------|
| `AmpWxPay.php` | 小程序微信支付 | `goPay()` — JSAPI 下单 |
| `AppWxPay.php` | APP 微信支付 | `goPay()` — APP 统一下单 |
| `AppAliPay.php` | APP 支付宝 | `goPay()` — APP 支付签名 |
| `AppAliPay2.php` | APP 支付宝 2 | `goPay()` — 备用支付宝通道 |
| `H5Wxpay.php` | H5 微信支付 | `goPay()` — H5 场景支付 |
| `H5Alipay.php` | H5 支付宝 | `goPay()` — H5 Wap 支付 |
| `H5Alipay2.php` | H5 支付宝 2 | `goPay()` — 备用 H5 通道 |
| `Epay.php` | 易支付网关 | `goPay()` / `go_epay()` / `notify()` — 支持微信/支付宝 |
| `JuhePay.php` | 聚合支付 | `goPay()` — 聚合支付网关 |
| `HeePay.php` | 汇付支付 | `goPay()` — 汇付天下支付 |
| `FbPay.php` | 付呗 | `goPay()` — 付呗支付 |
| `BalancePay.php` | 余额支付 | `goPay()` — 扣减余额，直接触发 Notify 回调 |
| `IntegralPay.php` | 积分支付 | `goPay()` — 扣减积分，直接触发 Notify 回调 |

`Pay/SDK/WeChatDeveloper/` — 微信支付/支付宝 SDK 底层封装（OAuth、支付、小程序等）。

#### 3.6.2 存储服务

| 类文件 | 服务 | 关键方法 |
|--------|------|---------|
| `Oss.php` | 阿里云 OSS | `putFile()` — 上传文件、`delete()` — 删除文件 |
| `Qiniu.php` | 七牛云 | `putFile()` — 上传文件、`delete()` — 删除文件、`getToken()` — 获取上传凭证 |

#### 3.6.3 短信服务

| 类文件 | 服务 | 说明 |
|--------|------|------|
| `Sms/Duanxinbao.php` | 短信宝 | `send()` — 发送短信、`error_msg()` — 错误码映射，对接 `api.smsbao.com` |

#### 3.6.4 身份核验

| 类文件 | 服务 | 说明 |
|--------|------|------|
| `Aliyun/IdentityVerify.php` | 阿里云 Cloudauth | `verifyIdentity()` — 二要素核验（姓名+身份证）、`maskIdCard()` / `maskName()` — 信息脱敏 |

#### 3.6.5 微信登录

| 类文件 | 服务 | 说明 |
|--------|------|------|
| `WxLogin.php` | 微信生态 | `getAccessToken()` — 获取 access_token、`threeLogin()` — 三方登录统一入口（小程序/APP/H5）、微信 API 请求封装 |

#### 3.6.6 其他服务

| 类文件 | 服务 | 说明 |
|--------|------|------|
| `SendEmail.php` | 邮件发送 | 基于 PHPMailer 的邮件封装 |
| `SendCode.php` | 安全码 | 管理员敏感操作的邮件验证码发送 |
| `PairMatchLogger.php` | 对对碰日志 | 游戏日志记录（`gameStart` / `collision` / `gameEnd`），写入文件 + 数据库 |
| `ShortLink/Bslyun.php` | 短链接 | 对接变色龙云 `qr.bslyun.com` 生成短链 |

---

### 3.7 公共模块 — `app/common/controller/`（基础控制器）

| 控制器 | 核心职责 |
|--------|---------|
| `Base.php` | 全局基类 — `validate()` 参数验证、`success()` / `error()` 统一响应、`redirect()` 重定向、响应类型判断 |
| `AdminBase.php` | 后台基类 — 登录状态检查、RBAC 权限校验（`checkAuth` / `checkMenuAuth`）、演示模式拦截、面包屑导航 |
| `ApiBase.php` | API 基类 — `get_uid()` 从 JWT 获取用户 ID、统一 JSON 响应（含 `sysTime`）、参数验证 |
| `IndexBase.php` | 前台基类 — 继承 Base |
| `MerchantBase.php` | 商户基类 — Session 登录检查（`getUid()`）、商户身份验证 |

---

### 3.8 公共函数 — `app/common.php`

**核心职责**: 全局通用辅助函数。  
**关键函数**:

| 函数名 | 功能 |
|--------|------|
| `xn_cfg($name)` | 从 `xn_general` 表读取系统配置（支持 `group.key` 格式，自动缓存） |
| `get_source()` | 获取活动来源映射（新人专享/买一送一/免单白嫖/一周限定等） |
| `get_integer_price()` | 计算积分（多多币/星石）抵扣后的价格 |
| `get_userday_countmoney()` | 查询用户当日消费金额 |
| `get_user_task_day_countmoney()` | 查询用户当日任务消费金额 |
| `get_order()` | 生成唯一订单号 |
| `alipayrefund()` | 支付宝退款 |
| `isCreditNo()` | 身份证号码格式验证 |
| `curl_post()` | HTTP POST 请求封装 |
| `get_host_url()` | 获取当前域名 URL |
| `xn_encrypt()` / `xn_root()` | 加密/路径工具 |
| `del_files()` | 删除文件 |

---

### 3.9 命令行任务 — `app/command/`

**核心职责**: 定时任务与数据维护命令（通过 `php think` 执行）。

| 命令文件 | 注册命令 | 功能说明 | 建议执行频率 |
|---------|---------|---------|-------------|
| `SendDailyRankPrize.php` | `send:daily-rank-prize` | 每日排行榜奖励发放：统计前一日消费排名 → 发放多多币/商品/优惠券/道具卡 | 每日 00:05 |
| `SendWeeklyRankPrize.php` | `send:weekly-rank-prize` | 每周排行榜奖励发放：统计上周消费排名（仅周一可执行） | 每周一 00:10 |
| `WelfareRoomLottery.php` | `welfare:lottery` | 福利房定时开奖：检查到期房间 → 随机抽取中奖者 → 发放奖品 | 每分钟 |
| `CleanQueue.php` | `clean:queue` | 清理排队超时记录：删除加入超过 3 分钟的排队数据 | 每分钟 |
| `CheckLordExpiration.php` | `check:lord-expiration` | 领主过期检查：标记超过 24 小时的领主记录为已过期 | 每小时 |
| `ClearRankingData.php` | `clearRankingData` | 清理排行榜/爬塔缓存数据，重置排名 | 按需/每日 |
| `DayPopularizeLog.php` | `day_popularize_log` | 每日邀请推广统计：统计星级用户的邀请战绩 | 每日 |
| `Caiji.php` | `caiji` | 商品采集：从外部 API 获取商品数据 → 上传图片到 OSS → 入库 | 按需 |
| `MigrateYifanshangBox.php` | `migrate:yifanshang` | 一番赏数据迁移：将旧版一番赏数据迁移到新的赏箱系统 | 一次性 |

---

### 3.10 全局配置 — `config/`

| 配置文件 | 核心职责 |
|---------|---------|
| `app.php` | 应用配置 — 应用映射（`app_map`）、默认时区 `Asia/Shanghai`、URL 后缀、错误显示 |
| `database.php` | 数据库配置 — MySQL 连接（从 `.env` 读取）、表前缀 `xn_`、编码 `utf8mb4` |
| `redis.php` | Redis 配置 — 连接地址/端口/密码 |
| `jwt.php` | JWT 配置 — 密钥（`JWT_SECRET`）、过期时间（TTL）、Token 获取方式 |
| `middleware.php` | 中间件别名 — Session、Check 等全局中间件注册 |
| `route.php` | 路由配置 — pathinfo 模式、默认控制器/操作、URL 参数方式 |
| `filesystem.php` | 文件系统 — 本地存储和 OSS 存储驱动配置 |
| `console.php` | 命令注册 — 定时任务命令类绑定 |
| `session.php` | Session — 存储驱动/过期时间 |
| `cache.php` | 缓存 — 缓存驱动配置 |
| `log.php` | 日志 — 日志通道/级别/格式 |
| `view.php` | 视图 — 模板引擎配置 |
| `captcha.php` | 验证码 — 字体/长度/干扰线配置 |
| `lang.php` | 多语言 — 默认语言/检测方式 |

---

### 3.11 路由 — `route/`

**核心职责**: 路由配置（项目以约定路由为主）。  
**路由规则**:
- 采用 ThinkPHP 多应用 + 默认约定路由（`url_route_must => false`）
- URL 格式：`/{app}/{controller}/{action}`
- API 示例：`/api/login/mobile_login`、`/api/blind_box/open`
- Admin 示例：`/admin/index/home`、`/admin/blind_box/index`
- `app/index/route/app.php` 中有少量自定义路由（注册页等）

---

### 3.12 扩展库 — `extend/`

| 文件/目录 | 说明 |
|----------|------|
| `alipay/` | 支付宝 SDK（Wap 支付、App 支付、转账、退款等） |
| `Predis.php` | Redis 客户端封装 |
| `OpenApi.php` | 开放 API 接口 |
| `NotifyApi.php` | 通知 API 接口 |

---

### 3.13 入口与部署 — `public/`

**核心职责**: Web 服务根目录。  
**关键文件**:
1. `index.php` — 应用唯一入口，定义 `PAY_ROOT`（支付宝 SDK 路径），设置 CORS 头
2. `static/` — 前端静态资源（JS/CSS/图片/字体）
3. `uploads/` — 用户上传文件存储目录
4. `share_code/` — 生成的分享码图片
5. `sql.txt` — 数据库初始化结构文件

---

## 第四部分：源码结构汇总表

| 路径 (Path) | 类型 (Type) | 模块名称 (Module Name) | 核心功能描述 (Key Functionality) | 备注 (Notes) |
|---|---|---|---|---|
| `app/admin/controller/` | 目录 | 后台管理控制器 | 50+ 个控制器，覆盖盲盒/商品/会员/订单/财务/配置/权限全方位管理 | Session + RBAC 认证 |
| `app/admin/controller/Index.php` | 文件 | 后台首页 | 仪表盘展示、菜单渲染、缓存管理 | |
| `app/admin/controller/Login.php` | 文件 | 后台登录 | 管理员登录验证、验证码校验 | |
| `app/admin/controller/BlindBox.php` | 文件 | 盲盒分类管理 | 盲盒 CRUD、类型管理、启停控制 | |
| `app/admin/controller/blind_box/` | 目录 | 盲盒子模块管理 | 商品/概率/概率分组/购买方案/订单/奖品/转赠审核/领主记录 | 含 8 个子控制器 |
| `app/admin/controller/Goods.php` | 文件 | 商品管理 | 商品 CRUD、淘宝同步、上下架 | 对接大淘客 API |
| `app/admin/controller/goods/` | 目录 | 商品子模块管理 | 商品分类、商品订单管理/发货 | |
| `app/admin/controller/Member.php` | 文件 | 会员管理 | 会员列表/搜索/禁用/详情/余额调整 | |
| `app/admin/controller/member/` | 目录 | 会员子模块管理 | 提现审核/地址/资金流水/佣金/推广/等级/消费等级/签到/优惠券/道具卡/银行卡 | 含 12 个子控制器 |
| `app/admin/controller/General.php` | 文件 | 系统配置 | 站点/支付/短信/上传/分销等全局参数配置 | |
| `app/admin/controller/general/` | 目录 | 配置子模块 | 签到设置/爬塔层级/系统银行/短链接/数据清理 | |
| `app/admin/controller/Statistics.php` | 文件 | 数据统计 | 盲盒利润报表、营收分析、用户数据统计 | |
| `app/admin/controller/Rank.php` | 文件 | 排行榜管理 | 日榜/周榜奖励配置与手动发放 | |
| `app/admin/controller/WelfareRoom.php` | 文件 | 福利房管理 | 官方/用户福利房管理 | |
| `app/admin/controller/WelfarePool.php` | 文件 | 福利池管理 | 福利池奖品配置 | |
| `app/admin/controller/Auth.php` | 文件 | 权限管理 | RBAC 权限规则/菜单管理 | |
| `app/admin/controller/AuthGroup.php` | 文件 | 角色管理 | 角色组创建与权限分配 | |
| `app/admin/controller/Task.php` | 文件 | 任务管理 | 每日任务配置与奖励设置 | |
| `app/admin/controller/RedPacket.php` | 文件 | 红包管理 | 红包口令创建/编辑/日志 | |
| `app/admin/middleware/AdminCheck.php` | 文件 | 安全码中间件 | 后台敏感操作邮件验证码校验 | |
| `app/admin/view/` | 目录 | 后台视图 | HTML 模板（layui），涵盖所有后台管理页面 | |
| `app/api/controller/Login.php` | 文件 | 用户登录 | 短信登录/微信登录/手机号一键登录/注册/JWT 颁发 | 公开接口 |
| `app/api/controller/Member.php` | 文件 | 用户中心 | 个人信息/提现/签到/分享/地址/优惠券/CDKEY/团队/任务/注销 | 30+ 个接口 |
| `app/api/controller/Common.php` | 文件 | 公共接口 | 首页数据/盲盒列表/商品列表/配置/协议/爬塔/身份核验/版本 | 40+ 个接口，大部分公开 |
| `app/api/controller/BlindBox.php` | 文件 | 盲盒开箱 | 普通开箱/对对碰(54 张卡牌)/一番赏/福袋/排队/锁箱 | 核心业务逻辑 |
| `app/api/controller/Pay.php` | 文件 | 支付入口 | 盲盒/商品/充值/运费支付，支持 13 种支付方式 | 统一支付网关 |
| `app/api/controller/Notify.php` | 文件 | 支付回调 | 各渠道异步回调处理、订单状态更新、业务分发、分销佣金 | 公开接口 |
| `app/api/controller/Order.php` | 文件 | 订单管理 | 订单查询/奖品兑换/转赠/发货/确认收货/重抽/物流 | |
| `app/api/controller/PrizeRecord.php` | 文件 | 奖品管理 | 奖品查询/进阶兑换/保险箱/福利房中奖/最新记录 | |
| `app/api/controller/WelfareRoom.php` | 文件 | 福利房 | 房间列表/创建/加入/详情/自动开奖 | |
| `app/api/controller/WelfarePool.php` | 文件 | 福利池 | 池列表/详情/加入抽奖（Redis 库存+权重随机） | |
| `app/api/controller/Rank.php` | 文件 | 排行榜 | 日/周消费排名、排名奖励发放 | |
| `app/api/controller/RedPacket.php` | 文件 | 红包 | 红包口令查询与使用 | |
| `app/api/controller/Comment.php` | 文件 | 评论 | 评论发布/按商品or订单查询/用户名脱敏 | |
| `app/api/controller/Identity.php` | 文件 | 身份核验 | 二要素实名认证（阿里云）、每日限额、防重复 | |
| `app/api/controller/IntegralPointsGoods.php` | 文件 | 积分商城 | 积分商品列表/详情/兑换（扣积分+生成奖品） | |
| `app/api/controller/IntegralPointsCoupon.php` | 文件 | 积分优惠券 | 积分优惠券列表/详情/兑换 | |
| `app/api/controller/Upload.php` | 文件 | 文件上传 | 图片上传（禁 PHP/水印）→ OSS/七牛/本地 | |
| `app/api/controller/Cooperation.php` | 文件 | 合作申请 | 合作申请提交（24h 去重） | |
| `app/api/controller/LordRecord.php` | 文件 | 领主记录 | 领主赏历史/收益/任期查询 | |
| `app/api/middleware/Jwt.php` | 文件 | JWT 中间件 | Token 解析/校验/自动刷新/白名单 | API 认证核心 |
| `app/index/` | 目录 | PC 端应用 | 首页展示、注册页、分享跳转 | |
| `app/merchant/` | 目录 | 商户端应用 | 分销代理后台、团队管理、收益统计 | Session 认证 |
| `app/common/controller/Base.php` | 文件 | 全局基类 | 参数验证、统一响应、重定向 | 所有控制器基类 |
| `app/common/controller/AdminBase.php` | 文件 | Admin 基类 | 登录检查、RBAC 校验、演示模式、面包屑 | |
| `app/common/controller/ApiBase.php` | 文件 | API 基类 | JWT uid 获取、统一 JSON 响应 | |
| `app/common/model/Member.php` | 文件 | 会员模型 | 登录注册、用户信息、邀请码、分享码生成 | 核心模型 |
| `app/common/model/BlindBox.php` | 文件 | 盲盒模型 | 盲盒列表/详情查询、缓存、购买方案 | |
| `app/common/model/BlindBoxOrder.php` | 文件 | 盲盒订单模型 | 订单创建、开奖核心逻辑（普通/一番赏/福袋/对对碰） | 核心业务 |
| `app/common/model/BlindBoxPrizeRecord.php` | 文件 | 奖品记录模型 | **抽奖核心** — 概率计算/一番赏开奖/福袋抽取/保底/领主赏/兑换/转赠/发货 | 最核心业务模型 |
| `app/common/model/MemberMoneyLog.php` | 文件 | 资金流水模型 | `set_money()` 处理所有余额/积分/佣金增减 | 资金核心 |
| `app/common/model/General.php` | 文件 | 系统配置模型 | K-V 配置存储/读取/缓存 | 被 `xn_cfg()` 调用 |
| `app/common/model/Recharge.php` | 文件 | 充值订单模型 | 充值订单创建/查询/状态管理 | |
| `app/common/model/GoodsOrder.php` | 文件 | 商品订单模型 | 商品订单管理/发货/物流 | |
| `app/common/model/WelfareRoom.php` | 文件 | 福利房模型 | 福利房数据管理 | |
| `app/common/model/WelfarePool.php` | 文件 | 福利池模型 | 福利池数据管理 | |
| `app/common/lib/Pay/` | 目录 | 支付集成 | 13 种支付方式封装（微信/支付宝/易支付/聚合/汇付/付呗/余额/积分） | 含 SDK |
| `app/common/lib/Oss.php` | 文件 | 阿里云 OSS | 文件上传/删除 | |
| `app/common/lib/Qiniu.php` | 文件 | 七牛云 | 文件上传/删除/Token | |
| `app/common/lib/Sms/Duanxinbao.php` | 文件 | 短信服务 | 短信宝短信发送 | api.smsbao.com |
| `app/common/lib/Aliyun/IdentityVerify.php` | 文件 | 身份核验 | 阿里云二要素实名认证 | Cloudauth |
| `app/common/lib/WxLogin.php` | 文件 | 微信登录 | 小程序/APP/H5 微信登录封装 | |
| `app/common/lib/PairMatchLogger.php` | 文件 | 对对碰日志 | 游戏过程日志（文件+数据库） | |
| `app/common/lib/SendEmail.php` | 文件 | 邮件服务 | PHPMailer 邮件封装 | |
| `app/common/lib/SendCode.php` | 文件 | 安全码 | 管理员操作验证码邮件 | |
| `app/common/lib/ShortLink/Bslyun.php` | 文件 | 短链接 | 变色龙云短链生成 | |
| `app/common.php` | 文件 | 全局函数 | `xn_cfg()`配置读取/`get_source()`活动来源/`get_integer_price()`积分抵扣/订单号生成/退款 | |
| `app/command/SendDailyRankPrize.php` | 文件 | 日榜奖励 | 每日排行榜奖品发放定时任务 | cron |
| `app/command/SendWeeklyRankPrize.php` | 文件 | 周榜奖励 | 每周排行榜奖品发放定时任务（周一） | cron |
| `app/command/WelfareRoomLottery.php` | 文件 | 福利房开奖 | 定时检查到期福利房并执行开奖 | cron |
| `app/command/CleanQueue.php` | 文件 | 清理排队 | 清理超过 3 分钟的排队超时记录 | cron |
| `app/command/CheckLordExpiration.php` | 文件 | 领主过期 | 标记超 24h 领主记录为过期 | cron |
| `app/command/ClearRankingData.php` | 文件 | 清理排行 | 重置爬塔排行榜与缓存 | cron |
| `app/command/DayPopularizeLog.php` | 文件 | 推广统计 | 每日邀请推广战绩统计 | cron |
| `app/command/Caiji.php` | 文件 | 商品采集 | 外部 API 商品采集并上传 OSS | 按需 |
| `app/command/MigrateYifanshangBox.php` | 文件 | 一番赏迁移 | 旧数据迁移到新赏箱系统 | 一次性 |
| `config/app.php` | 文件 | 应用配置 | 时区/默认应用/URL 后缀/错误显示 | |
| `config/database.php` | 文件 | 数据库配置 | MySQL 连接/表前缀 `xn_` | 读 `.env` |
| `config/jwt.php` | 文件 | JWT 配置 | 密钥/TTL/Token 获取方式 | |
| `config/redis.php` | 文件 | Redis 配置 | 连接地址/端口/密码 | |
| `config/console.php` | 文件 | 命令注册 | CLI 命令类注册 | |
| `extend/alipay/` | 目录 | 支付宝 SDK | Wap/App 支付、转账、退款 | |
| `extend/Predis.php` | 文件 | Redis 客户端 | Redis 连接封装 | |
| `public/index.php` | 文件 | 入口文件 | Web 入口、CORS 设置、路径定义 | |
| `public/sql.txt` | 文件 | 数据库结构 | 数据库初始化 SQL | |
| `.env` | 文件 | 环境变量 | 数据库/JWT/版本/域名等敏感配置 | **勿提交** |
| `composer.json` | 文件 | 依赖管理 | Composer 包依赖定义 | |

---

## 附录 A：核心业务流程简述

### A1. 盲盒开箱流程

```
用户下单 → Pay.go_pay() 生成充值订单 → 支付渠道下单
    → 支付成功 → Notify 回调 → 创建盲盒订单 (BlindBoxOrder.add_order)
    → 用户点击开箱 → BlindBox.open() → BlindBoxOrder.order_open()
    → BlindBoxPrizeRecord.get_open_prize() 概率抽奖
    → 生成奖品记录 → 用户查看奖品 → 兑换/发货/转赠
```

### A2. 对对碰流程

```
选择心愿商品 → choose_wish_goods()
    → 54张卡牌初始化 → 逐次翻牌碰撞 pair_box_collision()
    → 匹配成功：获得对应商品
    → 匹配失败：计数+1，达到保底次数(3/6/9/14)触发保底
    → 心愿卡出现：open_wish_card() 直接获得心愿商品
    → 游戏结束
```

### A3. 支付回调分发流程

```
支付渠道回调 → Notify.recharge_xxx_notify()
    → 验证签名 → recharge_notify()
    → 更新充值订单状态 → 根据 order_type 分发：
        ├── type=1: add_blind_box_order (盲盒订单)
        ├── type=2: add_goods_order (商品订单)
        ├── type=3: batch_apply_deliver (批量发货)
        ├── type=4: add_balance_recharge (余额充值)
        └── type=5: add_goods_to_warehouse (商品入仓)
    → 消费等级检查升级 → 分销佣金结算
```

### A4. 福利房开奖流程

```
创建房间 (从仓库选择奖品) → 其他用户加入 (检查消费门槛/密码/容量)
    → 人满触发 / 定时触发 → WelfareRoomLottery 执行开奖
    → 随机抽取中奖者 → 奖品转移到中奖者仓库
```

---

## 附录 B：数据库表清单

| 表名 | 说明 |
|------|------|
| `xn_member` | 会员 |
| `xn_member_address` | 收货地址 |
| `xn_member_bank` | 银行卡 |
| `xn_member_level` | 会员等级 |
| `xn_member_consumption_level` | 消费等级 |
| `xn_member_money_log` | 资金流水 |
| `xn_member_commission_log` | 佣金记录 |
| `xn_member_popularize_log` | 推广日志 |
| `xn_member_share_log` | 分享日志 |
| `xn_member_qiandao_log` | 签到日志 |
| `xn_member_withdrawal` | 提现记录 |
| `xn_member_coupon_list` | 用户优惠券 |
| `xn_member_cdkey_log` | CDKEY 兑换日志 |
| `xn_member_card` | 用户道具卡 |
| `xn_member_token` | 用户 Token |
| `xn_blind_box` | 盲盒分类 |
| `xn_blind_box_goods` | 盲盒商品 |
| `xn_blind_box_odds` | 盲盒概率 |
| `xn_blind_box_odds_group` | 概率分组 |
| `xn_blind_box_buy` | 购买方案 |
| `xn_blind_box_order` | 盲盒订单 |
| `xn_blind_box_prize_record` | 奖品记录 |
| `xn_blind_box_prize_give_log` | 转赠日志 |
| `xn_blind_box_queue` | 排队记录 |
| `xn_blind_box_lock` | 盲盒锁定 |
| `xn_blind_box_xiang` | 一番赏赏箱 |
| `xn_blind_box_fukubukuro` | 福袋 |
| `xn_blind_box_match_record` | 对对碰记录 |
| `xn_blind_box_match_guarantee_goods` | 对对碰保底商品 |
| `xn_blind_box_lord_record` | 领主记录 |
| `xn_goods` | 商品 |
| `xn_goods_menu` | 商品分类 |
| `xn_goods_order` | 商品订单 |
| `xn_goods_kami` | 虚拟卡密 |
| `xn_recharge` | 充值订单 |
| `xn_welfare_room` | 福利房 |
| `xn_welfare_room_participants` | 福利房参与者 |
| `xn_welfare_room_winners` | 福利房中奖者 |
| `xn_welfare_room_goods` | 福利房商品 |
| `xn_welfare_pool` | 福利池 |
| `xn_welfare_pool_record` | 福利池记录 |
| `xn_welfare_pool_prize` | 福利池奖品 |
| `xn_general` | 系统配置 |
| `xn_admin` | 管理员 |
| `xn_auth_rule` | 权限规则 |
| `xn_auth_group` | 角色组 |
| `xn_auth_group_access` | 角色权限关联 |
| `xn_admin_log` | 管理员操作日志 |
| `xn_red_packet` | 红包 |
| `xn_red_packet_log` | 红包领取记录 |
| `xn_coupon` | 优惠券模板 |
| `xn_cdkey` | 兑换码 |
| `xn_task_list` | 任务列表 |
| `xn_task_user_log` | 任务完成日志 |
| `xn_qiandao_set` | 签到配置 |
| `xn_integral_points_goods` | 积分商品 |
| `xn_integral_points_goods_category` | 积分商品分类 |
| `xn_integral_points_coupon` | 积分优惠券 |
| `xn_tower_levels` | 爬塔层级 |
| `xn_tower_logs` | 爬塔日志 |
| `xn_tower_user_status` | 用户爬塔状态 |
| `xn_userpk_log` | 擂台 PK 日志 |
| `xn_sys_reward` | 系统奖励 |
| `xn_comment` | 评论 |
| `xn_notice` | 公告 |
| `xn_advert` | 广告 |
| `xn_news` | 新闻 |
| `xn_agreement` | 协议 |
| `xn_cooperation` | 合作申请 |
| `xn_sms_log` | 短信日志 |
| `xn_newer` | 新人活动 |
| `xn_zhuanti` | 专题 |
| `xn_card` | 道具卡模板 |
| `xn_bank_list` | 银行列表 |
| `xn_short_link` | 短链接 |
| `xn_version_manager` | 版本管理 |
| `xn_app_version` | APP 版本 |
| `xn_friendly_link` | 友情链接 |
| `xn_kuaidi100_code` | 快递编码 |
| `xn_upload_files` | 上传文件 |

---

## 附录 C：环境变量配置项（.env）

| 配置项 | 说明 |
|--------|------|
| `DATABASE_HOSTNAME` | 数据库主机 |
| `DATABASE_DATABASE` | 数据库名 |
| `DATABASE_USERNAME` | 数据库用户名 |
| `DATABASE_PASSWORD` | 数据库密码 |
| `DATABASE_HOSTPORT` | 数据库端口 |
| `DATABASE_PREFIX` | 表前缀（`xn_`） |
| `JWT_SECRET` | JWT 签名密钥 |
| `APP_DEBUG` | 调试模式 |
| `APP_VERSION` | 应用版本 |
| `APP_HOST` | 应用域名 |
| `APP_ISDEMO` | 是否演示模式 |

---

> **文档说明**: 本文档基于源码静态分析自动生成，覆盖项目主要目录、文件和业务逻辑。如有新增模块或业务变更，请及时更新本文档。