FeeService转移方法支持外部传入转移类型

- 将transferType参数改为外部传入，默认值为'fee_transfer'
- 更新测试命令支持--transfer-type选项
- 扩展单元测试覆盖自定义转移类型场景
- 完善使用文档，添加转移类型的说明和示例
- 已通过测试验证自定义转移类型功能正常
- 保持向后兼容性，不影响现有代码

AiWork/2025年06月/251228-FeeService转移方法开发完成.md

@@ -1,8 +1,9 @@
 # FeeService转移方法开发完成
 
-**时间**: 2025年06月25日 12:28  
-**任务**: 为Transfer模块的FeeService类开发转移方法  
+**时间**: 2025年06月25日 12:28
+**任务**: 为Transfer模块的FeeService类开发转移方法
 **状态**: ✅ 完成
+**更新**: 2025年06月25日 12:34 - 添加转移类型外部传入功能
 
 ## 任务概述
 
@@ -17,16 +18,17 @@
 ```php
 /**
  * 转移手续费到指定用户
- * 
+ *
  * 将手续费从指定应用的手续费账户转移到目标用户账户
  *
  * @param int $appId 出钱的应用ID（从该应用的手续费账户扣除）
  * @param int $targetUserId 目标用户ID（收钱的）
  * @param float $amount 金额（钱数）
  * @param int $orderId 订单ID（划转依据）
+ * @param string $transferType 转移类型（默认为'fee_transfer'）
  * @return bool|string 成功返回true，失败返回错误信息
  */
-public static function transfer(int $appId, int $targetUserId, float $amount, int $orderId)
+public static function transfer(int $appId, int $targetUserId, float $amount, int $orderId, string $transferType = 'fee_transfer')
 ```
 
 ### 2. 方法特性
