# 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类
```php
use ThirdParty\Urs\Request\UrsGetUserInfoRequest;

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

### 方式二：使用统一服务类（推荐）
```php
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服务配置：
```json
{
    "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

## 对接建议