kknongchang_2506/app/Module/TransferOld

Transfer 模块 - 划转/流转系统

更新时间: 2025-06-15 模块路径: app/Module/Transfer/

模块概述

Transfer 模块是一个完整的资金划转/流转系统，主要用于处理用户与外部应用之间的资金转入转出操作。该模块支持多种货币、多个外部应用的资金流转，并提供完整的订单管理、状态跟踪和自动化处理功能。

主要功能

• 资金转入(In): 从外部应用向用户账户转入资金
• 资金转出(Out): 从用户账户向外部应用转出资金
• 订单管理: 完整的订单生命周期管理
• 自动化处理: 定时任务自动处理订单和回调
• 多应用支持: 支持多个外部应用的资金流转
• 汇率转换: 支持不同汇率的资金转换

目录结构

app/Module/Transfer/
├── App.php                 # 应用配置管理类
├── AutoCall.php           # 转入自动处理类
├── AutoCallOut.php        # 转出自动处理类
├── Info.php               # 订单信息处理类
├── OutBudan.php           # 转出补单处理类
├── Docs/                  # 文档目录
├── Entity/                # 实体类目录
├── Enums/                 # 枚举类目录
│   ├── TStatus.php        # 订单状态枚举
│   └── TType.php          # 订单类型枚举
├── Model/                 # 数据模型目录
│   ├── TransferApp.php    # 划转应用模型
│   └── TransferOrder.php  # 划转订单模型
├── Repository/            # 数据仓库目录
│   ├── App.php            # 应用仓库
│   └── Order.php          # 订单仓库
├── Validation/            # 验证类目录
│   ├── INCreate.php       # 转入创建验证
│   └── OutCreate.php      # 转出创建验证
└── Validator/             # 验证器目录
    ├── BusinessId.php     # 业务ID验证器
    ├── OutApp.php         # 外部应用验证器
    ├── TrApp.php          # 划转应用验证器
    └── TrOpen.php         # 划转开放验证器

核心类说明

1. App.php - 应用配置管理

负责管理划转应用的配置信息获取。

class App
{
    // 根据ID获取划转配置信息
    static public function get($trapp_id):TransferApp

    // 根据外部ID获取配置
    static public function getByOid2($id):TransferApp
}

2. AutoCall.php - 转入自动处理

处理转入订单的自动化流程，包括订单处理和回调。

class AutoCall
{
    // 转入订单处理
    static public function in_call()

    // 转入回调处理
    static public function in_callback()

    // 具体的转入处理逻辑
    static private function in_call2(TransferOrder $order)
}

3. AutoCallOut.php - 转出自动处理

处理转出订单的自动化流程。

class AutoCallOut
{
    // 转出订单处理
    static public function out_call()

    // 具体的转出处理逻辑
    static private function out_call2(TransferOrder $order)
}

4. Info.php - 订单信息处理

提供订单信息的格式化输出。

class Info
{
    // 格式化订单信息输出
    public function order_info(TransferOrder $order)
}

5. OutBudan.php - 转出补单处理

处理转出订单的补单操作。

class OutBudan
{
    // 执行转出补单操作
    static public function run(TransferOrder $order, bool $validation)
}

数据模型

TransferApp - 划转应用配置

存储外部应用的划转配置信息。

/**
 * 划转APP配置模型
 * @property int $id
 * @property string $keyname 标识
 * @property string $title 应用名字
 * @property int $out_id 对应外部APP
 * @property int $crrency_id 对应货币
 * @property int $fund_id 对应账户
 * @property int $rate 比例 钱包:业务
 */
class TransferApp extends ModelCore

主要字段说明:

• keyname: 应用标识符
• title: 应用显示名称
• out_id: 关联的外部应用ID
• crrency_id: 使用的货币类型
• fund_id: 关联的资金账户
• rate: 汇率比例(钱包金额:业务金额)
• order_callback: 结果通知API地址
• order_in_info: 转入交易查询API
• order_out_create: 转出订单创建API
• order_out_info: 转出交易查询API

TransferOrder - 划转订单

存储具体的划转订单信息。

/**
 * 划转订单模型
 * @property int $id
 * @property int $trapp_id 划转app_id
 * @property string $out_order_id 外部订单ID
 * @property int $user_id 用户ID
 * @property int $status 状态
 * @property int $type 类型,方向
 * @property float $oamount 外部金额
 * @property int $amount 内部金额
 */
