# URS Request机制重构说明

## 重构概述

本次重构将URS包的Request机制从"一个类处理多种请求"改为"一个Request类只完成一种请求"的设计原则，提高了代码的可维护性和扩展性。

## 重构前的问题

### 1. 违反单一职责原则
原有的`UrsRequest`类使用switch语句处理多种操作：
```php
protected function handler(array $params): array
{
    $action = $params['action'] ?? '';

    switch ($action) {
        case 'register':
            return $this->handleRegister($params);
        case 'deposit':
            return $this->handleDeposit($params);
        case 'withdraw':
            return $this->handleWithdraw($params);
        case 'check':
            return $this->handleCheck($params);
        default:
            throw new \Exception("不支持的操作类型: {$action}");
    }
}
```

### 2. 代码耦合度高
- 所有操作的逻辑都在同一个类中
- 修改某个功能可能影响其他功能
- 代码复杂度随着功能增加而快速增长

### 3. 难以维护和扩展
- 新增功能需要修改现有类
- 测试困难，需要测试所有功能
- 代码职责不清晰

## 重构后的设计

### 1. 专用Request类
每个API操作都有对应的专用Request类：

#### 获取用户信息
```php
class UrsGetUserInfoRequest extends BaseRequest
{
    protected function handler(array $params): array
    {
        // 只处理获取用户信息的逻辑
        // 验证userKey参数
        // 调用URS API
        // 返回用户信息
    }
}
```

#### 获取用户团队关系
```php
class UrsGetUserTeamRequest extends BaseRequest
{
    protected function handler(array $params): array
    {
        // 只处理获取用户团队关系的逻辑
        // 验证userId参数
        // 调用URS API
        // 返回团队关系数据
    }
}
```

#### 获取用户下级统计
```php
class UrsGetUserLevelCountRequest extends BaseRequest
{
    protected function handler(array $params): array
    {
        // 只处理获取用户下级统计的逻辑
        // 验证userId和level参数
        // 调用URS API
        // 返回统计数据
    }
}
```

#### 用户注册
```php
class UrsRegisterRequest extends BaseRequest
{
    protected function handler(array $params): array
    {
        // 只处理用户注册的逻辑
        // 验证user_id和username参数
        // 调用URS API
        // 返回注册结果
    }
}
```

#### 充值操作
```php
class UrsDepositRequest extends BaseRequest
{
    protected function handler(array $params): array
    {
        // 只处理充值操作的逻辑
        // 验证user_id、amount、order_id参数
        // 调用URS API
        // 返回充值结果
    }
}
```

#### 提取操作
```php
class UrsWithdrawRequest extends BaseRequest
{
    protected function handler(array $params): array
    {
        // 只处理提取操作的逻辑
        // 验证user_id、amount、order_id参数
        // 调用URS API
        // 返回提取结果
    }
}
```

#### 余额检查
```php
class UrsCheckBalanceRequest extends BaseRequest
{
    protected function handler(array $params): array
    {
        // 只处理余额检查的逻辑
        // 验证user_id参数
        // 调用URS API
        // 返回余额信息
    }
}
```

### 2. 统一服务类
创建`UrsService`类来统一管理所有Request类的调用：

```php
class UrsService
{
    public static function getUserInfo(string $userKey): array
    {
        $request = new UrsGetUserInfoRequest();
        return $request->request(['userKey' => $userKey]);
    }

    public static function getUserTeam(int $userId): array
    {
        $request = new UrsGetUserTeamRequest();
        return $request->request(['userId' => $userId]);
    }

    public static function getUserLevelCount(int $userId, int $level): array
    {
        $request = new UrsGetUserLevelCountRequest();
        return $request->request(['userId' => $userId, 'level' => $level]);
    }

    // ... 其他方法
}
```

## 重构后的优势

### 1. 单一职责原则
- 每个Request类只负责一种特定的请求处理
- 代码职责清晰，易于理解

### 2. 易于维护
- 修改某个功能不会影响其他功能
- 代码隔离性好，降低了维护风险

### 3. 易于扩展
- 新增功能只需创建新的Request类
- 不需要修改现有代码

### 4. 易于测试
- 每个Request类可以独立测试
- 测试覆盖率更高，测试更精确

### 5. 代码复用
- 通用逻辑可以在基类中实现
- 特定逻辑在各自的类中实现

## 文件结构对比

### 重构前
```
Request/
└── UrsRequest.php          # 处理所有操作的单一类
```

### 重构后
```
Request/
├── UrsGetUserInfoRequest.php       # 获取用户信息
├── UrsGetUserTeamRequest.php       # 获取用户团队关系
├── UrsGetUserLevelCountRequest.php # 获取用户下级统计
├── UrsRegisterRequest.php          # 用户注册
├── UrsDepositRequest.php           # 充值操作
├── UrsWithdrawRequest.php          # 提取操作
└── UrsCheckBalanceRequest.php      # 余额检查

Services/
└── UrsService.php                  # 统一服务类
```

## 使用方式对比

### 重构前
```php
$request = new UrsRequest();
$result = $request->request([
    'action' => 'userInfo',
    'userKey' => 'user_key_here'
]);
```

### 重构后
```php
// 方式一：直接使用Request类
$request = new UrsGetUserInfoRequest();
$result = $request->request(['userKey' => 'user_key_here']);

// 方式二：使用统一服务类（推荐）
$result = UrsService::getUserInfo('user_key_here');
```

## 兼容性说明

本次重构是破坏性更新，不兼容旧的调用方式。如果有现有代码使用了旧的`UrsRequest`类，需要按照新的方式进行调整。

## 测试验证

已创建`TestUrsRequestCommand`命令来验证重构后的功能：

```bash
# 测试所有Request类
php artisan thirdparty:test-urs-request

# 测试特定类型
php artisan thirdparty:test-urs-request --type=userinfo
php artisan thirdparty:test-urs-request --type=team
php artisan thirdparty:test-urs-request --type=count
php artisan thirdparty:test-urs-request --type=register
```

## 总结

本次重构显著提高了URS包的代码质量和可维护性，为后续的功能扩展奠定了良好的基础。建议其他第三方包也采用类似的设计原则进行开发。