# ThirdParty 第三方包目录

## 目录说明

此目录用于存放第三方服务对接包，每个包都遵循ThirdParty模块的标准化规范。

## 目录结构

```
ThirdParty/
├── README.md                   # 本说明文件
├── Urs/                       # URS包示例（已重构）
│   ├── Request/               # 请求类目录
│   │   ├── UrsGetUserInfoRequest.php       # 获取用户信息请求类
│   │   ├── UrsGetUserTeamRequest.php       # 获取用户团队关系请求类
│   │   ├── UrsGetUserLevelCountRequest.php # 获取用户下级统计请求类
│   │   ├── UrsRegisterRequest.php          # 用户注册请求类
│   │   ├── UrsDepositRequest.php           # 充值请求类
│   │   ├── UrsWithdrawRequest.php          # 提取请求类
│   │   └── UrsCheckBalanceRequest.php      # 余额检查请求类
│   ├── Services/              # 服务类目录
│   │   └── UrsService.php     # URS统一服务类
│   ├── Webhook/               # Webhook处理器目录
│   │   ├── UrsRegisterWebhook.php  # 注册通知处理器
│   │   ├── UrsDepositWebhook.php   # 充值通知处理器
│   │   ├── UrsWithdrawWebhook.php  # 提取通知处理器
│   │   └── UrsCheckWebhook.php     # 余额检查处理器
│   ├── Util/                  # 工具类目录
│   │   └── CryptoService.php  # 加密服务类
│   ├── Docs/                  # 文档目录
│   └── UrsServiceProvider.php # URS服务提供者
└── [其他包]/                   # 其他第三方服务包
```

## Request机制重构说明

**重要更新**：ThirdParty模块的Request机制已重构，遵循"一个Request类只完成一种请求"的设计原则。

### 重构前的问题
- 单个Request类使用switch语句处理多种操作
- 违反单一职责原则，代码耦合度高
- 难以维护和扩展

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

## 包开发规范

### 1. 命名空间
- 所有包使用 `ThirdParty\{包名}` 命名空间
- 包名使用大驼峰命名法，如：`Urs`、`Alipay`、`Wechat`

### 2. 必需文件
每个包至少包含以下文件：

#### 请求类目录 (`Request/`)
- 每个API操作创建独立的Request类
- 继承 `App\Module\ThirdParty\Services\BaseRequest`
- 实现 `handler(array $params): array` 方法
- 类名格式：`{包名}{操作名}Request.php`
- 处理对第三方服务的主动调用

#### 服务类 (`Services/{包名}Service.php`)
- 统一管理所有Request类的调用
- 提供简洁的静态方法接口
- 封装复杂的参数验证逻辑

#### Webhook处理器 (`{包名}Webhook.php`)
- 继承 `App\Module\ThirdParty\Services\BaseWebhook`
- 实现 `handler(string $action, Request $request): array` 方法
- 处理来自第三方服务的回调

#### 服务提供者 (`{包名}ServiceProvider.php`)
- 继承 `Illuminate\Support\ServiceProvider`
- 在 `boot()` 方法中注册Webhook处理器
- 可选：注册其他服务到容器

### 3. 配置要求
- 在 `thirdparty_services` 表中注册服务配置
- 服务代码（code字段）与包名保持一致（小写）
- 配置信息存储在 `config` 字段中（JSON格式）

### 4. 使用示例

#### 创建专用请求类（推荐方式）
```php
<?php
namespace ThirdParty\YourPackage\Request;
use App\Module\ThirdParty\Services\BaseRequest;

// 专门处理用户信息获取的请求类
class YourPackageGetUserRequest extends BaseRequest
{
    public function __construct()
    {
        parent::__construct('your_package'); // 服务代码
    }

    protected function handler(array $params): array
    {
        // 验证必需参数
        if (empty($params['user_id'])) {
            throw new \Exception('user_id参数是必填的');
        }

        // 获取配置
        $config = $this->getConfig();

        // 实现具体的用户信息获取逻辑
        // ... 业务逻辑
        return $result;
    }
}

// 专门处理用户注册的请求类
class YourPackageRegisterRequest extends BaseRequest
{
    public function __construct()
    {
        parent::__construct('your_package');
    }

    protected function handler(array $params): array
    {
        // 验证必需参数
        if (empty($params['username'])) {
            throw new \Exception('username参数是必填的');
        }

        // 实现具体的用户注册逻辑
        // ... 业务逻辑
        return $result;
    }
}
```

