# Transfer 模块 API 接口文档

> 更新时间: 2025-06-19 03:43
> 模块: Transfer
> 维护状态: 🔄 持续维护中

## 接口概述

Transfer 模块不直接提供API接口，而是通过其他模块进行功能暴露：

**接口提供方式:**
- **用户端功能**: 通过服务层(TransferService)供客户端模块调用，不提供直接API
- **外部应用接口**: 通过OpenAPI模块进行对外开放，不直接提供API
- **管理端功能**: 通过后台控制器实现，不提供API接口

**说明:**
Transfer模块专注于核心业务逻辑实现，所有对外接口都通过其他专门的模块进行暴露和管理。

## 用户端服务层接口

Transfer 模块不提供直接的用户端API，而是通过服务层供客户端模块调用。

### TransferService 服务接口

#### 1. 创建转出订单
```php
/**
 * 创建转出订单
 * @param array $data 订单数据
 * @return TransferOrderDto|string 成功返回DTO，失败返回错误信息
 */
TransferService::createTransferOut(array $data);
```

**参数说明:**
```php
$data = [
    'user_id' => 123,               // 用户ID (必填)
    'transfer_app_id' => 1,         // 划转应用ID (必填)
    'amount' => '100.50',           // 转出金额 (必填)
    'password' => 'user_password',  // 安全密码 (必填)
    'google_code' => '123456'       // Google 2FA验证码 (可选)
];
```

**返回数据:**
```php
// 成功时返回 TransferOrderDto
$dto = new TransferOrderDto([
    'id' => 12345,
    'transfer_app_id' => 1,
    'out_order_id' => 'EXT_123456',
    'amount' => '100.50',
    'status' => 1,
    'created_at' => '2025-06-15 14:53:00'
]);

// 失败时返回错误信息字符串
$error = "余额不足";
```

#### 2. 查询订单状态
```php
/**
 * 查询订单状态
 * @param int $orderId 订单ID
 * @param int $userId 用户ID
 * @return TransferOrderDto|null
 */
TransferService::getOrderInfo(int $orderId, int $userId);
```

#### 3. 获取可用应用列表
```php
/**
 * 获取用户可用的划转应用列表
 * @param int $userId 用户ID
 * @return TransferAppDto[]
 */
TransferService::getAvailableApps(int $userId);
```

#### 4. 获取用户订单列表
```php
/**
 * 获取用户订单列表
 * @param int $userId 用户ID
 * @param array $filters 筛选条件
 * @return array
 */
TransferService::getUserOrders(int $userId, array $filters = []);
```

#### 5. 计算手续费
```php
/**
 * 计算转出手续费
 * @param int $transferAppId 划转应用ID
 * @param string $amount 金额
 * @return array
 */
TransferService::calculateOutFee(int $transferAppId, string $amount);

/**
 * 计算转入手续费
 * @param int $transferAppId 划转应用ID
 * @param string $amount 金额
 * @return array
 */
TransferService::calculateInFee(int $transferAppId, string $amount);
```

#### 6. 获取手续费配置
```php
/**
 * 获取应用的手续费配置
 * @param int $transferAppId 划转应用ID
 * @return array
 */
TransferService::getFeeConfig(int $transferAppId);
```

#### 7. 强类型参数接口
```php
/**
 * 创建转出订单 - 强类型参数
 * @param int $transferAppId 划转应用ID
 * @param int $userId 用户ID
 * @param string $amount 转出金额
 * @param string $password 安全密码
 * @param string|null $googleCode 谷歌验证码
 * @param string|null $outUserId 外部用户ID
 * @param string|null $remark 备注
 * @param array $callbackData 回调数据
 * @return TransferOrderDto|string
 */
TransferService::createTransferOut(
    int $transferAppId,
    int $userId,
    string $amount,
    string $password,
    ?string $googleCode = null,
    ?string $outUserId = null,
    ?string $remark = null,
    array $callbackData = []
);

/**
 * 创建转入订单 - 强类型参数
 * @param int $transferAppId 划转应用ID
 * @param int $userId 用户ID
 * @param string $businessId 业务订单ID
 * @param string $amount 转入金额
 * @param string|null $outUserId 外部用户ID
 * @param string|null $remark 备注
 * @param array $callbackData 回调数据
 * @return TransferOrderDto|string
 */
TransferService::createTransferIn(
    int $transferAppId,
    int $userId,
    string $businessId,
    string $amount,
    ?string $outUserId = null,
    ?string $remark = null,
    array $callbackData = []
);
```

## 外部应用接口集成

Transfer模块不直接提供外部应用API，而是通过OpenAPI模块进行对外开放。

### OpenAPI模块集成方案

#### 1. Handler注册
在OpenAPI模块中注册Transfer相关的Handler：

