# 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`