#### 创建统一服务类
```php
<?php
namespace ThirdParty\YourPackage\Services;

use ThirdParty\YourPackage\Request\YourPackageGetUserRequest;
use ThirdParty\YourPackage\Request\YourPackageRegisterRequest;

class YourPackageService
{
    /**
     * 获取用户信息
     */
    public static function getUser(int $userId): array
    {
        $request = new YourPackageGetUserRequest();
        return $request->request(['user_id' => $userId]);
    }

    /**
     * 注册用户
     */
    public static function registerUser(string $username): array
    {
        $request = new YourPackageRegisterRequest();
        return $request->request(['username' => $username]);
    }
}
```
```

#### 创建Webhook处理器
```php
<?php
namespace ThirdParty\YourPackage;
use App\Module\ThirdParty\Services\BaseWebhook;
use Illuminate\Http\Request;

class YourPackageWebhook extends BaseWebhook
{
    public function __construct(Request $request)
    {
        parent::__construct('your_package', $request);
    }
    
    protected function handler(string $action, Request $request): array
    {
        // 实现具体的Webhook处理逻辑
        switch ($action) {
            case 'notify':
                return $this->handleNotify($request);
            // ... 其他操作
        }
    }
}
```

#### 注册服务提供者
```php
<?php
namespace ThirdParty\YourPackage;
use Illuminate\Support\ServiceProvider;
use App\Module\ThirdParty\Services\WebhookDispatchService;

class YourPackageServiceProvider extends ServiceProvider
{
    public function boot()
    {
        WebhookDispatchService::registerPackageHandlers('your_package', [
            'notify' => YourPackageWebhook::class,
            // ... 其他处理器
        ]);
    }
}
```

## 注册步骤

### 1. 在composer.json中注册命名空间
```json
{
    "autoload": {
        "psr-4": {
            "ThirdParty\\YourPackage\\": "ThirdParty/YourPackage/"
        }
    }
}
```

### 2. 在config/app.php中注册服务提供者
```php
'providers' => [
    // ...
    ThirdParty\YourPackage\YourPackageServiceProvider::class,
],
```

### 3. 在数据库中注册服务配置
```sql
INSERT INTO `kku_thirdparty_services` (
    `name`, `code`, `type`, `provider`, `description`, 
    `base_url`, `auth_type`, `status`, `config`
) VALUES (
    '您的服务名称', 'your_package', 'CUSTOM', 'YOUR_PROVIDER', '服务描述',
    'https://api.yourservice.com', 'API_KEY', 'ACTIVE',
    JSON_OBJECT(
        'api_url', 'https://api.yourservice.com',
        'app_id', 'your_app_id',
        'app_secret', 'your_app_secret'
    )
);
```

## 基类功能

### BaseRequest 提供的功能
- ✅ 自动配置读取
- ✅ 配额检查和更新
- ✅ 请求日志记录
- ✅ 错误处理
- ✅ 凭证管理

### BaseWebhook 提供的功能
- ✅ 签名验证
- ✅ 请求格式验证
- ✅ Webhook日志记录
- ✅ 错误处理和响应
- ✅ 配置访问

## Webhook路由

所有Webhook请求都通过以下路由格式访问：
```
POST /thirdParty/webhook/{包名}/{处理器路由}
```

例如：
- `/thirdParty/webhook/urs/register` - URS注册通知
- `/thirdParty/webhook/alipay/notify` - 支付宝支付通知
- `/thirdParty/webhook/wechat/callback` - 微信回调

## 监控和日志

所有包的请求和Webhook处理都会自动记录到 `thirdparty_logs` 表中，可以通过后台管理界面查看：
- 请求参数和响应数据
- 执行时间和状态
- 错误信息和堆栈跟踪
- 调用统计和性能分析

## 注意事项

1. **包名唯一性** - 确保包名在整个系统中唯一
2. **服务代码一致性** - 包名与数据库中的服务代码保持一致
3. **错误处理** - 继承基类的错误处理机制，不要自行捕获异常
4. **配置安全** - 敏感配置信息会自动加密存储
5. **版本兼容** - 确保包与ThirdParty模块版本兼容

## 技术支持

如有问题，请参考：
- `app/Module/ThirdParty/Docs/基础架构使用示例.md` - 详细使用示例
- `app/Module/ThirdParty/Docs/第三方包.md` - 规范说明
- `app/Module/ThirdParty/README.md` - 模块文档