```php
// 在OpenAPI模块的Handlers目录下创建Transfer处理器
app/Module/OpenAPI/Handlers/Transfer/
├── TransferInHandler.php      # 转入处理器
├── TransferOutHandler.php     # 转出处理器
└── TransferQueryHandler.php   # 查询处理器
```

#### 2. 权限范围定义
在OpenAPI模块的权限系统中定义Transfer相关权限：

```php
// SCOPE_TYPE枚举中添加
case TRANSFER_IN = 'transfer:in';           // 转入权限
case TRANSFER_OUT = 'transfer:out';         // 转出权限
case TRANSFER_QUERY = 'transfer:query';     // 查询权限
```

#### 3. API接口路由
通过OpenAPI模块的路由系统暴露接口：

```php
// 转入订单创建
POST /openapi/transfer/in
Handler: TransferInHandler
Scope: transfer:in

// 转出订单创建
POST /openapi/transfer/out
Handler: TransferOutHandler
Scope: transfer:out

// 订单状态查询
GET /openapi/transfer/order/{businessId}
Handler: TransferQueryHandler
Scope: transfer:query
```

### Handler实现示例

#### TransferInHandler.php
```php
<?php

namespace App\Module\OpenAPI\Handlers\Transfer;

use App\Module\OpenAPI\Handlers\BaseHandler;
use App\Module\Transfer\Services\TransferService;
use App\Module\Transfer\Validations\TransferInValidation;

class TransferInHandler extends BaseHandler
{
    protected string $scope = 'transfer:in';

    public function handle(array $data): array
    {
        // 验证请求数据
        $validation = new TransferInValidation($data);
        $validation->validated();

        // 调用Transfer服务
        $result = TransferService::createTransferIn($data);

        if (is_string($result)) {
            return $this->error($result);
        }

        return $this->success([
            'order_id' => $result->id,
            'out_order_id' => $result->out_order_id,
            'amount' => $result->out_amount,
            'internal_amount' => $result->amount,
            'exchange_rate' => $result->exchange_rate,
            'status' => $result->status,
            'created_at' => $result->created_at
        ]);
    }
}
```

#### TransferOutHandler.php
```php
<?php

namespace App\Module\OpenAPI\Handlers\Transfer;

use App\Module\OpenAPI\Handlers\BaseHandler;
use App\Module\Transfer\Services\TransferService;
use App\Module\Transfer\Validations\TransferOutValidation;

class TransferOutHandler extends BaseHandler
{
    protected string $scope = 'transfer:out';

    public function handle(array $data): array
    {
        // 验证请求数据
        $validation = new TransferOutValidation($data);
        $validation->validated();

        // 调用Transfer服务
        $result = TransferService::createTransferOut($data);

        if (is_string($result)) {
            return $this->error($result);
        }

        return $this->success([
            'order_id' => $result->id,
            'out_order_id' => $result->out_order_id,
            'amount' => $result->amount,
            'out_amount' => $result->out_amount,
            'exchange_rate' => $result->exchange_rate,
            'status' => $result->status,
            'created_at' => $result->created_at
        ]);
    }
}
```

### 接口文档

#### 1. 创建转入订单
**接口**: `POST /openapi/transfer/in`
**权限**: `transfer:in`
**说明**: 外部应用向用户账户转入资金

**请求参数:**
```json
{
    "out_order_id": "EXT_ORDER_789",     // 外部订单ID (必填,唯一)
    "out_user_id": "EXT_USER_123",      // 外部用户ID (必填)
    "user_id": 456,                     // 内部用户ID (必填)
    "amount": "50.25",                  // 转入金额 (必填)
    "remark": "游戏充值",               // 备注信息 (可选)
    "callback_data": {                  // 回调数据 (可选)
        "game_order_id": "GAME_123",
        "item_id": 100
    }
}
```

#### 2. 创建转出订单
**接口**: `POST /openapi/transfer/out`
**权限**: `transfer:out`
**说明**: 用户向外部应用转出资金

**请求参数:**
```json
{
    "out_order_id": "EXT_ORDER_456",     // 外部订单ID (必填,唯一)
    "user_id": 123,                     // 用户ID (必填)
    "amount": "100.00",                 // 转出金额 (必填)
    "remark": "游戏提现"                // 备注信息 (可选)
}
```

#### 3. 查询订单状态
**接口**: `GET /openapi/transfer/order/{businessId}`
**权限**: `transfer:query`
**说明**: 查询订单处理状态

**响应数据:**
```json
{
    "code": 0,
    "message": "查询成功",
    "data": {
        "out_order_id": "EXT_ORDER_789",
        "status": 100,
        "status_text": "已完成",
        "amount": "50.25",
        "internal_amount": "48.00",
        "user_id": 456,
        "created_at": "2025-06-15 14:53:00",
        "completed_at": "2025-06-15 14:54:00"
    }
}
```

## 管理端功能

Transfer 模块不提供管理端API接口，管理功能通过后台控制器实现。

### 后台管理功能