class TransferOrder extends ModelCore

主要字段说明:

• trapp_id: 关联的划转应用ID
• out_order_id: 外部系统的订单ID
• ouser_id: 外部系统的用户ID
• user_id: 内部系统的用户ID
• status: 订单状态(使用TStatus枚举)
• type: 订单类型(使用TType枚举)
• oamount: 外部系统金额
• amount: 内部系统金额(经过汇率转换)

枚举类型

TStatus - 订单状态

定义订单的各种状态。

enum TStatus: int
{
    case CREATED = 1;    // 创建
    case CALL = 20;      // 已处理,等待回调
    case CALLBACK = 30;  // 回调成功
    case END = 100;      // 已完成
}

状态流转:

1. CREATED → CALL → CALLBACK → END

TType - 订单类型

定义订单的转账方向。

enum TType: int
{
    case In = 1;   // 转入
    case Out = 2;  // 转出
}

业务流程

转出流程 (Out)

用户从内部账户向外部应用转出资金的完整流程。

sequenceDiagram
    participant User as 用户
    participant App as 应用端
    participant Transfer as Transfer模块
    participant Fund as 资金系统
    participant External as 外部应用

    User->>App: 发起转出请求
    App->>Transfer: 创建转出订单
    Transfer->>Transfer: 验证用户信息
    Transfer->>Fund: 扣除用户资金
    Transfer->>Transfer: 订单状态: CREATED
    Transfer->>External: 调用外部API创建订单
    External-->>Transfer: 返回外部订单ID
    Transfer->>Transfer: 订单状态: CALL
    Transfer->>External: 查询订单状态
    External-->>Transfer: 返回处理结果
    Transfer->>Transfer: 订单状态: CALLBACK
    Transfer->>User: 通知转出完成

详细步骤:

1. 订单创建: 用户发起转出请求，系统创建TransferOrder
2. 资金扣除: 从用户账户扣除相应金额
3. 外部下单: 调用外部应用API创建转出订单
4. 状态更新: 订单状态从CREATED更新为CALL
5. 结果查询: 定时查询外部订单处理结果
6. 完成处理: 订单状态更新为CALLBACK/END

转入流程 (In)

从外部应用向用户内部账户转入资金的完整流程。

sequenceDiagram
    participant External as 外部应用
    participant Transfer as Transfer模块
    participant Fund as 资金系统
    participant User as 用户

    External->>Transfer: 发起转入请求
    Transfer->>Transfer: 验证外部应用
    Transfer->>Transfer: 创建转入订单(CREATED)
    Transfer->>Fund: 向用户账户转入资金
    Transfer->>Transfer: 订单状态: CALL
    Transfer->>External: 回调通知处理结果
    External-->>Transfer: 确认收到回调
    Transfer->>Transfer: 订单状态: CALLBACK
    Transfer->>User: 通知转入完成

详细步骤:

1. 外部请求: 外部应用发起转入请求
2. 订单创建: 系统创建TransferOrder，状态为CREATED
3. 资金转入: 向用户账户增加相应金额
4. 状态更新: 订单状态更新为CALL
5. 回调通知: 向外部应用发送处理结果
6. 完成处理: 订单状态更新为CALLBACK/END

API接口

用户端接口

POST /transfer/create - 创建转出订单

用户发起资金转出请求。

#[Post('/create')]
public function create(Request $request)
{
    $se = \App\Module\App\Transfer::newBySession();
    $res = $se->create($request->post());
    return $this->resData($res);
}

请求参数:

• trapp_id: 划转应用ID
• amount: 转出金额
• 其他验证参数(密码、2FA等)

响应数据:

{
    "code": 0,
    "data": {
        "id": 123  // 订单ID
    }
}

外部应用接口

POST /oapi/transfer/in_create - 创建转入订单

外部应用发起资金转入请求。

public function in_create($data)
{
    $data['out_id'] = $this->out_id;
    $validation = new INCreate($data);
    $validation->validated();
    // 创建转入订单...
}

请求参数:

• business_id: 外部订单ID
• ouser_id: 外部用户ID
• money: 转入金额
• 其他验证参数

