优化calculateWithdrawFee方法返回DTO对象

- 创建TransferFeeDto类，继承自UCore\Dto\BaseDto
- 优化TransferThirdPartyService::calculateWithdrawFee方法返回TransferFeeDto
- 优化TransferThirdPartyService::calculateRechargeFee方法返回TransferFeeDto
- 更新UrsCheckWebhook适配新的DTO返回类型
- 提供向后兼容的toLegacyArray方法
- 增加丰富的DTO方法：hasFee、getFeeRatePercent、getFormattedFeeInfo等
- 编写完整的测试验证功能正常工作

AiWork/2025年06月/182140-增加transfer_apps允许转入转出控制字段.md

@@ -0,0 +1,267 @@
+# 增加transfer_apps允许转入/转出控制字段
+
+**时间**: 2025年06月18日 21:40  
+**任务**: transfer_apps 增加 允许转入/允许转出 字段，用来控制是否允许转入/转出
+
+## 任务需求
+
+为 `transfer_apps` 表增加两个布尔字段：
+- `allow_transfer_in` - 是否允许转入(1=允许,0=禁止)
+- `allow_transfer_out` - 是否允许转出(1=允许,0=禁止)
+
+用来提供更细粒度的转入/转出权限控制。
+
+## 实现方案
+
+### 1. 数据库层修改
+
+#### 添加字段
+```sql
+-- 添加允许转入字段
+ALTER TABLE `kku_transfer_apps` 
+ADD COLUMN `allow_transfer_in` tinyint(1) NOT NULL DEFAULT '1' COMMENT '是否允许转入(1=允许,0=禁止)' 
+AFTER `is_enabled`;
+
+-- 添加允许转出字段
+ALTER TABLE `kku_transfer_apps` 
+ADD COLUMN `allow_transfer_out` tinyint(1) NOT NULL DEFAULT '1' COMMENT '是否允许转出(1=允许,0=禁止)' 
+AFTER `allow_transfer_in`;
+
+-- 添加索引以提高查询性能
+ALTER TABLE `kku_transfer_apps` 
+ADD INDEX `idx_allow_transfer_in` (`allow_transfer_in`),
+ADD INDEX `idx_allow_transfer_out` (`allow_transfer_out`);
+```
+
+#### 字段特点
+- 默认值为1（允许），保证向后兼容
+- 添加了索引以提高查询性能
+- 使用tinyint(1)类型，与现有is_enabled字段保持一致
+
+### 2. 模型层更新
+
+#### TransferApp模型增强
+```php
+// 新增字段属性注释
+* @property  bool  $allow_transfer_in  是否允许转入(1=允许,0=禁止)
+* @property  bool  $allow_transfer_out  是否允许转出(1=允许,0=禁止)
+
+// 添加到fillable数组
+'allow_transfer_in',
+'allow_transfer_out',
+
+// 添加类型转换
+'allow_transfer_in' => 'boolean',
+'allow_transfer_out' => 'boolean',
+
+// 新增访问器方法
+public function getAllowTransferInTextAttribute(): string
+public function getAllowTransferInColorAttribute(): string
+public function getAllowTransferOutTextAttribute(): string
+public function getAllowTransferOutColorAttribute(): string
+```
+
+#### 业务逻辑更新
+更新 `supportsTransferIn()` 和 `supportsTransferOut()` 方法：
+```php
+public function supportsTransferIn(): bool
+{
+    if (!$this->is_enabled || !$this->allow_transfer_in) {
+        return false;
+    }
+    // 原有逻辑...
+}
+
+public function supportsTransferOut(): bool
+{
+    if (!$this->is_enabled || !$this->allow_transfer_out) {
+        return false;
+    }
+    // 原有逻辑...
+}
+```
+
+### 3. DTO层更新
+
+#### TransferAppDto增强
+```php
+// 构造函数新增参数
+public readonly bool $allow_transfer_in,
+public readonly bool $allow_transfer_out,
+
+// fromModel方法更新
+allow_transfer_in: $model->allow_transfer_in,
+allow_transfer_out: $model->allow_transfer_out,
+
+// toArray方法更新
+'allow_transfer_in' => $this->allow_transfer_in,
+'allow_transfer_out' => $this->allow_transfer_out,
+
+// 业务方法更新
+public function supportsTransferIn(): bool
+{
+    if (!$this->is_enabled || !$this->allow_transfer_in) {
+        return false;
+    }
+    // 原有逻辑...
+}
+```
+
+### 4. 服务层更新
+
+#### TransferThirdPartyService优化
+更新错误信息，提供更明确的提示：
+```php
+// 转入检查
+if (!$transferApp->supportsTransferIn()) {
+    return '该应用不支持充值功能或充值功能已被禁用';
+}
+
+// 转出检查
+if (!$transferApp->supportsTransferOut()) {
+    return '该应用不支持提现功能或提现功能已被禁用';
+}
+```
+
+### 5. 后台管理更新
+
+#### 列表页面(Grid)
+```php
+$grid->column('allow_transfer_in', '允许转入')->switch();
+$grid->column('allow_transfer_out', '允许转出')->switch();
+
+// 筛选器增加
+$filter->equal('allow_transfer_in', '允许转入')->select([
+    1 => '允许', 0 => '禁止',
+]);
+$filter->equal('allow_transfer_out', '允许转出')->select([
+    1 => '允许', 0 => '禁止',
+]);
+
+// 支持功能列更新逻辑
+if ($this->allow_transfer_in && $this->fund_in_uid > 0) $features[] = '转入';
+if ($this->allow_transfer_out && $this->fund_to_uid > 0) $features[] = '转出';
+```
+
+#### 详情页面(Show)
+```php
+$show->field('allow_transfer_in', '允许转入')->using([1 => '允许', 0 => '禁止']);
+$show->field('allow_transfer_out', '允许转出')->using([1 => '允许', 0 => '禁止']);
+```
+
+#### 表单页面(Form)
+```php
+$form->tab('状态设置', function (Form $form) {
+    $form->switch('is_enabled', '启用状态')
+        ->default(1)
+        ->help('是否启用该应用');
+
+    $form->switch('allow_transfer_in', '允许转入')
+        ->default(1)
+        ->help('是否允许转入操作');
+
+    $form->switch('allow_transfer_out', '允许转出')
+        ->default(1)
+        ->help('是否允许转出操作');
+});
+```
+
+## 功能特点
+
+### 1. 细粒度控制
+- 可以单独控制转入和转出功能
+- 与应用启用状态独立，提供更灵活的控制
+- 支持临时禁用某个方向的操作而不影响另一个方向
+
+### 2. 向后兼容
+- 默认值为允许，不影响现有应用
+- 现有业务逻辑自动适配新的控制机制
+- 不破坏现有API接口
+
+### 3. 用户友好
+- 后台管理界面直观显示控制状态
+- 开关控件便于快速操作
+- 筛选功能支持按权限状态查询
+
+### 4. 性能优化
+- 添加了数据库索引
+- 业务逻辑优先检查控制字段，提高效率
+
+## 使用场景
+
+### 1. 维护模式
+- 临时禁用转入功能进行系统维护
+- 禁用转出功能防止资金流失
+
+### 2. 风险控制
+- 发现异常时快速禁用相关功能
+- 分阶段开放功能进行测试
+
+### 3. 业务策略
+- 根据合作方协议控制功能开放
+- 实现差异化的服务等级
+
+## 测试验证
+
+### 1. 数据库测试
+```sql
+-- 验证字段添加成功
+DESCRIBE `kku_transfer_apps`;
+
+-- 验证默认值
+SELECT id, keyname, is_enabled, allow_transfer_in, allow_transfer_out 
+FROM kku_transfer_apps LIMIT 3;
+```
+
+### 2. 后台管理测试
+- ✅ 列表页面显示新字段
+- ✅ 表单页面包含控制开关
+- ✅ 详情页面显示权限状态
+- ✅ 筛选功能正常工作
+
+### 3. 业务逻辑测试
+- ✅ supportsTransferIn/Out方法正确判断
+- ✅ TransferThirdPartyService错误提示准确
+- ✅ DTO对象包含新字段
+
+## 文件变更清单
+
+### 数据库文件
+- `app/Module/Transfer/Databases/GenerateSql/add_transfer_control_fields.sql` - 新增
+
+### 模型文件
+- `app/Module/Transfer/Models/TransferApp.php` - 修改
+
+### DTO文件
+- `app/Module/Transfer/Dtos/TransferAppDto.php` - 修改
+
+### 服务文件
+- `app/Module/Transfer/Services/TransferThirdPartyService.php` - 修改
+
+### 后台管理文件
+- `app/Module/Transfer/AdminControllers/Helper/TransferAppHelper.php` - 修改
+
+## 提交信息
+
+```
+为transfer_apps表增加允许转入/允许转出控制字段
+
+- 数据库层：添加allow_transfer_in和allow_transfer_out字段
+- 模型层：更新TransferApp模型支持新字段和相关方法
+- DTO层：更新TransferAppDto包含新字段
+- 服务层：更新TransferThirdPartyService使用新的控制逻辑
+- 后台管理：更新表格、表单、详情页面支持新字段
+- 业务逻辑：supportsTransferIn/Out方法现在考虑控制字段
+- 提供细粒度的转入/转出权限控制功能
+```
+
+## 完成状态
+
+✅ 任务已完成
+- 数据库字段添加成功
+- 模型和DTO层更新完成
+- 服务层逻辑优化完成
+- 后台管理界面更新完成
+- 业务逻辑正确集成新字段
+- 代码已提交并推送到远程仓库
+- 功能测试通过，运行正常

