新增URS注册农场用户WebHook

任务时间: 2025年07月02日 20:00-20:30
任务类型: 功能开发
模块: ThirdParty/Urs

任务描述

按照现有WebHook模式，新增一个URS注册农场用户的WebHook处理器，用于处理URS用户注册农场用户的请求。

需求分析

传入参数：user_id (URS的用户ID), user_key (URS的用户密钥)
处理逻辑：使用 UrsUserMappingService::getFarmUserIdByUserKeyWithAutoCreate($userKey, $ursUserId) 的公共逻辑
返回结果：farm_user_id (农场的用户ID)

实现方案

1. 创建WebHook处理器

文件: ThirdParty/Urs/Webhook/UrsRegisterFarmUserWebhook.php

主要功能：

继承自 WebhookReceiver 基类
验证操作类型为 register_farm_user
验证必需参数：user_id 和 user_key
参数格式验证：用户ID必须为正整数，用户密钥不能为空
调用 UrsUserMappingService::getFarmUserIdByUserKeyWithAutoCreate() 处理用户注册
返回农场用户ID和状态信息
完整的错误处理和日志记录

2. 注册WebHook处理器

文件: ThirdParty/Urs/UrsServiceProvider.php

修改内容：

添加 UrsRegisterFarmUserWebhook 类的导入
在 registerWebhookHandlers() 方法中注册新的处理器
路由映射：'register_farm_user' => UrsRegisterFarmUserWebhook::class

技术实现要点

1. 参数验证

protected function validateRegisterRequest(Request $request): void
{
    $requiredFields = ['user_id', 'user_key'];

    foreach ($requiredFields as $field) {
        if (!$request->has($field)) {
            throw new \Exception("缺少必需字段: {$field}");
        }
    }

    // 验证用户ID格式
    $userId = $request->input('user_id');
    if (!is_numeric($userId) || $userId <= 0) {
        throw new \Exception('用户ID格式无效');
    }

    // 验证用户密钥
    $userKey = $request->input('user_key');
    if (empty($userKey)) {
        throw new \Exception('用户密钥不能为空');
    }
}

2. 业务逻辑处理

protected function processRegisterFarmUser($ursUserId, $userKey): array
{
    // 使用UrsUserMappingService的公共逻辑获取或创建农场用户ID
    $farmUserId = UrsUserMappingService::getFarmUserIdByUserKeyWithAutoCreate($userKey, $ursUserId);

    if (!$farmUserId) {
        throw new \Exception("无法获取或创建农场用户ID");
    }

    // 返回成功响应
    return [
        'farm_user_id' => $farmUserId,
        'status' => 'success'
    ];
}

3. 日志记录

处理开始时记录请求信息
成功时记录农场用户ID
异常时记录详细错误信息和堆栈跟踪

测试验证

1. WebHook路由

URL: http://kku_laravel.local.gd/thirdParty/webhook/urs/register_farm_user
方法: POST
Content-Type: application/json

2. 请求参数

{
  "user_id": 12345,
  "user_key": "test_user_key_12345"
}

3. 签名验证

Header: X-Signature
算法: HMAC-SHA256
密钥: Hy0LmLKJSbDQY2oaaZOZKR1XKpFHSY8Y
签名字符串: user_id=12345&user_key=test_user_key_12345

4. 测试结果

{
  "success": true,
  "data": {
    "farm_user_id": 39147,
    "status": "success"
  },
  "request_id": "webhook_dispatch_686524a32e66b8.94052417"
}

测试成功：WebHook正常工作，成功创建了农场用户ID为39147的用户。

文件变更

新增文件

ThirdParty/Urs/Webhook/UrsRegisterFarmUserWebhook.php - WebHook处理器
ThirdParty/Urs/Webhook/webhook.md - 需求文档

修改文件

ThirdParty/Urs/UrsServiceProvider.php - 注册新的WebHook处理器

提交信息

新增URS注册农场用户WebHook处理器

- 创建UrsRegisterFarmUserWebhook类，处理URS用户注册农场用户请求
- 实现参数验证：验证user_id和user_key参数格式
- 集成UrsUserMappingService::getFarmUserIdByUserKeyWithAutoCreate逻辑
- 返回farm_user_id给调用方，包含完整的错误处理和日志记录
- 在UrsServiceProvider中注册新的WebHook处理器
- 测试验证功能正常，成功创建农场用户并返回正确响应

总结

成功实现了URS注册农场用户的WebHook处理器，完全按照现有WebHook模式开发：

架构一致性：继承自WebhookReceiver基类，遵循现有的WebHook架构
参数验证：完整的参数验证机制，确保数据安全性
业务逻辑：复用现有的UrsUserMappingService逻辑，避免重复开发
错误处理：完善的异常处理和日志记录机制
测试验证：通过实际测试验证功能正确性

该WebHook处理器已成功集成到系统中，可以正常处理URS用户注册农场用户的请求。

022000-新增URS注册农场用户WebHook.md 4.7 KB Permalink History Raw