AI Assistant eaefaee2a1 实现URS注册用户设置昵称和头像功能		6 months ago
..
Urs	eaefaee2a1 实现URS注册用户设置昵称和头像功能	6 months ago
README.md	4babfca9b0 重构ThirdParty模块URS Request机制	6 months ago

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
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
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 表中，可以通过后台管理界面查看：

请求参数和响应数据
执行时间和状态
错误信息和堆栈跟踪
调用统计和性能分析

注意事项

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

技术支持

如有问题，请参考：

app/Module/ThirdParty/Docs/基础架构使用示例.md - 详细使用示例
app/Module/ThirdParty/Docs/第三方包.md - 规范说明
app/Module/ThirdParty/README.md - 模块文档

README.md