#### 1. 应用配置管理 (TransferAppController)
- **应用列表**: 查看所有划转应用配置
- **应用详情**: 查看单个应用的详细配置
- **应用编辑**: 修改应用配置信息
- **应用启用/禁用**: 控制应用的启用状态

#### 2. 订单管理 (TransferOrderController)
- **订单列表**: 查看所有划转订单，支持筛选和搜索
- **订单详情**: 查看订单的详细信息和处理历史
- **订单重试**: 重新处理失败或异常的订单
- **手动补单**: 手动完成订单处理(仅限转出订单)
- **订单统计**: 查看订单统计数据和报表

#### 3. 监控和日志
- **系统监控**: 监控订单处理状态和系统健康度
- **操作日志**: 记录所有管理操作的详细日志
- **错误日志**: 查看订单处理过程中的错误信息
- **性能统计**: 查看系统性能指标和处理效率

### 后台控制器方法

#### TransferAppController
```php
// 应用列表页面
public function index()

// 应用详情页面
public function show($id)

// 应用编辑页面
public function edit($id)

// 更新应用配置
public function update(Request $request, $id)

// 启用/禁用应用
public function toggleStatus($id)
```

#### TransferOrderController
```php
// 订单列表页面
public function index()

// 订单详情页面
public function show($id)

// 重试订单处理
public function retry($id)

// 手动补单
public function manual(Request $request, $id)

// 订单统计页面
public function statistics()
```

## 状态码说明

### 订单状态 (TransferStatus)
- `1`: 已创建 (CREATED)
- `20`: 处理中 (PROCESSING)  
- `30`: 已回调 (CALLBACK)
- `100`: 已完成 (COMPLETED)
- `-1`: 失败 (FAILED)

### 订单类型 (TransferType)
- `1`: 转入 (IN)
- `2`: 转出 (OUT)

### 错误码说明
- `0`: 成功
- `1001`: 参数错误
- `1002`: 用户不存在
- `1003`: 应用不存在或未启用
- `1004`: 余额不足
- `1005`: 订单不存在
- `1006`: 订单状态错误
- `1007`: 签名验证失败
- `1008`: 权限不足
- `1009`: 系统错误

## 签名验证

### 外部应用接口签名
1. 将请求参数按key排序
2. 拼接成 key1=value1&key2=value2 格式
3. 在末尾添加 &key=APP_SECRET
4. 对整个字符串进行MD5加密
5. 将签名添加到请求头: `X-Signature: {signature}`

### 回调通知签名
1. 使用相同的签名算法
2. 外部应用验证签名确保数据完整性

## 接口限流

- 用户端接口: 每分钟最多10次请求
- 外部应用接口: 每分钟最多100次请求  
- 管理端接口: 无限制

## 注意事项

1. **金额精度**: 所有金额字段支持最多10位小数
2. **幂等性**: 外部订单ID保证操作幂等性
3. **异步处理**: 订单创建后异步处理，需轮询状态
4. **回调重试**: 回调失败时会重试3次，间隔递增
5. **数据安全**: 敏感数据传输使用HTTPS加密
6. **日志记录**: 所有接口调用都会记录详细日志
7. **农场内部模式**: 当应用配置的外部API地址为空时，系统将只在农场内部运转，不进行外部通信，订单状态直接完成

## 第三方平台接口

Transfer模块还提供了专门的第三方平台服务接口：

### TransferThirdPartyService

#### 1. 第三方转出订单
```php
/**
 * 为第三方平台创建转出订单
 * @param int $transferAppId 划转应用ID
 * @param int $userId 用户ID
 * @param string $amount 第三方金额
 * @param string $businessId 业务订单ID
 * @param string|null $remark 备注
 * @return TransferOrderDto|string
 */
TransferThirdPartyService::createTransferOutForThirdParty(
    int $transferAppId,
    int $userId,
    string $amount,
    string $businessId,
    ?string $remark = null
);
```

#### 2. 第三方转入订单
```php
/**
 * 为第三方平台创建转入订单
 * @param int $transferAppId 划转应用ID
 * @param int $userId 用户ID
 * @param string $amount 第三方金额
 * @param string $businessId 业务订单ID
 * @param string|null $remark 备注
 * @return TransferOrderDto|string
 */
TransferThirdPartyService::createTransferInForThirdParty(
    int $transferAppId,
    int $userId,
    string $amount,
    string $businessId,
    ?string $remark = null
);
```

## 相关文档

- [API使用指南](API_USAGE.md) - 详细的API使用说明和示例
- [手续费使用指南](FEE_USAGE.md) - 手续费功能的配置和使用
- [汇率概念说明](EXCHANGE_RATE_CONCEPT.md) - 汇率计算和转换规则

---

> 文档创建时间: 2025-06-15 14:53
> 最后更新时间: 2025-06-19 03:43
> 如有疑问请联系开发团队