# 祈盟SDK（new_sdk）项目功能梳理文档

## 一、项目概述

**项目名称**：祈盟SDK（Qimeng SDK）  
**内部代号**：new_sdk  
**项目类型**：多租户游戏SDK聚合平台  
**技术栈**：ThinkPHP 5.0 + PHP 7.0-7.2 + MySQL + Redis + Kafka

### 核心定位
为游戏发行商和渠道合作伙伴提供一站式接入与运营能力，实现：
- 多渠道游戏发行（一次接入对接 45+ 渠道）
- 多支付方式集成（聚合 10+ 支付渠道）
- 跨游戏、跨渠道的用户统一管理
- 数据统计、分析与风控
- CPS 公会渠道分层管理

---

## 二、核心业务模块（12大功能模块）

### 1. 用户体系
- 用户注册/登录（手机号、邮箱、第三方登录）
- 用户信息管理与中心
- 身份验证与实名认证
- 密码找回与重置
- 短信验证码服务
- 防沉迷系统对接

### 2. 游戏管理
- 游戏信息配置与维护
- 游戏版本管理与更新检测
- 游戏支付类型配置
- 游戏公告与通知管理
- 游戏礼包发放

### 3. 支付处理
- 支付统一下单接口
- 多支付渠道集成：
  - 支付宝（H5/小程序/扫码）
  - 微信支付（H5/扫码）
  - 易宝支付
  - 联动优势
  - 趣智连
  - 喜钛游
  - 全民付
- 支付异步回调处理（队列机制）
- 支付记录查询
- iOS内购对接

### 4. 渠道管理
- 45+ 游戏渠道SDK对接
- 渠道登录验证
- 渠道支付回调处理
- 渠道参数配置
- 渠道包管理与分发

### 5. 数据统计
- 用户数据分析
- 订单数据统计
- 支付数据报表
- 渠道效果分析
- 数据导出功能（Go服务实现）

### 6. 内容管理
- 公告管理
- 轮播图管理
- 隐私政策页面
- 静态资源管理（阿里云OSS/华为云OBS）

### 7. 客服系统
- 用户反馈处理
- 工单管理
- 在线客服对接

### 8. 风控系统
- 异常订单检测
- 充值异常告警（钉钉机器人）
- 风险规则配置
- 黑名单管理

### 9. CPS公会系统
- 公会账号管理
- 推广链接生成
- 分包功能
- 流水数据查询
- 佣金结算

### 10. 运营工具
- 权限管理系统
- 操作日志记录
- 系统配置管理
- 邮件发送服务

### 11. 自动打包
- 渠道包自动生成（Python服务）
- 分包任务管理
- 打包状态监控

### 12. MLBB游戏专项
- MLBB专属登录接口
- MLBB支付处理
- MLBB回调通知

---

## 三、系统架构分层

### 1. 用户接入层
- 游戏App客户端
- Web端应用
- 渠道SDK接入
- 公会系统接入

### 2. API网关层
- **V1版本接口**：基础功能接口
- **V2版本接口**：增强版接口
- **MLBB接口**：游戏专用接口
- **Complex接口**：渠道联运对接接口

### 3. 业务逻辑层
- **admin模块**：总控管理后台（100+控制器）
- **api模块**：对外API服务
- **cps模块**：公会系统
- **common模块**：公共模型/工厂/服务
- **crontab模块**：定时任务（14+个）

### 4. 数据存储层
- MySQL数据库
- Redis缓存
- 消息队列（Kafka/ThinkPHP queue）

### 5. 外部服务层
- 阿里云OSS/华为云OBS（对象存储）
- 阿里云短信服务
- 钉钉告警机器人
- 第三方API（176Park、MLBB、抖音广告追踪）

---

## 四、API接口功能清单

### 用户相关接口
| 接口 | 功能说明 |
|------|----------|
| Login | 用户登录 |
| Register | 用户注册 |
| PasswordFind | 密码找回 |
| SendSms | 短信验证码发送 |
| Checkemail | 邮箱验证 |
| Email | 邮件服务 |
| UserCenter | 用户中心信息 |
| UserCenterAuth | 用户中心认证 |
| Identity | 身份验证 |
| IsIdentity | 身份验证状态查询 |
| IsHwu | 实名认证查询 |
| HwuXiaofei | 实名消费记录 |

### 支付相关接口
| 接口 | 功能说明 |
|------|----------|
| Pay | 支付统一下单 |
| PayCoin | 金币支付 |
| IosPay | iOS内购支付 |
| PayNotify | 支付异步回调 |
| PayNotifyCoin | 金币支付回调 |
| PayRecord | 支付记录查询 |
| PayReturn | 支付返回处理 |
| GamePayType | 游戏支付类型查询 |

### 游戏相关接口
| 接口 | 功能说明 |
|------|----------|
| Index | 首页数据 |
| CheckUpdate | 版本更新检测 |
| GameNotify | 游戏通知 |
| Gift | 礼包发放 |
| Coin | 金币相关 |
| CoinInstruction | 金币说明 |
| MemberCoin | 会员金币 |