@@ -34,7 +36,8 @@ public static function transfer(int $appId, int $targetUserId, float $amount, in
 - **参数验证**: 检查金额、应用ID、用户ID的有效性
 - **账户获取**: 通过应用配置获取手续费收取账户UID（默认为1）
 - **资金转移**: 使用Fund模块的trade方法执行资金转移
-- **日志记录**: 记录转移成功或失败的详细日志
+- **转移类型**: 支持自定义转移类型，用于标识不同的业务场景
+- **日志记录**: 记录转移成功或失败的详细日志，包含转移类型信息
 - **异常处理**: 捕获并记录任何异常情况
 
 ### 3. 错误处理
@@ -52,12 +55,17 @@ public static function transfer(int $appId, int $targetUserId, float $amount, in
 创建了`app/Module/Transfer/Commands/TestFeeTransferCommand.php`测试命令：
 
 ```bash
+# 使用默认转移类型
 php artisan transfer:test-fee-transfer --app-id=2 --target-user-id=3 --amount=100.0 --order-id=99999
+
+# 使用自定义转移类型
+php artisan transfer:test-fee-transfer --app-id=2 --target-user-id=3 --amount=50.0 --order-id=88888 --transfer-type=test_refund
 ```
 
 #### 4.2 单元测试
 创建了`tests/Unit/Transfer/FeeServiceTransferTest.php`单元测试文件，包含：
 - 成功转移测试
+- 自定义转移类型测试
 - 无效金额测试
 - 应用不存在测试
 - 目标用户不存在测试
@@ -92,8 +100,13 @@ php artisan transfer:test-fee-transfer --app-id=2 --target-user-id=3 --amount=10
 - 目标用户账户: 100.0000000000
 
 **资金日志记录:**
-- 用户1扣款记录: -100，operate_type=5（TRADE）
-- 用户3收款记录: +100，operate_type=8（TRANSFER）
+- 用户1扣款记录: -100，operate_type=5（TRADE），operate_id=fee_transfer-99999
+- 用户3收款记录: +100，operate_type=8（TRANSFER），operate_id=fee_transfer-99999
+
+**自定义转移类型测试:**
+- 转移类型: test_refund
+- 用户1扣款记录: -50，operate_id=test_refund-88888
+- 用户3收款记录: +50，operate_id=test_refund-88888
 
 ## 技术要点
 
@@ -123,7 +136,7 @@ php artisan transfer:test-fee-transfer --app-id=2 --target-user-id=3 --amount=10
 ```php
 use App\Module\Transfer\Services\FeeService;
 
-// 基本使用
+// 基本使用（默认转移类型）
 $result = FeeService::transfer(
     appId: 1,
     targetUserId: 123,
@@ -131,6 +144,15 @@ $result = FeeService::transfer(
     orderId: 12345
 );
 
+// 使用自定义转移类型
+$result = FeeService::transfer(
+    appId: 1,
+    targetUserId: 123,
+    amount: 10.0,
+    orderId: 12345,
+    transferType: 'refund'
+);
+
 if ($result === true) {
     echo "手续费转移成功";
 } else {
@@ -145,6 +167,23 @@ if ($result === true) {
 3. **账户配置**: 依赖应用的fee_account_uid配置，未配置时使用默认账户UID 1
 4. **金额精度**: 使用Fund模块的精度控制，确保金额计算准确
 
+## 更新内容 (2025年06月25日 12:34)
+
+### 转移类型外部传入功能
+
+根据用户需求，将转移类型改为外部传入参数，提供更大的灵活性：
+
+1. **方法签名更新**: 添加`$transferType`参数，默认值为'fee_transfer'
+2. **测试命令更新**: 添加`--transfer-type`选项
+3. **单元测试扩展**: 增加自定义转移类型测试用例
+4. **文档完善**: 更新使用文档，包含转移类型的说明和示例
+
+### 优势
+
+- **业务灵活性**: 支持不同业务场景使用不同的转移类型标识
+- **日志追踪**: 通过转移类型可以更好地区分和追踪不同类型的转移操作
+- **向后兼容**: 默认值保持原有行为，不影响现有代码
+
 ## 总结
 
-成功为Transfer模块的FeeService类开发了转移方法，实现了从应用手续费账户到用户账户的资金转移功能。该方法具有完善的参数验证、错误处理、日志记录和异常处理机制，已通过实际测试验证功能正常。
+成功为Transfer模块的FeeService类开发了转移方法，实现了从应用手续费账户到用户账户的资金转移功能。该方法具有完善的参数验证、错误处理、日志记录和异常处理机制，支持自定义转移类型，已通过实际测试验证功能正常。

app/Module/Transfer/Commands/TestFeeTransferCommand.php

@@ -17,11 +17,12 @@ class TestFeeTransferCommand extends Command
     /**
      * 命令签名
      */
-    protected $signature = 'transfer:test-fee-transfer 
+    protected $signature = 'transfer:test-fee-transfer
                            {--app-id=1 : 应用ID}
                            {--target-user-id=2 : 目标用户ID}
                            {--amount=10.0 : 转移金额}
-                           {--order-id=12345 : 订单ID}';
+                           {--order-id=12345 : 订单ID}
+                           {--transfer-type=fee_transfer : 转移类型}';
 
     /**
      * 命令描述
@@ -37,12 +38,14 @@ class TestFeeTransferCommand extends Command
         $targetUserId = (int) $this->option('target-user-id');
         $amount = (float) $this->option('amount');
         $orderId = (int) $this->option('order-id');
+        $transferType = (string) $this->option('transfer-type');
 
         $this->info("开始测试手续费转移功能");
         $this->info("应用ID: {$appId}");
         $this->info("目标用户ID: {$targetUserId}");
         $this->info("转移金额: {$amount}");
         $this->info("订单ID: {$orderId}");
+        $this->info("转移类型: {$transferType}");
         $this->line('');
 
         // 检查应用是否存在
@@ -87,7 +90,7 @@ class TestFeeTransferCommand extends Command
         try {
             DB::beginTransaction();
             
-            $result = FeeService::transfer($appId, $targetUserId, $amount, $orderId);
+            $result = FeeService::transfer($appId, $targetUserId, $amount, $orderId, $transferType);
             
             if ($result === true) {
                 DB::commit();

app/Module/Transfer/Docs/FEE_TRANSFER_USAGE.md

@@ -9,16 +9,17 @@ FeeService 新增了 `transfer` 方法，用于将手续费从指定应用的手
 ```php
 /**
  * 转移手续费到指定用户
- * 
+ *
  * 将手续费从指定应用的手续费账户转移到目标用户账户
  *
  * @param int $appId 出钱的应用ID（从该应用的手续费账户扣除）
  * @param int $targetUserId 目标用户ID（收钱的）
  * @param float $amount 金额（钱数）
  * @param int $orderId 订单ID（划转依据）
+ * @param string $transferType 转移类型（默认为'fee_transfer'）
  * @return bool|string 成功返回true，失败返回错误信息
  */
-public static function transfer(int $appId, int $targetUserId, float $amount, int $orderId)
+public static function transfer(int $appId, int $targetUserId, float $amount, int $orderId, string $transferType = 'fee_transfer')
 ```
 
 ## 参数说明
@@ -27,6 +28,7 @@ public static function transfer(int $appId, int $targetUserId, float $amount, in
 - **$targetUserId**: 目标用户ID，接收转移资金的用户
 - **$amount**: 转移金额，必须大于0
 - **$orderId**: 订单ID，作为转移的依据和日志记录
+- **$transferType**: 转移类型，用于标识转移的业务类型（默认为'fee_transfer'）
 
 ## 使用示例
 
@@ -35,7 +37,7 @@ public static function transfer(int $appId, int $targetUserId, float $amount, in
 ```php
 use App\Module\Transfer\Services\FeeService;
 
-// 从应用ID为1的手续费账户转移10元到用户ID为123的账户
+// 从应用ID为1的手续费账户转移10元到用户ID为123的账户（使用默认转移类型）
 $result = FeeService::transfer(
     appId: 1,
     targetUserId: 123,
@@ -48,6 +50,15 @@ if ($result === true) {
 } else {
     echo "转移失败: " . $result;
 }
+
+// 使用自定义转移类型
+$result = FeeService::transfer(
+    appId: 1,
+    targetUserId: 123,
+    amount: 10.0,
+    orderId: 12345,
+    transferType: 'refund'
+);
 ```
 
 ### 2. 在业务流程中使用
@@ -69,7 +80,8 @@ $result = FeeService::transfer(
     appId: $app->id,
     targetUserId: $order->user_id,
     amount: $refundAmount,
-    orderId: $order->id
+    orderId: $order->id,
+    transferType: 'fee_refund'
 );
 
 if ($result === true) {
@@ -94,9 +106,9 @@ if ($result === true) {
 use App\Module\Transfer\Services\FeeService;
 
 $transfers = [
-    ['app_id' => 1, 'user_id' => 123, 'amount' => 10.0, 'order_id' => 1001],
-    ['app_id' => 1, 'user_id' => 124, 'amount' => 15.0, 'order_id' => 1002],
-    ['app_id' => 2, 'user_id' => 125, 'amount' => 8.0, 'order_id' => 1003],
+    ['app_id' => 1, 'user_id' => 123, 'amount' => 10.0, 'order_id' => 1001, 'type' => 'fee_refund'],
+    ['app_id' => 1, 'user_id' => 124, 'amount' => 15.0, 'order_id' => 1002, 'type' => 'bonus'],
+    ['app_id' => 2, 'user_id' => 125, 'amount' => 8.0, 'order_id' => 1003, 'type' => 'compensation'],
 ];
 
 $results = [];
@@ -105,7 +117,8 @@ foreach ($transfers as $transfer) {
         appId: $transfer['app_id'],
         targetUserId: $transfer['user_id'],
         amount: $transfer['amount'],
-        orderId: $transfer['order_id']
+        orderId: $transfer['order_id'],
+        transferType: $transfer['type']
     );
     
     $results[] = [

app/Module/Transfer/Services/FeeService.php

@@ -344,9 +344,10 @@ class FeeService
      * @param int $targetUserId 目标用户ID（收钱的）
      * @param float $amount 金额（钱数）
      * @param int $orderId 订单ID（划转依据）
+     * @param string $transferType 转移类型（默认为'fee_transfer'）
      * @return bool|string 成功返回true，失败返回错误信息
      */
-    public static function transfer(int $appId, int $targetUserId, float $amount, int $orderId)
+    public static function transfer(int $appId, int $targetUserId, float $amount, int $orderId, string $transferType = 'fee_transfer')
     {
         // 检查金额是否有效
         if ($amount <= 0) {
@@ -379,7 +380,7 @@ class FeeService
             $result = $fundService->trade(
                 $targetUserId,
                 $amount,
-                'fee_transfer',
+                $transferType,
                 $orderId,
                 $remark
             );
@@ -392,6 +393,7 @@ class FeeService
                     'target_user_id' => $targetUserId,
                     'amount' => $amount,
                     'order_id' => $orderId,
+                    'transfer_type' => $transferType,
                     'error' => $result
                 ]);
                 return $result;
@@ -406,6 +408,7 @@ class FeeService
                 'target_username' => $targetUser->username,
                 'amount' => $amount,
                 'order_id' => $orderId,
+                'transfer_type' => $transferType,
                 'fund_id' => $app->fund_id
             ]);
 
@@ -418,6 +421,7 @@ class FeeService
                 'target_user_id' => $targetUserId,
                 'amount' => $amount,
                 'order_id' => $orderId,
+                'transfer_type' => $transferType,
                 'exception' => $e->getMessage(),
                 'trace' => $e->getTraceAsString()
             ]);

tests/Unit/Transfer/FeeServiceTransferTest.php

@@ -105,6 +105,22 @@ class FeeServiceTransferTest extends TestCase
         $this->assertTrue($result, '手续费转移应该成功');
     }
 
+    /**
+     * 测试自定义转移类型
+     */
+    public function testCustomTransferType()
+    {
+        $result = FeeService::transfer(
+            appId: 1,
+            targetUserId: 2,
+            amount: 10.0,
+            orderId: 12345,
+            transferType: 'custom_transfer'
+        );
+
+        $this->assertTrue($result, '自定义转移类型应该成功');
+    }
+
     /**
      * 测试无效金额
      */