kknongchang_2506/ThirdParty/Urs

URS 第三方包

概述

URS（User Referral System）用户推广系统第三方包，用于对接URS生态系统的API接口。

重要更新：本包已重构为遵循"一个Request类只完成一种请求"的原则，每个API操作都有对应的专用Request类。

目录结构

Urs/
├── readme.md                           # 本说明文件
├── UrsServiceProvider.php              # 服务提供者
├── Request/                            # 请求类目录
│   ├── UrsGetUserInfoRequest.php       # 获取用户信息请求类
│   ├── UrsGetUserTeamRequest.php       # 获取用户团队关系请求类
│   └── UrsGetUserLevelCountRequest.php # 获取用户下级统计请求类
├── Services/                           # 服务类目录
│   └── UrsService.php                  # URS统一服务类
├── Webhook/                            # Webhook处理器目录
│   ├── UrsRegisterWebhook.php          # 注册通知处理器
│   ├── UrsDepositWebhook.php           # 充值通知处理器
│   ├── UrsWithdrawWebhook.php          # 提取通知处理器
│   └── UrsCheckWebhook.php             # 检查通知处理器
├── Util/                               # 工具类目录
│   └── CryptoService.php               # 加密服务类
└── Docs/                               # 文档目录
    ├── Api.md                          # API文档
    ├── URS对接建议.md                   # 对接建议
    ├── urs对接.md                      # 对接说明
    └── urs对接ThirdParty文档.md         # ThirdParty对接文档

Request类设计原则

重构前的问题

• 原有的UrsRequest类使用switch语句处理多种操作
• 违反了单一职责原则，一个类承担了多种不同的请求处理
• 代码耦合度高，难以维护和扩展

重构后的优势

• 单一职责：每个Request类只处理一种特定的请求
• 易于维护：修改某个功能不会影响其他功能
• 易于扩展：新增功能只需创建新的Request类
• 代码清晰：每个类的职责明确，代码更易理解

重要说明

本包包含URS实际提供的业务接口对应的Request类。

API接口说明

1. 用户登录

• 类名：UrsLoginRequest
• 功能：使用手机号和密码进行登录认证
• 参数：mobile（手机号码）、password（登录密码）
• 返回：用户ID和用户密钥

2. 获取用户信息

• 类名：UrsGetUserInfoRequest
• 功能：根据用户密钥获取用户ID
• 参数：userKey（用户密钥）
• 返回：用户ID信息

2. 获取用户团队关系

• 类名：UrsGetUserTeamRequest
• 功能：获取用户的3级上级关系链
• 参数：userId（用户ID）
• 返回：各级上级用户ID

3. 获取用户下级统计

• 类名：UrsGetUserLevelCountRequest
• 功能：获取用户下级人数统计
• 参数：userId（用户ID）、level（1或3）
• 返回：下级人数统计

使用方法

方式一：直接使用Request类

use ThirdParty\Urs\Request\UrsGetUserInfoRequest;

$request = new UrsGetUserInfoRequest();
$result = $request->request(['userKey' => 'user_key_here']);

方式二：使用统一服务类（推荐）

use ThirdParty\Urs\Services\UrsService;

// 用户登录
$loginResult = UrsService::login('18600648353', 'a123123');

// 获取用户信息
$userInfo = UrsService::getUserInfo('user_key_here');

// 获取用户团队关系
$userTeam = UrsService::getUserTeam(12345);

// 获取用户下级统计
$levelCount = UrsService::getUserLevelCount(12345, 1);

Webhook处理机制

支持的Webhook类型

1. 注册通知：传入uid和三级上级，返回处理成功
2. 充值通知：用户ID、USDT数量、交易ID，按1:300比例充值钻石
3. 提取通知：用户ID、USDT数量、交易ID，按1:300比例提取钻石
4. 余额检查：用户ID、USDT数量，返回是否允许及相关费用信息

Webhook路由

• 注册通知：POST /thirdParty/webhook/urs/register
• 充值通知：POST /thirdParty/webhook/urs/deposit
• 提取通知：POST /thirdParty/webhook/urs/withdraw
• 余额检查：POST /thirdParty/webhook/urs/check

核心流程

1. URS应用访问：URS应用访问农场客户端，携带ukey
2. 用户信息获取：农场使用ukey到URS获取用户的urs.user_id
3. 用户关联创建：为URS用户创建农场用户，建立关联（创建urs_user表）
4. 推广关系同步：农场获取URS的推广关系，同步到UrsPromotion模块
5. 资金操作：根据webhook进行钻石的充值和提取

资金系统设计

设计资金系统操作，需要创建专属充值资金操作用户ID，充值的资金如钻石从这个专属用户账户转移到用户账户；提取钻石专属操作用户ID，提取钻石从用户账户转移到这个专属用户账户

配置要求

在thirdparty_services表中注册URS服务配置：

{
    "api_url": "https://urs.example.com",
    "app_key": "your_app_key_here",
    "ecology_id": 1,
    "app_id": "your_app_id",
    "app_secret": "your_app_secret"
}

urs 服务

Api通讯 Key ： Hy0LmLKJSbDQY2oaaZOZKR1XKpFHSY8Y ecology_id 生态ID： 1 用户Key （测试用，实际通过客户端传递） ukey ： $2y$10$i.h97m13olfIaU.ZTYiyeeXFl8xqn48w2bFiAhcoQsJdU6K3w.Lgu

对接建议