### 渠道相关接口
| 接口 | 功能说明 |
|------|----------|
| ComplexLogin | 渠道登录 |
| ComplexPay | 渠道支付 |
| ComplexPayNotify | 渠道支付回调 |
| QuickCallback | 快速回调 |
| SpecialParam | 特殊参数处理 |

### 系统相关接口
| 接口 | 功能说明 |
|------|----------|
| Startup | 系统启动 |
| Helper | 辅助工具 |
| Demo | 演示接口 |
| Test | 测试接口 |
| TestRedis | Redis测试 |
| KafkaTest | Kafka测试 |
| Mobile | 移动端相关 |

---

## 五、定时任务清单

系统包含14+个定时任务，主要包括：
- 订单状态同步
- 支付回调重试
- 数据统计汇总
- 日志清理
- 缓存更新
- 风控规则执行

---

## 六、对外域名生态

### 生产环境
| 用途 | 域名 |
|------|------|
| 后台管理 | sdkadmin.7dgames.cn / sdkadmin.qmgames.cn |
| 支付回调+API | sdkapi.7dgames.cn / sdkapi.qmgames.cn |
| 渠道SDK对接 | sdkjhgame.7dgames.cn / sdkjhgame.qmgames.cn |
| 公会后台 | sdkcps.7dgames.cn / sdkcps.qmgames.cn |
| 公会API | sdkcpsapi.7dgames.cn / sdkcpsapi.qmgames.cn |
| 官网 | sdkwww.7dgames.cn / sdkwww.qmgames.cn |
| 渠道包下载 | sdkdownapp.7dgames.cn / sdkdownapp.qmgames.cn |
| 导出下载 | sdkdownreport.7dgames.cn / sdkdownreport.qmgames.cn |
| 图片静态资源 | sdkstatic.7dgames.cn / sdkstatic.qmgames.cn |

### 测试环境
在生产域名前加 `dev` 前缀（如 devsdkapi.qmgames.cn）

---

## 七、关联项目仓库

| 仓库名称 | 功能职责 |
|----------|----------|
| new_sdk（本仓库） | 后台 + API + CPS_API |
| new_sdk_cps-admin | CPS公会后台（前端分离） |
| new_sdk_cps-py | CPS打包服务（Python） |
| new_sdk_ws | 相关通知服务（WebSocket） |
| new_sdk_go | Excel导出 & 发放游戏礼包（Go） |

---

## 八、部署与运维

### 环境要求
- 服务器：2核4G
- 打包服务器：2核8G
- 数据库：2核8G
- Redis：2核4G
- 带宽：5M
- 开发栈：PHP + MySQL + Redis + WS + Go + Python

### 容器化部署
```bash
docker-compose up -d --build
```

### 队列服务
```bash
# 生产环境（守护进程）
php think queue:work --queue asyncCallback --daemon

# 调试环境（热更新）
php think queue:listen --queue asyncCallback
```

---

## 九、API响应码约定

| 响应码 | 含义 |
|--------|------|
| 100 | 登录失效 |
| 110 | 请求参数有误 |
| 120 | 请求处理过程提示 |
| 130 | 执行异常 |
| 200 | 正常 |

---

## 十、第三方服务集成

### 支付渠道
- 支付宝（H5/小程序/扫码）
- 微信支付（H5/扫码）
- 易宝支付
- 联动优势
- 趣智连
- 喜钛游
- 全民付

### 云服务
- 阿里云OSS（对象存储）
- 华为云OBS（对象存储）
- 阿里云短信服务
- 钉钉告警机器人

### 第三方API
- 176Park游戏平台
- MLBB游戏服务
- 抖音广告追踪

---

## 十一、项目现状与重构方向

### 现状特征
- ✅ 功能完整，覆盖游戏SDK全链路
- ✅ 业务复杂，多租户、多渠道、多支付
- ⚠️ 技术债务：ThinkPHP 5.0.7已过时，PHP 7.0-7.2官方停止维护
- ⚠️ 代码质量：缺乏统一规范、无测试覆盖、耦合度高

### 主要痛点
1. PaymentController约2000行，逻辑混乱
2. 45+个Channel SDK存在大量重复代码
3. 80+个数据模型缺乏统一规范
4. 无测试覆盖，改一处可能影响多处
5. 大量同步阻塞调用影响性能

### 重构文档索引
详见 `www/new_sdk/docs_12/` 目录下的系列文档

---

## 十二、快速上手指南

### 推荐阅读顺序
1. `www/new_sdk/docs_12/01_项目概览.md` + `02_痛点清单.md` - 建立全局认知
2. `09_全部文档总结.md` - 把握重构总体思路
3. 支付模块重点：`application/common/factory/Pay.php` 与 `application/api/controller/v1/PayNotify.php`
4. 渠道SDK：`06_SDK渠道架构优化方案.md` + `extend/` 目录
5. 风控系统：根目录 `risk_control_tables.sql` 与 `application/admin/controller/` 下风控相关控制器

---

**文档生成时间**：2026年5月27日  
**文档版本**：v1.0