# 新增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. 参数验证
```php
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. 业务逻辑处理
```php
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. 请求参数
```json
{
  "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. 测试结果
```json
{
  "success": true,
  "data": {
    "farm_user_id": 39147,
    "status": "success"
  },
  "request_id": "webhook_dispatch_686524a32e66b8.94052417"
}
```

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

## 文件变更

### 新增文件
1. `ThirdParty/Urs/Webhook/UrsRegisterFarmUserWebhook.php` - WebHook处理器
2. `ThirdParty/Urs/Webhook/webhook.md` - 需求文档

### 修改文件
1. `ThirdParty/Urs/UrsServiceProvider.php` - 注册新的WebHook处理器

## 提交信息

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

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

## 总结

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

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

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