Transfer 模块 API 接口文档

更新时间: 2025-06-15
模块: Transfer

接口概述

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

接口提供方式:

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

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

用户端服务层接口

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

TransferService 服务接口

1. 创建转出订单

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

参数说明:

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

返回数据:

// 成功时返回 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. 查询订单状态

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

3. 获取可用应用列表

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

4. 获取用户订单列表

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

外部应用接口集成

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

OpenAPI模块集成方案

1. Handler注册

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

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

2. 权限范围定义

在OpenAPI模块的权限系统中定义Transfer相关权限：

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

3. API接口路由

通过OpenAPI模块的路由系统暴露接口：

// 转入订单创建
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

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,
            'business_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

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,
            'business_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 说明: 外部应用向用户账户转入资金

请求参数:

{
    "business_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 说明: 用户向外部应用转出资金

请求参数:

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

3. 查询订单状态

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

响应数据:

{
    "code": 0,
    "message": "查询成功",
    "data": {
        "business_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

// 应用列表页面
public function index()

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

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

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

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

TransferOrderController

// 订单列表页面
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: 系统错误

签名验证

外部应用接口签名

将请求参数按key排序
拼接成 key1=value1&key2=value2 格式
在末尾添加 &key=APP_SECRET
对整个字符串进行MD5加密
将签名添加到请求头: X-Signature: {signature}

回调通知签名

使用相同的签名算法
外部应用验证签名确保数据完整性

接口限流

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

注意事项

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

文档更新时间: 2025-06-15 14:53
如有疑问请联系开发团队

API.md 10 KB Istoric Crud