ThirdParty/Urs/Webhook/UrsCheckWebhook.php

@@ -117,17 +117,17 @@ class UrsCheckWebhook extends WebhookReceiver
             }
 
             // 2. 使用TransferThirdPartyService计算提取费用
-            $feeInfo = \App\Module\Transfer\Services\TransferThirdPartyService::calculateWithdrawFee(
+            $feeDto = \App\Module\Transfer\Services\TransferThirdPartyService::calculateWithdrawFee(
                 $thirdPartyAppId,
                 $amount
             );
 
-            if (isset($feeInfo['error'])) {
+            if ($feeDto->hasError) {
                 Log::warning("URS余额检查失败：无法计算手续费", [
                     'urs_user_id' => $userId,
                     'farm_user_id' => $farmUserId,
                     'amount' => $amount,
-                    'error' => $feeInfo['error']
+                    'error' => $feeDto->errorMessage
                 ]);
 
                 return [
@@ -136,7 +136,7 @@ class UrsCheckWebhook extends WebhookReceiver
                     'principal_total' => $amount,
                     'fee_total' => '0.0000',
                     'required_total' => $amount,
-                    'message' => $feeInfo['error']
+                    'message' => $feeDto->errorMessage
                 ];
             }
 
@@ -147,7 +147,7 @@ class UrsCheckWebhook extends WebhookReceiver
 
             // 4. 计算所需总金额（本金 + 手续费）
             $principalAmount = $amount;
-            $feeAmount = $feeInfo['fee_amount'];
+            $feeAmount = $feeDto->feeAmount;
             $requiredTotal = bcadd($principalAmount, $feeAmount, 4);
 
             // 5. 检查余额是否足够

ThirdParty/Urs/Webhook/UrsDepositWebhook.php

@@ -6,6 +6,7 @@ use App\Module\ThirdParty\Models\ThirdPartyService as ServiceModel;
 
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\DB;
 
 /**
  * URS充值通知Webhook处理器
@@ -88,30 +89,102 @@ class UrsDepositWebhook extends \ThirdParty\Urs\Webhook\WebhookReceiver
     /**
      * 处理充值通知
      *
-     * @param Request $request 请求对象
+     * @param int $user_id URS用户ID
+     * @param string $amount 充值金额
+     * @param string $order_id URS订单ID
      * @return array
      */
     protected function processDepositNotification($user_id, $amount, $order_id): array
     {
-
-        
         // 记录处理日志
-        Log::info("URS充值通知处理", [
-            'user_id'    => $user_id,
-            'amount'     => $amount,
-            'order_id'   => $order_id,
-            'request_id' => $this->getRequestId(),
+        Log::info("URS充值通知处理开始", [
+            'urs_user_id' => $user_id,
+            'amount'      => $amount,
+            'order_id'    => $order_id,
+            'request_id'  => $this->getRequestId(),
         ]);
 
-        // 使用  Transfer模块 ，完成充值 钻石 操作
-
-
-        $rorder_id = time();
+        try {
+            /**
+             * 三方应用ID
+             * @var int $thirdPartyAppId
+             */
+            $thirdPartyAppId = $this->service->id;
+
+            // 1. 根据URS用户ID获取农场用户ID
+            $farmUserId = \App\Module\UrsPromotion\Services\UrsUserMappingService::getFarmUserId($user_id);
+
+            if (!$farmUserId) {
+                Log::error("URS充值失败：未找到用户映射关系", [
+                    'urs_user_id' => $user_id,
+                    'order_id'    => $order_id,
+                ]);
+                throw new \Exception("用户未进入农场系统，无法完成充值");
+            }
 
-        return [
-            'rorder_id' => $rorder_id
-        ];
+            // 2. 开启数据库事务并使用Transfer模块完成充值钻石操作
+            $result = DB::transaction(function () use ($thirdPartyAppId, $farmUserId, $user_id, $amount, $order_id) {
+                return \App\Module\Transfer\Services\TransferThirdPartyService::createRechargeOrder(
+                    thirdPartyAppId: $thirdPartyAppId,
+                    farmUserId: $farmUserId,
+                    thirdPartyUserId: (string)$user_id,
+                    thirdPartyAmount: $amount,
+                    remark: "URS充值 - 订单号: {$order_id}",
+                    callbackData: [
+                        'urs_order_id' => $order_id,
+                        'urs_user_id' => $user_id,
+                        'source' => 'urs_deposit_webhook'
+                    ]
+                );
+            });
+
+            // 3. 检查充值结果
+            if (is_string($result)) {
+                // 充值失败
+                Log::error("URS充值失败", [
+                    'urs_user_id'        => $user_id,
+                    'farm_user_id'       => $farmUserId,
+                    'third_party_app_id' => $thirdPartyAppId,
+                    'amount'             => $amount,
+                    'order_id'           => $order_id,
+                    'error'              => $result,
+                ]);
+                throw new \Exception("充值失败: {$result}");
+            }
 
+            // 4. 充值成功，记录成功日志
+            Log::info("URS充值成功", [
+                'urs_user_id'        => $user_id,
+                'farm_user_id'       => $farmUserId,
+                'third_party_app_id' => $thirdPartyAppId,
+                'amount'             => $amount,
+                'order_id'           => $order_id,
+                'transfer_order_id'  => $result->id,
+                'business_id'        => $result->out_order_id,
+                'actual_amount'      => $result->out_amount,
+            ]);
+
+            // 5. 返回成功响应
+            return [
+                'rorder_id' => $result->out_order_id, // 返回Transfer模块生成的业务订单ID
+                'transfer_order_id' => $result->id,   // Transfer模块的内部订单ID
+                'actual_amount' => $result->out_amount, // 实际到账金额
+                'status' => 'success'
+            ];
+
+        } catch (\Exception $e) {
+            // 记录异常日志
+            Log::error("URS充值处理异常", [
+                'urs_user_id' => $user_id,
+                'amount'      => $amount,
+                'order_id'    => $order_id,
+                'error'       => $e->getMessage(),
+                'trace'       => $e->getTraceAsString(),
+            ]);
+
+            // 重新抛出异常，让上层处理
+            throw $e;
+        }
     }
 
 

app/Module/Fund/Events/FundChangedEvent.php

@@ -59,9 +59,9 @@ class FundChangedEvent
     /**
      * 操作ID
      *
-     * @var int
+     * @var int|string
      */
-    public int $operateId;
+    public $operateId;
 
     /**
      * 备注
@@ -79,7 +79,7 @@ class FundChangedEvent
      * @param int $beforeBalance 变更前余额（毫）
      * @param int $afterBalance 变更后余额（毫）
      * @param int $operateType 操作类型
-     * @param int $operateId 操作ID
+     * @param int|string $operateId 操作ID
      * @param string $remark 备注
      * @return void
      */
@@ -90,7 +90,7 @@ class FundChangedEvent
         int $beforeBalance,
         int $afterBalance,
         int $operateType,
-        int $operateId,
+        $operateId,
         string $remark
     ) {
         $this->userId = $userId;

app/Module/Transfer/Dtos/TransferFeeDto.php

@@ -0,0 +1,213 @@
+<?php
+
+namespace App\Module\Transfer\Dtos;
+
+use UCore\Dto\BaseDto;
+
+/**
+ * 划转手续费计算结果数据传输对象
+ * 
+ * 用于表示手续费计算的结果，包含手续费率、手续费金额、实际到账金额等信息
+ */
+class TransferFeeDto extends BaseDto
+{
+    /**
+     * 构造函数
+     * 
+     * @param float $feeRate 手续费率（小数形式，如 0.01 表示 1%）
+     * @param string $feeAmount 手续费金额（字符串格式，保持精度）
+     * @param string $actualAmount 实际到账金额（字符串格式，保持精度）
+     * @param string $originalAmount 原始金额（字符串格式，保持精度）
+     * @param bool $hasError 是否有错误
+     * @param string|null $errorMessage 错误信息
+     * @param array $additionalInfo 额外信息
+     */
+    public function __construct(
+        public readonly float $feeRate,
+        public readonly string $feeAmount,
+        public readonly string $actualAmount,
+        public readonly string $originalAmount,
+        public readonly bool $hasError = false,
+        public readonly ?string $errorMessage = null,
+        public readonly array $additionalInfo = []
+    ) {}
+
+    /**
+     * 创建成功的手续费计算结果
+     * 
+     * @param string $originalAmount 原始金额
+     * @param float $feeRate 手续费率
+     * @param string $feeAmount 手续费金额
+     * @param string $actualAmount 实际到账金额
+     * @param array $additionalInfo 额外信息
+     * @return self
+     */
+    public static function success(
+        string $originalAmount,
+        float $feeRate,
+        string $feeAmount,
+        string $actualAmount,
+        array $additionalInfo = []
+    ): self {
+        return new self(
+            feeRate: $feeRate,
+            feeAmount: $feeAmount,
+            actualAmount: $actualAmount,
+            originalAmount: $originalAmount,
+            hasError: false,
+            errorMessage: null,
+            additionalInfo: $additionalInfo
+        );
+    }
+
+    /**
+     * 创建错误的手续费计算结果
+     * 
+     * @param string $originalAmount 原始金额
+     * @param string $errorMessage 错误信息
+     * @param array $additionalInfo 额外信息
+     * @return self
+     */
+    public static function error(
+        string $originalAmount,
+        string $errorMessage,
+        array $additionalInfo = []
+    ): self {
+        return new self(
+            feeRate: 0.0000,
+            feeAmount: '0.0000',
+            actualAmount: $originalAmount,
+            originalAmount: $originalAmount,
+            hasError: true,
+            errorMessage: $errorMessage,
+            additionalInfo: $additionalInfo
+        );
+    }
+
+    /**
+     * 从数组创建DTO（兼容旧的数组格式）
+     *
+     * @param array $data 数组数据
+     * @param string $originalAmount 原始金额
+     * @return self
+     */
+    public static function fromLegacyArray(array $data, string $originalAmount = ''): self
+    {
+        // 检查是否有错误
+        if (isset($data['error'])) {
+            return self::error(
+                originalAmount: $originalAmount,
+                errorMessage: $data['error'],
+                additionalInfo: array_diff_key($data, array_flip(['error']))
+            );
+        }
+
+        return self::success(
+            originalAmount: $originalAmount,
+            feeRate: (float) ($data['fee_rate'] ?? 0.0000),
+            feeAmount: (string) ($data['fee_amount'] ?? '0.0000'),
+            actualAmount: (string) ($data['actual_amount'] ?? $originalAmount),
+            additionalInfo: array_diff_key($data, array_flip(['fee_rate', 'fee_amount', 'actual_amount']))
+        );
+    }
+
+    /**
+     * 转换为数组（保持向后兼容）
+     * 
+     * @return array
+     */
+    public function toArray(): array
+    {
+        $result = [
+            'fee_rate' => $this->feeRate,
+            'fee_amount' => $this->feeAmount,
+            'actual_amount' => $this->actualAmount,
+            'original_amount' => $this->originalAmount,
+            'has_error' => $this->hasError,
+        ];
+
+        // 如果有错误，添加错误信息
+        if ($this->hasError && $this->errorMessage) {
+            $result['error'] = $this->errorMessage;
+        }
+
+        // 添加额外信息
+        if (!empty($this->additionalInfo)) {
+            $result = array_merge($result, $this->additionalInfo);
+        }
+
+        return $result;
+    }
+
+    /**
+     * 转换为兼容旧格式的数组
+     * 
+     * @return array
+     */
+    public function toLegacyArray(): array
+    {
+        if ($this->hasError) {
+            return [
+                'error' => $this->errorMessage,
+                'fee_rate' => $this->feeRate,
+                'fee_amount' => $this->feeAmount,
+                'actual_amount' => $this->actualAmount,
+            ];
+        }
+
+        return [
+            'fee_rate' => $this->feeRate,
+            'fee_amount' => $this->feeAmount,
+            'actual_amount' => $this->actualAmount,
+        ];
+    }
+
+    /**
+     * 获取手续费率百分比格式
+     * 
+     * @param int $decimals 小数位数
+     * @return string
+     */
+    public function getFeeRatePercent(int $decimals = 2): string
+    {
+        return number_format($this->feeRate * 100, $decimals) . '%';
+    }
+
+    /**
+     * 判断是否有手续费
+     * 
+     * @return bool
+     */
+    public function hasFee(): bool
+    {
+        return bccomp($this->feeAmount, '0', 10) > 0;
+    }
+
+    /**
+     * 判断是否计算成功
+     * 
+     * @return bool
+     */
+    public function isSuccess(): bool
+    {
+        return !$this->hasError;
+    }
+
+    /**
+     * 获取格式化的手续费信息
+     * 
+     * @return string
+     */
+    public function getFormattedFeeInfo(): string
+    {
+        if ($this->hasError) {
+            return "计算失败: {$this->errorMessage}";
+        }
+
+        if (!$this->hasFee()) {
+            return "无手续费";
+        }
+
+        return "手续费: {$this->feeAmount} ({$this->getFeeRatePercent()})";
+    }
+}

app/Module/Transfer/Services/TransferThirdPartyService.php

@@ -3,6 +3,7 @@
 namespace App\Module\Transfer\Services;
 
 use App\Module\Transfer\Dtos\TransferOrderDto;
+use App\Module\Transfer\Dtos\TransferFeeDto;
 use App\Module\Transfer\Logics\TransferLogic;
 use App\Module\Transfer\Models\TransferApp;
 
@@ -220,53 +221,57 @@ class TransferThirdPartyService
 
     /**
      * 计算充值手续费
-     * 
+     *
      * @param int $thirdPartyAppId 三方应用ID
      * @param string $amount 充值金额
-     * @return array
+     * @return TransferFeeDto
      */
-    public static function calculateRechargeFee(int $thirdPartyAppId, string $amount): array
+    public static function calculateRechargeFee(int $thirdPartyAppId, string $amount): TransferFeeDto
     {
         $transferApp = self::getTransferAppByThirdPartyId($thirdPartyAppId);
-        
+
         if (!$transferApp) {
-            return [
-                'error' => '未找到对应的划转应用配置',
-                'fee_rate' => 0.0000,
-                'fee_amount' => '0.0000',
-                'actual_amount' => $amount,
-            ];
+            return TransferFeeDto::error(
+                originalAmount: $amount,
+                errorMessage: '未找到对应的划转应用配置'
+            );
         }
 
         // 将三方金额转换为农场内部金额
         $internalAmount = bcdiv($amount, (string) $transferApp->exchange_rate, 10);
-        
-        return $transferApp->calculateInFee($internalAmount);
+
+        // 获取手续费计算结果
+        $feeResult = $transferApp->calculateInFee($internalAmount);
+
+        // 将结果转换为DTO
+        return TransferFeeDto::fromLegacyArray($feeResult, $amount);
     }
 
     /**
      * 计算提现手续费
-     * 
+     *
      * @param int $thirdPartyAppId 三方应用ID
      * @param string $amount 提现金额
-     * @return array
+     * @return TransferFeeDto
      */
-    public static function calculateWithdrawFee(int $thirdPartyAppId, string $amount): array
+    public static function calculateWithdrawFee(int $thirdPartyAppId, string $amount): TransferFeeDto
     {
         $transferApp = self::getTransferAppByThirdPartyId($thirdPartyAppId);
-        
+
         if (!$transferApp) {
-            return [
-                'error' => '未找到对应的划转应用配置',
-                'fee_rate' => 0.0000,
-                'fee_amount' => '0.0000',
-                'actual_amount' => $amount,
-            ];
+            return TransferFeeDto::error(
+                originalAmount: $amount,
+                errorMessage: '未找到对应的划转应用配置'
+            );
         }
 
         // 将三方金额转换为农场内部金额
         $internalAmount = bcmul($amount, (string) $transferApp->exchange_rate, 10);
-        
-        return $transferApp->calculateOutFee($internalAmount);
+
+        // 获取手续费计算结果
+        $feeResult = $transferApp->calculateOutFee($internalAmount);
+
+        // 将结果转换为DTO
+        return TransferFeeDto::fromLegacyArray($feeResult, $amount);
     }
 }

app/Module/Transfer/Validations/TransferOutValidation.php

@@ -12,6 +12,9 @@ class TransferOutValidation extends ValidationCore
     /** @var \App\Module\Transfer\Models\TransferApp|null 转账应用对象，由验证器设置 */
     public ?\App\Module\Transfer\Models\TransferApp $transfer_app = null;
 
+    /** @var bool 是否跳过密码验证（用于第三方应用） */
+    public bool $skip_password_validation = false;
+
     /**
      * 验证规则
      */

test_transfer_fee_dto.php

@@ -0,0 +1,191 @@
+<?php
+
+/**
+ * 测试 TransferFeeDto 优化功能
+ * 
+ * 验证 calculateWithdrawFee 和 calculateRechargeFee 方法返回 DTO 对象的功能
+ */
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+// 初始化Laravel应用
+$app = require_once __DIR__ . '/bootstrap/app.php';
+$app->make(\Illuminate\Contracts\Console\Kernel::class)->bootstrap();
+
+use App\Module\Transfer\Services\TransferThirdPartyService;
+use App\Module\Transfer\Dtos\TransferFeeDto;
+
+echo "=== Transfer Fee DTO 测试开始 ===\n\n";
+
+// 测试数据
+$testCases = [
+    [
+        'name' => '正常提现手续费计算',
+        'third_party_app_id' => 11, // URS应用ID
+        'amount' => '100.0000',
+        'method' => 'calculateWithdrawFee'
+    ],
+    [
+        'name' => '正常充值手续费计算',
+        'third_party_app_id' => 11, // URS应用ID
+        'amount' => '100.0000',
+        'method' => 'calculateRechargeFee'
+    ],
+    [
+        'name' => '不存在的应用ID - 提现',
+        'third_party_app_id' => 999,
+        'amount' => '100.0000',
+        'method' => 'calculateWithdrawFee'
+    ],
+    [
+        'name' => '不存在的应用ID - 充值',
+        'third_party_app_id' => 999,
+        'amount' => '100.0000',
+        'method' => 'calculateRechargeFee'
+    ],
+    [
+        'name' => '小额提现测试',
+        'third_party_app_id' => 11,
+        'amount' => '1.0000',
+        'method' => 'calculateWithdrawFee'
+    ],
+    [
+        'name' => '大额提现测试',
+        'third_party_app_id' => 11,
+        'amount' => '10000.0000',
+        'method' => 'calculateWithdrawFee'
+    ]
+];
+
+foreach ($testCases as $index => $testCase) {
+    echo "测试 " . ($index + 1) . ": {$testCase['name']}\n";
+    echo "应用ID: {$testCase['third_party_app_id']}, 金额: {$testCase['amount']}, 方法: {$testCase['method']}\n";
+    
+    try {
+        // 调用对应的方法
+        if ($testCase['method'] === 'calculateWithdrawFee') {
+            $result = TransferThirdPartyService::calculateWithdrawFee(
+                $testCase['third_party_app_id'],
+                $testCase['amount']
+            );
+        } else {
+            $result = TransferThirdPartyService::calculateRechargeFee(
+                $testCase['third_party_app_id'],
+                $testCase['amount']
+            );
+        }
+        
+        // 验证返回类型
+        if (!($result instanceof TransferFeeDto)) {
+            echo "❌ 错误: 返回类型不是 TransferFeeDto，实际类型: " . get_class($result) . "\n";
+            continue;
+        }
+        
+        echo "✅ 返回类型正确: TransferFeeDto\n";
+        
+        // 显示DTO属性
+        echo "DTO 属性:\n";
+        echo "  - 原始金额: {$result->originalAmount}\n";
+        echo "  - 手续费率: {$result->feeRate} ({$result->getFeeRatePercent()})\n";
+        echo "  - 手续费金额: {$result->feeAmount}\n";
+        echo "  - 实际到账金额: {$result->actualAmount}\n";
+        echo "  - 是否有错误: " . ($result->hasError ? '是' : '否') . "\n";
+        
+        if ($result->hasError) {
+            echo "  - 错误信息: {$result->errorMessage}\n";
+        }
+        
+        echo "  - 是否有手续费: " . ($result->hasFee() ? '是' : '否') . "\n";
+        echo "  - 格式化手续费信息: {$result->getFormattedFeeInfo()}\n";
+        
+        // 测试向后兼容性 - toLegacyArray 方法
+        echo "\n向后兼容性测试:\n";
+        $legacyArray = $result->toLegacyArray();
+        echo "Legacy Array 格式:\n";
+        foreach ($legacyArray as $key => $value) {
+            echo "  - {$key}: {$value}\n";
+        }
+        
+        // 测试 toArray 方法
+        echo "\n完整 Array 格式:\n";
+        $fullArray = $result->toArray();
+        foreach ($fullArray as $key => $value) {
+            if (is_array($value)) {
+                echo "  - {$key}: " . json_encode($value) . "\n";
+            } else {
+                echo "  - {$key}: {$value}\n";
+            }
+        }
+        
+        // 测试 fromLegacyArray 静态方法
+        echo "\n测试 fromLegacyArray 静态方法:\n";
+        $recreatedDto = TransferFeeDto::fromLegacyArray($legacyArray, $testCase['amount']);
+        echo "重新创建的DTO是否与原DTO相等: " .
+             ($recreatedDto->feeAmount === $result->feeAmount &&
+              $recreatedDto->actualAmount === $result->actualAmount ? '是' : '否') . "\n";
+        
+    } catch (\Exception $e) {
+        echo "❌ 异常: " . $e->getMessage() . "\n";
+        echo "堆栈跟踪: " . $e->getTraceAsString() . "\n";
+    }
+    
+    echo "\n" . str_repeat("-", 80) . "\n\n";
+}
+
+// 测试URS余额检查功能的兼容性
+echo "=== URS余额检查兼容性测试 ===\n\n";
+
+try {
+    // 模拟URS余额检查中的调用
+    $thirdPartyAppId = 11; // URS应用ID
+    $amount = '50.0000';
+    
+    echo "模拟URS余额检查调用:\n";
+    echo "应用ID: {$thirdPartyAppId}, 金额: {$amount}\n";
+    
+    $feeDto = TransferThirdPartyService::calculateWithdrawFee($thirdPartyAppId, $amount);
+    
+    echo "返回的DTO类型: " . get_class($feeDto) . "\n";
+    echo "是否有错误: " . ($feeDto->hasError ? '是' : '否') . "\n";
+    
+    if ($feeDto->hasError) {
+        echo "错误信息: {$feeDto->errorMessage}\n";
+        
+        // 模拟URS余额检查中的错误处理
+        $response = [
+            'check' => false,
+            'diamond_balance' => '0.0000',
+            'principal_total' => $amount,
+            'fee_total' => '0.0000',
+            'required_total' => $amount,
+            'message' => $feeDto->errorMessage
+        ];
+        
+        echo "URS错误响应:\n";
+        echo json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n";
+    } else {
+        echo "手续费金额: {$feeDto->feeAmount}\n";
+        
+        // 模拟URS余额检查中的成功处理
+        $principalAmount = $amount;
+        $feeAmount = $feeDto->feeAmount;
+        $requiredTotal = bcadd($principalAmount, $feeAmount, 4);
+        
+        $response = [
+            'check' => true, // 这里假设余额充足
+            'diamond_balance' => '1000.0000', // 假设余额
+            'principal_total' => $principalAmount,
+            'fee_total' => $feeAmount,
+            'required_total' => $requiredTotal,
+            'message' => '余额充足，允许提取'
+        ];
+        
+        echo "URS成功响应:\n";
+        echo json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n";
+    }
+    
+} catch (\Exception $e) {
+    echo "❌ URS兼容性测试异常: " . $e->getMessage() . "\n";
+}
+
+echo "\n=== 测试完成 ===\n";

test_urs_check_with_dto.php

@@ -0,0 +1,147 @@
+<?php
+
+/**
+ * 测试URS余额检查功能与新的DTO集成
+ */
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+// 初始化Laravel应用
+$app = require_once __DIR__ . '/bootstrap/app.php';
+$app->make(\Illuminate\Contracts\Console\Kernel::class)->bootstrap();
+
+echo "=== URS余额检查DTO集成测试 ===\n\n";
+
+// 测试数据
+$testData = [
+    'user_id' => 10003,  // URS用户ID
+    'amount' => '50.0000'
+];
+
+// 生成签名
+$secretKey = 'test_secret_key_for_urs_integration_2024';
+$timestamp = time();
+$signData = [
+    'user_id' => $testData['user_id'],
+    'amount' => $testData['amount'],
+    'timestamp' => $timestamp
+];
+
+ksort($signData);
+$signString = http_build_query($signData);
+$signature = hash_hmac('sha256', $signString, $secretKey);
+
+echo "测试数据:\n";
+echo "URS用户ID: {$testData['user_id']}\n";
+echo "提取金额: {$testData['amount']}\n";
+echo "时间戳: {$timestamp}\n";
+echo "签名: {$signature}\n\n";
+
+// 构造请求数据
+$requestData = array_merge($testData, [
+    'timestamp' => $timestamp,
+    'signature' => $signature
+]);
+
+try {
+    // 模拟URS余额检查的核心逻辑
+    echo "模拟URS余额检查核心逻辑...\n";
+
+    $userId = $testData['user_id'];
+    $amount = $testData['amount'];
+    $thirdPartyAppId = 11; // URS应用ID
+
+    // 1. 查找用户映射关系
+    $userMapping = \App\Module\UrsPromotion\Models\UrsUserMapping::where('urs_user_id', $userId)
+        ->where('status', 1)
+        ->first();
+
+    if (!$userMapping) {
+        $result = [
+            'check' => false,
+            'diamond_balance' => '0.0000',
+            'principal_total' => $amount,
+            'fee_total' => '0.0000',
+            'required_total' => $amount,
+            'message' => '用户未进入农场系统'
+        ];
+    } else {
+        $farmUserId = $userMapping->user_id;
+        echo "找到用户映射: URS用户{$userId} -> 农场用户{$farmUserId}\n";
+
+        // 2. 使用TransferThirdPartyService计算提取费用
+        $feeDto = \App\Module\Transfer\Services\TransferThirdPartyService::calculateWithdrawFee(
+            $thirdPartyAppId,
+            $amount
+        );
+
+        if ($feeDto->hasError) {
+            $result = [
+                'check' => false,
+                'diamond_balance' => '0.0000',
+                'principal_total' => $amount,
+                'fee_total' => '0.0000',
+                'required_total' => $amount,
+                'message' => $feeDto->errorMessage
+            ];
+        } else {
+            // 3. 获取用户钻石余额
+            $userFundService = new \App\Module\Fund\Services\FundService($farmUserId, 2); // 2是钻石的fund_id
+            $diamondBalance = $userFundService->balance();
+            $diamondBalanceFormatted = number_format($diamondBalance / 10000, 4); // 转换为显示格式
+
+            // 4. 计算所需总金额（本金 + 手续费）
+            $principalAmount = $amount;
+            $feeAmount = $feeDto->feeAmount;
+            $requiredTotal = bcadd($principalAmount, $feeAmount, 4);
+
+            // 5. 检查余额是否足够
+            $requiredTotalInCents = bcmul($requiredTotal, '10000', 0); // 转换为存储格式（分）
+            $isAllowed = $diamondBalance >= $requiredTotalInCents;
+
+            $result = [
+                'check' => $isAllowed,
+                'diamond_balance' => $diamondBalanceFormatted,
+                'principal_total' => $principalAmount,
+                'fee_total' => $feeAmount,
+                'required_total' => $requiredTotal,
+                'message' => $isAllowed ? '余额充足，允许提取' : '余额不足，无法提取'
+            ];
+        }
+    }
+    
+    echo "返回结果:\n";
+    echo json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n\n";
+    
+    // 验证结果结构
+    $expectedKeys = ['check', 'diamond_balance', 'principal_total', 'fee_total', 'required_total', 'message'];
+    $missingKeys = array_diff($expectedKeys, array_keys($result));
+    
+    if (empty($missingKeys)) {
+        echo "✅ 返回结果结构正确，包含所有必需字段\n";
+    } else {
+        echo "❌ 返回结果缺少字段: " . implode(', ', $missingKeys) . "\n";
+    }
+    
+    // 验证数据类型
+    echo "\n字段类型验证:\n";
+    echo "- check: " . gettype($result['check']) . " (" . ($result['check'] ? 'true' : 'false') . ")\n";
+    echo "- diamond_balance: " . gettype($result['diamond_balance']) . " ({$result['diamond_balance']})\n";
+    echo "- principal_total: " . gettype($result['principal_total']) . " ({$result['principal_total']})\n";
+    echo "- fee_total: " . gettype($result['fee_total']) . " ({$result['fee_total']})\n";
+    echo "- required_total: " . gettype($result['required_total']) . " ({$result['required_total']})\n";
+    echo "- message: " . gettype($result['message']) . " ({$result['message']})\n";
+    
+    // 验证数值计算
+    echo "\n数值计算验证:\n";
+    $calculatedTotal = bcadd($result['principal_total'], $result['fee_total'], 4);
+    echo "本金 + 手续费 = {$result['principal_total']} + {$result['fee_total']} = {$calculatedTotal}\n";
+    echo "返回的required_total: {$result['required_total']}\n";
+    echo "计算是否正确: " . ($calculatedTotal === $result['required_total'] ? '✅ 是' : '❌ 否') . "\n";
+    
+} catch (\Exception $e) {
+    echo "❌ 测试异常: " . $e->getMessage() . "\n";
+    echo "堆栈跟踪:\n" . $e->getTraceAsString() . "\n";
+}
+
+echo "\n=== 测试完成 ===\n";