自动化处理

定时任务

系统通过定时任务自动处理订单和回调。

/**
 * 流转系统 - 自动处理,每分钟自动执行
 */
class TransferCall extends Command
{
    public function handleRun()
    {
        // 处理转入订单
        AutoCall::in_call();
        // 转入回调处理
        AutoCall::in_callback();
        // 处理转出订单
        AutoCallOut::out_call();
    }
}

执行频率: 每分钟执行一次

处理内容:

1. 转入处理: 处理状态为CREATED的转入订单
2. 转入回调: 处理状态为CALL的转入订单回调
3. 转出处理: 处理状态为CREATED的转出订单

队列任务

使用Laravel队列处理异步任务。

主要队列任务:

• TransferOrderInCall: 转入订单处理
• TransferOrderInCallback: 转入订单回调
• TransferOrderOutCallback: 转出订单回调

补单机制

支持手动补单操作，用于处理异常订单。

public function budan($data, $validation = true)
{
    $id = $data['id'];
    $model = TransferOrder::find($id);
    if ($model->type != TType::Out) {
        return "补单类型错误,出金可以补单";
    }
    return OutBudan::run($model, $validation);
}

验证和校验

验证类 (Validation)

OutCreate - 转出创建验证

验证用户转出请求的合法性。

class OutCreate extends ValidationCore
{
    // 验证用户绑定、资金余额、应用配置等
    // 包含密码验证、2FA验证等安全检查
}

验证项目:

• 用户身份验证
• 资金余额检查
• 划转应用配置验证
• 安全密码验证
• Google 2FA验证

INCreate - 转入创建验证

验证外部应用转入请求的合法性。

class INCreate extends ValidationCore
{
    // 验证外部应用、业务ID、用户信息等
}

验证项目:

• 外部应用合法性
• 业务ID唯一性
• 用户信息验证
• 金额格式验证

验证器 (Validator)

TrApp - 划转应用验证器

验证划转应用配置的有效性。

class TrApp extends Validator
{
    public function validate(mixed $value, array $data): bool
    {
        $app = TransferApp::query()->where('id', $value)->first();
        if($app){
            $this->validationSet($field,$app);
            return true;
        }
        return false;
    }
}

BusinessId - 业务ID验证器

验证外部业务ID的唯一性。

OutApp - 外部应用验证器

验证外部应用的合法性和权限。

使用示例

1. 用户转出资金

// 用户端调用
$transfer = new \App\Module\App\Transfer();
$transfer->setUserId($userId);

$result = $transfer->create([
    'trapp_id' => 1,        // 划转应用ID
    'amount' => 100.00,     // 转出金额
    'password' => 'xxx',    // 安全密码
    'google_code' => '123456' // 2FA验证码
]);

if (is_array($result)) {
    echo "转出成功，订单ID: " . $result['id'];
} else {
    echo "转出失败: " . $result;
}

2. 外部应用转入资金

// 外部应用调用
$transfer = new \App\Module\AppOapi\Transfer();
$transfer->setOutId($outId);

$result = $transfer->in_create([
    'business_id' => 'EXT_ORDER_123', // 外部订单ID
    'ouser_id' => 'EXT_USER_456',     // 外部用户ID
    'money' => 50.00,                 // 转入金额
    'user_id' => 789                  // 内部用户ID
]);

3. 管理员补单操作

// 管理员补单
$admin = new \App\Module\AppAdmin\Transfer();
$result = $admin->budan([
    'id' => 123  // 订单ID
], true);  // 是否验证

echo $result; // 返回处理结果

注意事项

1. 资金安全: 所有资金操作都使用数据库事务，确保数据一致性
2. 状态管理: 订单状态严格按照流程流转，避免状态混乱
3. 汇率处理: 内外部金额通过配置的汇率进行转换
4. 异常处理: 完善的异常处理和日志记录机制
5. 幂等性: 外部订单ID保证操作的幂等性
6. 定时处理: 依赖定时任务进行自动化处理，需确保任务正常运行

相关模块

• Fund模块: 资金账户管理
• User模块: 用户信息管理
• Outside模块: 外部应用管理
• Admin模块: 管理员功能

---

文档最后更新: 2025-06-15 如有疑问请联系开发团队