# Transfer模块API使用指南

## 概述

Transfer模块提供了明确的参数接口，替代了原来难以理解的数组参数方式。新的API更加类型安全，易于理解和维护。

## 创建转出订单

### 完整参数版本

```php
use App\Module\Transfer\Services\TransferService;

// 创建转出订单 - 完整参数
$result = TransferService::createTransferOut(
    transferAppId: 1,                    // 划转应用ID
    userId: 12345,                       // 用户ID
    amount: '100.50',                    // 转出金额
    password: 'user_password',           // 安全密码
    googleCode: '123456',                // 谷歌验证码（可选）
    outUserId: 'external_user_123',      // 外部用户ID（可选）
    remark: '游戏充值',                   // 备注（可选）
    callbackData: ['game_id' => 'abc']   // 回调数据（可选）
);

if (is_string($result)) {
    // 处理错误
    echo "创建失败: " . $result;
} else {
    // 成功，$result 是 TransferOrderDto 对象
    echo "订单创建成功，ID: " . $result->id;
}
```

### 简化版本

```php
// 快速创建转出订单 - 只需必要参数
$result = TransferService::quickCreateTransferOut(
    transferAppId: 1,
    userId: 12345,
    amount: '100.50',
    password: 'user_password'
);
```

## 创建转入订单

### 完整参数版本

```php
// 创建转入订单 - 完整参数
$result = TransferService::createTransferIn(
    transferAppId: 1,                    // 划转应用ID
    userId: 12345,                       // 用户ID
    businessId: 'BIZ_20250618_001',      // 业务订单ID
    amount: '100.50',                    // 转入金额
    outUserId: 'external_user_123',      // 外部用户ID（可选）
    remark: '游戏提现',                   // 备注（可选）
    callbackData: ['game_id' => 'abc']   // 回调数据（可选）
);
```

### 简化版本

```php
// 快速创建转入订单 - 只需必要参数
$result = TransferService::quickCreateTransferIn(
    transferAppId: 1,
    userId: 12345,
    businessId: 'BIZ_20250618_001',
    amount: '100.50'
);
```

## 向后兼容

如果您的代码仍在使用数组参数，可以使用向后兼容方法：

```php
// 向后兼容 - 转出订单
$data = [
    'transfer_app_id' => 1,
    'user_id' => 12345,
    'amount' => '100.50',
    'password' => 'user_password',
    'google_code' => '123456',
    'out_user_id' => 'external_user_123',
    'remark' => '游戏充值',
    'callback_data' => ['game_id' => 'abc']
];

$result = TransferService::createTransferOutFromArray($data);

// 向后兼容 - 转入订单
$data = [
    'transfer_app_id' => 1,
    'user_id' => 12345,
    'out_order_id' => 'BIZ_20250618_001',
    'amount' => '100.50',
    'out_user_id' => 'external_user_123',
    'remark' => '游戏提现',
    'callback_data' => ['game_id' => 'abc']
];

$result = TransferService::createTransferInFromArray($data);
```

## 参数说明

### 转出订单参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| transferAppId | int | 是 | 划转应用ID |
| userId | int | 是 | 用户ID |
| amount | string | 是 | 转出金额（字符串格式，支持小数） |
| password | string | 是 | 用户安全密码 |
| googleCode | string\|null | 否 | 谷歌验证码（6位数字） |
| outUserId | string\|null | 否 | 外部用户ID |
| remark | string\|null | 否 | 备注信息 |
| callbackData | array | 否 | 回调数据（键值对数组） |

### 转入订单参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| transferAppId | int | 是 | 划转应用ID |
| userId | int | 是 | 用户ID |
| businessId | string | 是 | 业务订单ID（外部系统的订单标识） |
| amount | string | 是 | 转入金额（字符串格式，支持小数） |
| outUserId | string\|null | 否 | 外部用户ID |
| remark | string\|null | 否 | 备注信息 |
| callbackData | array | 否 | 回调数据（键值对数组） |

## 返回值处理

所有创建方法都返回 `TransferOrderDto|string`：

- 成功时返回 `TransferOrderDto` 对象
- 失败时返回错误信息字符串

```php
$result = TransferService::createTransferOut(/* 参数 */);

if (is_string($result)) {
    // 处理错误
    $errorMessage = $result;
    // 记录日志、返回错误响应等
} else {
    // 处理成功
    $order = $result; // TransferOrderDto 对象
    $orderId = $order->id;
    $status = $order->status;
    $amount = $order->amount;
    // 其他业务逻辑
}
```

## 最佳实践

1. **使用命名参数**：PHP 8.0+ 支持命名参数，提高代码可读性
2. **类型检查**：利用返回值类型检查处理成功和失败情况
3. **错误处理**：始终检查返回值类型，妥善处理错误情况
4. **参数验证**：在调用API前进行基础参数验证
5. **日志记录**：记录重要的操作和错误信息

## 迁移指南

### 从数组参数迁移

**旧代码：**
```php
$data = [
    'transfer_app_id' => 1,
    'user_id' => 12345,
    'amount' => '100.50',
    'password' => 'password'
];
$result = TransferService::createTransferOut($data);
```

**新代码：**
```php
$result = TransferService::createTransferOut(
    transferAppId: 1,
    userId: 12345,
    amount: '100.50',
    password: 'password'
);
```

### 优势

1. **类型安全**：编译时检查参数类型
2. **IDE支持**：更好的代码补全和提示
3. **可读性**：参数含义一目了然
4. **维护性**：减少参数错误和遗漏
5. **文档化**：参数名称即文档

## 注意事项

1. 金额参数使用字符串类型，避免浮点数精度问题
2. 可选参数使用 null 作为默认值
3. 回调数据必须是关联数组格式
4. 业务订单ID必须在同一应用内唯一
5. 密码和验证码等敏感信息需要妥善处理