445 lines
16 KiB
Markdown
445 lines
16 KiB
Markdown
# GGL 项目分析文档
|
||
|
||
## 一、项目概述
|
||
|
||
本项目是一个基于 **Webman（Workerman）** 框架构建的 **游戏聚合 + 支付平台** 后端系统，提供玩家端 API、第三方回调接口以及后台管理系统（ExAdmin）。
|
||
|
||
- **框架**: Webman (workerman/webman-framework ^1.5.0)
|
||
- **语言**: PHP >= 7.2
|
||
- **ORM**: Illuminate Database (Eloquent) ^8.83
|
||
- **后台管理**: ExAdmin (rockys/ex-admin-webman ^1.0)
|
||
- **HTTP 监听**: `http://0.0.0.0:8786`
|
||
- **进程数**: `cpu_count() * 4`
|
||
|
||
---
|
||
|
||
## 二、项目目录结构
|
||
|
||
```
|
||
ggl/
|
||
├── addons/webman/ # ExAdmin 后台管理模块
|
||
│ ├── controller/ # 后台控制器 (28个)
|
||
│ ├── model/ # Eloquent 数据模型 (60+)
|
||
│ ├── middleware/ # 后台中间件
|
||
│ ├── database/ # 数据库迁移 & 种子
|
||
│ ├── service/ # 菜单等服务
|
||
│ ├── token/ # Token 驱动
|
||
│ ├── traits/ # 公共 Trait
|
||
│ ├── validator/ # 验证器
|
||
│ ├── common/ # 公共组件 (登录/系统)
|
||
│ ├── echart/ # 图表组件
|
||
│ ├── form/ # 表单组件
|
||
│ └── grid/ # 列表组件
|
||
├── app/
|
||
│ ├── api/controller/v1/ # 玩家端 API 控制器
|
||
│ ├── external/ # 外部回调 API 控制器
|
||
│ ├── exception/ # 异常处理
|
||
│ ├── middleware/ # 应用中间件
|
||
│ ├── queue/redis/ # Redis 队列消费者
|
||
│ ├── service/ # 业务服务层
|
||
│ │ └── game/ # 游戏平台接口适配
|
||
│ └── functions.php # 全局函数
|
||
├── config/ # 配置文件
|
||
├── db/migrations/ # Phinx 数据库迁移
|
||
├── process/ # 自定义进程
|
||
├── public/ # Web 静态资源
|
||
├── resource/translations/ # 多语言资源 (zh_CN, en, Ma_my, cam_dia)
|
||
├── runtime/ # 运行时文件 (日志/缓存)
|
||
├── support/ # 框架辅助文件
|
||
├── composer.json
|
||
├── start.php # Linux 入口
|
||
└── windows.php # Windows 入口
|
||
```
|
||
|
||
---
|
||
|
||
## 三、核心功能模块
|
||
|
||
### 3.1 玩家端功能
|
||
|
||
| 模块 | 功能描述 |
|
||
|------|----------|
|
||
| 用户认证 | 手机号注册、短信验证码、登录、登出、忘记密码 |
|
||
| 玩家信息 | 获取玩家信息、编辑昵称 |
|
||
| 银行卡管理 | 银行列表、添加/编辑/删除银行卡 |
|
||
| 充值功能 | 充值列表、充值项配置、玩家充值、上传凭证、SePay充值 |
|
||
| 提现功能 | 提现申请、SePay提现 |
|
||
| 账单记录 | Cash In/Out列表、充提记录、游戏记录 |
|
||
| 游戏中心 | 登录游戏、获取游戏地址 |
|
||
| 抽奖系统 | 奖品列表、抽奖、抽奖记录 |
|
||
| 数据中心 | 礼品中心 |
|
||
| 版本更新 | APP 版本检测更新 |
|
||
|
||
### 3.2 后台管理功能
|
||
|
||
| 模块 | 功能描述 |
|
||
|------|----------|
|
||
| 仪表盘 | 登录数据、玩家数据、充值/提现数据、图表统计 |
|
||
| 玩家管理 | 玩家列表、等级设置、标签管理、人工充值/提现、钱包管理、密码重置 |
|
||
| 游戏管理 | 游戏列表、进入游戏、奖品管理、每日库存补充、游戏服务配置 |
|
||
| 充值管理 | 充值记录、充值审核、充值方式配置、快捷支付配置 |
|
||
| 提现管理 | 提现记录、提现审核（通过/拒绝）、付款处理 |
|
||
| 渠道管理 | 渠道列表、渠道管理员、渠道配置 |
|
||
| 系统管理 | 菜单管理、角色权限管理、部门管理、岗位管理、系统设置 |
|
||
| 货币管理 | 货币列表、货币配置 |
|
||
| APP版本管理 | Android/iOS 版本管理、渠道配置、APK解压 |
|
||
| 附件管理 | 文件上传、分类管理 |
|
||
| 游戏记录 | 玩家游戏记录查询 |
|
||
| 配送记录 | 玩家配送记录查询 |
|
||
|
||
### 3.3 第三方集成
|
||
|
||
| 服务 | 说明 |
|
||
|------|------|
|
||
| SKL Pay | 支付充值、提现、回调通知 |
|
||
| One Pay | 支付服务 |
|
||
| Se Pay | 支付充值、提现服务 |
|
||
| 短信服务 | Weiqucloud 短信 API（含日本/台湾短信） |
|
||
| Facebook SDK | Facebook Graph SDK 集成 |
|
||
| WebSocket 推送 | webman/push 实时消息推送 |
|
||
|
||
### 3.4 游戏平台适配
|
||
|
||
通过 `GameServiceInterface` 统一接口 + `GameServiceFactory` 工厂模式，接入多个游戏平台：
|
||
|
||
| 游戏平台 | 接口文件 |
|
||
|----------|----------|
|
||
| MEGA888 | MeGa888ServiceInterface.php |
|
||
| KISS918 | Kiss918ServiceInterface.php |
|
||
| Joker | JokerServiceInterface.php |
|
||
| JiLi | JiLiServiceInterface.php |
|
||
| JDB | JDBServiceInterface.php |
|
||
| Pragmatic | PragmaticServiceInterface.php |
|
||
| LionKing | LionKingServiceInterface.php |
|
||
| Lucky365 | Lucky365ServiceInterface.php |
|
||
| MarioClub | MarioClubServiceInterface.php |
|
||
| MonkeyKing | MonkeyKingServiceInterface.php |
|
||
| NextSpin | NextSpinServiceInterface.php |
|
||
| BigGaming | BigGamingServiceInterface.php |
|
||
| CS | CSServiceInterface.php |
|
||
|
||
统一接口方法：`createPlayer()`、`getPlayer()`、`getSimpleGameList()`、`login()`
|
||
|
||
---
|
||
|
||
## 四、API 接口清单
|
||
|
||
### 4.1 玩家端 API（`/api/v1`）
|
||
|
||
> 请求方式：全部为 **POST**
|
||
> 中间件：`SiteAuthMiddleware`（需要 `Site-Id` 请求头）、`Lang`（多语言）、`AppVersionMiddleware`（版本校验）
|
||
|
||
#### 4.1.1 认证与用户
|
||
|
||
| 接口路径 | 控制器方法 | 功能说明 |
|
||
|----------|-----------|----------|
|
||
| `/api/v1/phone-register` | PlayerController@phoneRegister | 手机号注册 |
|
||
| `/api/v1/send-msg` | PlayerController@sendMsg | 发送短信验证码 |
|
||
| `/api/v1/login` | PlayerController@login | 玩家登录 |
|
||
| `/api/v1/logout` | IndexController@logout | 玩家登出 |
|
||
| `/api/v1/forget-password` | PlayerController@forgetPassword | 忘记密码 |
|
||
| `/api/v1/player-info` | PlayerController@playerInfo | 获取玩家信息 |
|
||
| `/api/v1/edit-player-name` | PlayerController@editPlayerName | 编辑玩家昵称 |
|
||
|
||
#### 4.1.2 银行卡管理
|
||
|
||
| 接口路径 | 控制器方法 | 功能说明 |
|
||
|----------|-----------|----------|
|
||
| `/api/v1/bank-list` | IndexController@bankList | 获取银行列表 |
|
||
| `/api/v1/bank-card-list` | IndexController@bankCardList | 获取用户银行卡列表 |
|
||
| `/api/v1/add-bank-card` | IndexController@addBankCard | 添加银行卡 |
|
||
| `/api/v1/edit-bank-card` | IndexController@editBankCard | 修改银行卡 |
|
||
| `/api/v1/delete-bank-card` | IndexController@deleteBankCard | 删除银行卡 |
|
||
|
||
#### 4.1.3 充值相关
|
||
|
||
| 接口路径 | 控制器方法 | 功能说明 |
|
||
|----------|-----------|----------|
|
||
| `/api/v1/recharge-list` | PlayerController@rechargeList | 获取充值列表 |
|
||
| `/api/v1/recharge-setting-list` | PlayerController@rechargeSettingList | 获取充值项配置列表 |
|
||
| `/api/v1/recharge-info` | PlayerController@rechargeInfo | 获取充值配置详情 |
|
||
| `/api/v1/player-recharge` | IndexController@playerRecharge | 玩家充值 |
|
||
| `/api/v1/upload-certificate` | IndexController@uploadCertificate | 上传充值凭证 |
|
||
| `/api/v1/complete-recharge` | PlayerController@completeRecharge | 完成充值 |
|
||
| `/api/v1/se-recharge-list` | PlayerController@seRechargeList | SePay充值列表 |
|
||
| `/api/v1/se-recharge` | PlayerController@seRecharge | SePay充值 |
|
||
|
||
#### 4.1.4 提现相关
|
||
|
||
| 接口路径 | 控制器方法 | 功能说明 |
|
||
|----------|-----------|----------|
|
||
| `/api/v1/withdrawal` | IndexController@playerWithdrawal | 玩家提现 |
|
||
| `/api/v1/se-withdrawal` | PlayerController@seWithdrawal | SePay提现 |
|
||
|
||
#### 4.1.5 账单与记录
|
||
|
||
| 接口路径 | 控制器方法 | 功能说明 |
|
||
|----------|-----------|----------|
|
||
| `/api/v1/cash-out-list` | IndexController@cashOutList | Cash Out 列表 |
|
||
| `/api/v1/cash-in-list` | IndexController@cashInList | Cash In 列表 |
|
||
| `/api/v1/game-record` | PlayerController@gameRecord | 游戏记录 |
|
||
| `/api/v1/deposit-withdrawal-records` | PlayerController@depositWithdrawalRecord | 充提记录 |
|
||
|
||
#### 4.1.6 游戏相关
|
||
|
||
| 接口路径 | 控制器方法 | 功能说明 |
|
||
|----------|-----------|----------|
|
||
| `/api/v1/login-game` | GameController@loginGame | 登录游戏（返回游戏地址）|
|
||
| `/api/v1/gametest` | GameController@gametest | 游戏测试接口 |
|
||
|
||
#### 4.1.7 抽奖系统
|
||
|
||
| 接口路径 | 控制器方法 | 功能说明 |
|
||
|----------|-----------|----------|
|
||
| `/api/v1/prize-list` | GameController@getPrizeList | 获取奖品列表 |
|
||
| `/api/v1/lottery` | GameController@lottery | 执行抽奖 |
|
||
| `/api/v1/draw-records` | GameController@getDrawRecords | 获取抽奖记录 |
|
||
|
||
#### 4.1.8 其他
|
||
|
||
| 接口路径 | 控制器方法 | 功能说明 |
|
||
|----------|-----------|----------|
|
||
| `/api/v1/get-app-update` | VersionController@getAppUpdate | 获取APP版本更新信息 |
|
||
| `/api/v1/channel-info` | IndexController@channelInfo | 获取渠道信息 |
|
||
| `/api/v1/gift-center` | PlayerController@giftCenter | 数据中心/礼品中心 |
|
||
|
||
---
|
||
|
||
### 4.2 外部回调接口（`/external`）
|
||
|
||
| 接口路径 | 请求方式 | 控制器方法 | 功能说明 |
|
||
|----------|---------|-----------|----------|
|
||
| `/external/login` | GET | ExternalApiController@login | 外部登录页面 |
|
||
| `/external/download` | GET | ExternalApiController@download | 外部下载页面 |
|
||
| `/external/skl-recharge-notify` | POST | ExternalApiController@sklRechargeNotify | SKL支付充值回调 |
|
||
| `/external/skl-withdrawal-notify` | POST | ExternalApiController@sklWithdrawalNotify | SKL支付提现回调 |
|
||
| `/external/skl-query/` | GET | ExternalApiController@sklQuery | SKL支付跳转查询 |
|
||
|
||
---
|
||
|
||
### 4.3 后台管理接口
|
||
|
||
后台基于 ExAdmin 自动生成 CRUD 路由，默认路径前缀为 `/admin` 和 `/agent`。
|
||
|
||
#### 主要管理模块
|
||
|
||
| 模块 | 控制器 | 主要功能 |
|
||
|------|--------|----------|
|
||
| 管理员 | AdminController | 管理员列表、修改密码、编辑信息、重置密码 |
|
||
| 仪表盘 | IndexController | 登录/玩家/充值/提现数据统计、图表 |
|
||
| 玩家管理 | PlayerController | 玩家CRUD、等级/标签、人工充提、钱包、记录查询 |
|
||
| 游戏管理 | GameController | 游戏CRUD、进入游戏、奖品管理、服务配置 |
|
||
| 充值记录 | RechargeRecordController | 充值记录查询、玩家详情 |
|
||
| 提现记录 | WithdrawRecordController | 提现记录查询、玩家详情 |
|
||
| 菜单管理 | MenuController | 菜单CRUD |
|
||
| 角色管理 | RoleController | 角色CRUD、权限分配 |
|
||
| 部门管理 | DepartmentController | 部门CRUD |
|
||
| 岗位管理 | PostController | 岗位CRUD |
|
||
| 系统设置 | SystemSettingController | 系统配置、结算日期 |
|
||
| 货币管理 | CurrencyController | 货币CRUD |
|
||
| APP版本 | AppVersionController | Android/iOS版本管理 |
|
||
| 附件管理 | AttachmentController | 文件上传、分类 |
|
||
| 游戏记录 | PlayGameRecordController | 游戏记录查询 |
|
||
| 配送记录 | PlayerDeliveryRecordController | 配送记录查询 |
|
||
|
||
#### 渠道端管理模块（`/agent`）
|
||
|
||
| 模块 | 控制器 | 主要功能 |
|
||
|------|--------|----------|
|
||
| 渠道仪表盘 | ChannelIndexController | 渠道数据统计 |
|
||
| 渠道玩家 | ChannelPlayerController | 玩家管理、推广员绑定 |
|
||
| 渠道管理 | ChannelController | 渠道CRUD |
|
||
| 渠道管理员 | ChannelAdminController | 渠道管理员CRUD |
|
||
| 渠道充值记录 | ChannelRechargeRecordController | 充值审核（通过/拒绝）、凭证查看 |
|
||
| 渠道充值配置 | ChannelRechargeController | 充值方式、快捷支付配置 |
|
||
| 渠道提现记录 | ChannelWithdrawRecordController | 提现审核、付款处理 |
|
||
| 渠道游戏 | ChannelGameController | 游戏管理 |
|
||
| 渠道岗位 | ChannelPostController | 岗位管理 |
|
||
| 渠道游戏记录 | ChannelPlayGameRecordController | 游戏记录 |
|
||
| 渠道配送记录 | ChannelPlayerDeliveryRecordController | 配送记录 |
|
||
|
||
---
|
||
|
||
## 五、中间件
|
||
|
||
### 5.1 应用中间件（API 请求）
|
||
|
||
| 中间件 | 作用 |
|
||
|--------|------|
|
||
| SiteAuthMiddleware | 站点/渠道验证，通过 `Site-Id` 请求头识别渠道 |
|
||
| Lang | 多语言处理 |
|
||
| AppVersionMiddleware | APP 版本校验 |
|
||
|
||
### 5.2 后台中间件
|
||
|
||
| 中间件 | 作用 |
|
||
|--------|------|
|
||
| AuthMiddleware | 后台管理员登录鉴权 |
|
||
| Permission | 角色权限校验 |
|
||
| LoadLangPack | 语言包加载 |
|
||
| RequestMiddleware | 请求预处理 |
|
||
|
||
---
|
||
|
||
## 六、数据模型
|
||
|
||
### 6.1 玩家相关
|
||
|
||
| 模型 | 说明 |
|
||
|------|------|
|
||
| Player | 玩家基础信息 |
|
||
| PlayerExtend | 玩家扩展信息 |
|
||
| PlayerBank | 玩家银行卡 |
|
||
| PlayerRechargeRecord | 充值记录 |
|
||
| PlayerWithdrawRecord | 提现记录 |
|
||
| PlayerDeliveryRecord | 配送记录 |
|
||
| PlayerLoginRecord | 登录记录 |
|
||
| PlayerRegisterRecord | 注册记录 |
|
||
| PlayerEditLog | 编辑日志 |
|
||
| PlayerTag | 玩家标签 |
|
||
| PlayerLevel | 玩家等级 |
|
||
| PlayerPromoter | 推广员 |
|
||
| PlayerGamePlatform | 玩家游戏平台关联 |
|
||
| PlayerGameRecord | 游戏记录 |
|
||
| PlayerLotteryRecord | 抽奖记录 |
|
||
| PlayerChipRecord | 筹码记录 |
|
||
| PlayerBankruptcyRecord | 破产记录 |
|
||
| PlayerPlatformCash | 平台现金 |
|
||
| PlayerMoneyEditLog | 资金变动日志 |
|
||
| PlayerWalletTransfer | 钱包转账 |
|
||
|
||
### 6.2 渠道相关
|
||
|
||
| 模型 | 说明 |
|
||
|------|------|
|
||
| Channel | 渠道 |
|
||
| ChannelRechargeMethod | 渠道充值方式 |
|
||
| ChannelRechargeMethodLang | 充值方式多语言 |
|
||
| ChannelRechargeSetting | 渠道充值配置 |
|
||
| ChannelFinancialRecord | 渠道财务记录 |
|
||
|
||
### 6.3 管理后台相关
|
||
|
||
| 模型 | 说明 |
|
||
|------|------|
|
||
| AdminUser | 管理员用户 |
|
||
| AdminRole | 管理角色 |
|
||
| AdminMenu | 管理菜单 |
|
||
| AdminConfig | 管理配置 |
|
||
| AdminDepartment | 部门 |
|
||
| AdminPost | 岗位 |
|
||
| AdminFileAttachment | 文件附件 |
|
||
|
||
### 6.4 业务相关
|
||
|
||
| 模型 | 说明 |
|
||
|------|------|
|
||
| Game | 游戏 |
|
||
| GamePlatform | 游戏平台 |
|
||
| GameType | 游戏类型 |
|
||
| Currency | 货币 |
|
||
| BankList | 银行列表 |
|
||
| Prize | 奖品 |
|
||
| DrawRecord | 抽奖记录 |
|
||
| Notice / Announcement | 公告/通知 |
|
||
| Activity / ActivityContent | 活动 |
|
||
| SepayRecharge | SePay充值记录 |
|
||
| Qrcode / QrcodeBatch / QrcodeOwner | 二维码管理 |
|
||
| PromoterProfitRecord | 推广员利润记录 |
|
||
| CommissionRecord | 佣金记录 |
|
||
| Broadcast | 广播消息 |
|
||
| AppVersion | APP版本 |
|
||
| SystemSetting | 系统设置 |
|
||
| ExternalApp | 外部应用 |
|
||
| ApiErrorLog | API 错误日志 |
|
||
| PhoneSmsLog | 短信日志 |
|
||
|
||
---
|
||
|
||
## 七、技术架构
|
||
|
||
### 7.1 核心依赖
|
||
|
||
| 依赖包 | 版本 | 用途 |
|
||
|--------|------|------|
|
||
| workerman/webman-framework | ^1.5.0 | Web 框架核心 |
|
||
| illuminate/database | ^8.83 | Eloquent ORM |
|
||
| rockys/ex-admin-webman | ^1.0 | 后台管理系统 |
|
||
| tinywan/jwt | ^1.6 | JWT 鉴权 |
|
||
| webman/push | ^1.0 | WebSocket 推送 |
|
||
| webman/redis-queue | ^1.2 | Redis 消息队列 |
|
||
| workerman/crontab | ^1.0 | 定时任务 |
|
||
| symfony/translation | ^5.4 | 多语言翻译 |
|
||
| gitfei1231/webman-api-sign | ^0.0.21 | API 签名验证 |
|
||
| facebook/graph-sdk | ^5.1 | Facebook 集成 |
|
||
| endroid/qr-code | ^4.6 | 二维码生成 |
|
||
| robmorgan/phinx | ^0.14.0 | 数据库迁移 |
|
||
| yzh52521/webman-lock | ^1.0 | 分布式锁 |
|
||
|
||
### 7.2 队列消费者
|
||
|
||
| 消费者 | 队列名 | 功能 |
|
||
|--------|--------|------|
|
||
| SendBroadcasts | broadcast_tasks | 广播消息发送 |
|
||
| CancelRecharge | - | 取消充值处理 |
|
||
|
||
### 7.3 多语言支持
|
||
|
||
- 简体中文 (zh_CN)
|
||
- 英语 (en)
|
||
- 马来语 (Ma_my)
|
||
- 柬埔寨语 (cam_dia)
|
||
|
||
### 7.4 存储
|
||
|
||
| 组件 | 配置 |
|
||
|------|------|
|
||
| MySQL | 默认数据库，utf8mb4 编码 |
|
||
| Redis | 127.0.0.1:6379，DB 1 |
|
||
| Redis Queue | 8 个消费进程，最大重试 5 次 |
|
||
|
||
---
|
||
|
||
## 八、异常处理
|
||
|
||
| 异常类 | 说明 |
|
||
|--------|------|
|
||
| ApiHandler | API 统一异常处理 |
|
||
| GameException | 游戏相关异常 |
|
||
| PlayerCheckException | 玩家校验异常 |
|
||
| PromoterCheckException | 推广员校验异常 |
|
||
|
||
---
|
||
|
||
## 九、支付服务
|
||
|
||
| 服务类 | 说明 |
|
||
|--------|------|
|
||
| SklPayServices | SKL 支付服务（充值/提现）|
|
||
| OnePayServices | OnePay 支付服务 |
|
||
| SePayServices | SePay 支付服务 |
|
||
| DrawService | 抽奖服务 |
|
||
|
||
---
|
||
|
||
## 十、部署与运行
|
||
|
||
```bash
|
||
# Linux 启动
|
||
php start.php start
|
||
|
||
# Linux 守护进程
|
||
php start.php start -d
|
||
|
||
# Windows 启动
|
||
php windows.php
|
||
|
||
# 停止
|
||
php start.php stop
|
||
|
||
# 重启
|
||
php start.php restart
|
||
```
|
||
|
||
默认监听地址：`http://0.0.0.0:8786`
|