kknongchang_2506/app/Module/Transfer/Docs

Transfer 模块设计文档

更新时间: 2025-06-19 03:43 模块路径: app/Module/Transfer/ 基于模块: TransferOld 维护状态: 🔄 持续维护中

模块概述

Transfer 模块是一个全新设计的资金划转/流转系统，用于处理用户与外部应用之间的资金转入转出操作。该模块基于TransferOld模块重新设计，采用现代化的架构模式，支持多种货币、多个外部应用的资金流转，并提供完整的订单管理、状态跟踪和自动化处理功能。

主要功能

• 资金转入(In): 从外部应用向用户账户转入资金
• 资金转出(Out): 从用户账户向外部应用转出资金
• 订单管理: 完整的订单生命周期管理
• 自动化处理: 定时任务自动处理订单和回调
• 多应用支持: 支持多个外部应用的资金流转
• 汇率转换: 支持不同汇率的资金转换，1个外部币兑换N个内部币
• 状态跟踪: 完整的订单状态流转跟踪
• 补单机制: 支持异常订单的手动补单操作
• 灵活配置: 支持根据API配置灵活处理，外部API地址为空时跳过相应步骤
• 手续费支持: 支持转入/转出手续费配置，可设置费率、最低/最高限额
• 第三方集成: 支持第三方平台的充值提现功能
• 强类型参数: 使用明确的参数接口，替代难以理解的数组参数

设计原则

• 基于TransferOld模块的成熟业务逻辑
• 采用现代化的模块架构设计
• 遵循用户偏好的代码规范和命名约定
• 参考物品模块(GameItems)的完整目录结构
• 使用枚举类型避免魔法数字
• 分离业务逻辑和数据访问层
• 完善的验证和错误处理机制
• 支持事件驱动架构和队列处理

目录结构

app/Module/Transfer/
├── AdminControllers/        # 后台管理控制器目录
│   ├── Helper/             # 后台辅助类目录
│   │   ├── TransferAppHelper.php      # 应用管理辅助类
│   │   ├── TransferOrderHelper.php    # 订单管理辅助类
│   │   ├── FilterHelper.php           # 筛选辅助类
│   │   ├── GridHelper.php             # 表格辅助类
│   │   ├── ShowHelper.php             # 详情辅助类
│   │   └── FormHelper.php             # 表单辅助类
│   ├── Tools/              # 后台工具目录
│   │   ├── RetryOrderTool.php         # 重试订单工具
│   │   ├── ManualCompleteTool.php     # 手动补单工具
│   │   └── ExportOrderTool.php        # 订单导出工具
│   ├── TransferAppController.php      # 应用管理控制器
│   └── TransferOrderController.php    # 订单管理控制器
├── Casts/                   # 模型转换器目录
│   ├── TransferAppCast.php           # 应用转换器
│   ├── TransferOrderCast.php         # 订单转换器
│   └── CallbackDataCast.php          # 回调数据转换器
├── Commands/                # 命令行工具目录
│   ├── TransferProcessCommand.php     # 订单处理命令
│   ├── TransferCallbackCommand.php   # 回调处理命令
│   ├── TransferStatsCommand.php      # 统计命令
│   └── TransferCleanCommand.php      # 数据清理命令
├── Config/                  # 配置文件目录
│   └── transfer.php        # 模块配置文件

├── Databases/               # 数据库相关目录
│   ├── GenerateSql/        # SQL生成脚本目录
│   │   ├── create_tables.sql         # 创建表SQL
│   │   ├── init_data.sql             # 初始化数据SQL
│   │   └── indexes.sql               # 索引SQL
│   └── README.md           # 数据库说明文档
├── Docs/                    # 文档目录
│   ├── README.md           # 模块设计文档
│   ├── API.md              # API接口文档
│   ├── API_USAGE.md        # API使用指南
│   ├── DATABASE.md         # 数据库设计文档
│   ├── DEV.md              # 开发进度文档
│   ├── DEPLOYMENT.md       # 部署文档
│   ├── EXCHANGE_RATE_CONCEPT.md # 汇率概念说明
│   ├── FEE_EVENT_SYSTEM.md # 手续费事件系统
│   ├── FEE_USAGE.md        # 手续费使用指南
│   └── README_AUTO.md      # 自动生成声明文档
├── Dtos/                    # 数据传输对象目录
│   ├── TransferAppDto.php            # 应用DTO
│   ├── TransferOrderDto.php          # 订单DTO
│   └── CallbackResultDto.php         # 回调结果DTO
├── Enums/                   # 枚举类目录
│   ├── TransferStatus.php            # 订单状态枚举
│   ├── TransferType.php              # 订单类型枚举
│   └── CallbackStatus.php            # 回调状态枚举
├── Events/                  # 事件目录
│   ├── TransferOrderCreated.php      # 订单创建事件
│   ├── TransferOrderCompleted.php    # 订单完成事件
│   └── TransferCallbackReceived.php  # 回调接收事件
├── Exceptions/              # 异常类目录
│   ├── TransferException.php         # 划转异常基类
│   ├── InsufficientBalanceException.php # 余额不足异常
│   └── ExternalApiException.php      # 外部API异常

├── Jobs/                    # 队列任务目录
│   ├── ProcessTransferOrderJob.php   # 处理订单任务
│   ├── SendCallbackJob.php           # 发送回调任务
│   └── RetryFailedOrderJob.php       # 重试失败订单任务
├── Listeners/               # 事件监听器目录
│   ├── TransferOrderListener.php     # 订单事件监听器
│   └── TransferCallbackListener.php  # 回调事件监听器
├── Logics/                  # 逻辑层目录
│   ├── TransferLogic.php             # 划转业务逻辑
│   ├── OrderLogic.php                # 订单处理逻辑
│   ├── CallbackLogic.php             # 回调处理逻辑
│   └── ExternalApiLogic.php          # 外部API调用逻辑
├── Models/                  # 数据模型目录
│   ├── TransferApp.php               # 划转应用模型
│   ├── TransferOrder.php             # 划转订单模型
│   └── README.md                     # 模型说明文档
├── Providers/               # 服务提供者目录
│   └── TransferServiceProvider.php   # 模块服务提供者
├── Repositories/            # 数据仓库目录
│   ├── TransferAppRepository.php     # 应用仓库
│   ├── TransferOrderRepository.php   # 订单仓库
│   └── README.md                     # 仓库说明文档
├── Routes/                  # 路由目录
│   └── admin.php           # 后台路由
├── Services/                # 服务层目录
│   ├── TransferService.php           # 对外服务接口
│   ├── ExternalApiService.php        # 外部API服务
│   └── StatisticsService.php         # 统计服务
├── Tests/                   # 测试目录
│   ├── Unit/               # 单元测试目录
│   │   ├── TransferServiceTest.php   # 服务层测试
│   │   ├── TransferLogicTest.php     # 逻辑层测试
│   │   └── TransferValidationTest.php # 验证测试
│   ├── Feature/            # 功能测试目录
│   │   ├── TransferApiTest.php       # API测试
│   │   └── TransferFlowTest.php      # 流程测试
│   └── README.md           # 测试说明文档
├── Validations/             # 验证类目录
│   ├── TransferInValidation.php      # 转入验证
│   ├── TransferOutValidation.php     # 转出验证
│   └── TransferAppValidation.php     # 应用验证
├── Validators/              # 验证器目录
│   ├── TransferAppValidator.php      # 应用验证器
│   ├── BusinessIdValidator.php       # 业务ID验证器
│   ├── TransferOpenValidator.php     # 划转开放验证器
│   ├── ExternalApiValidator.php      # 外部API验证器
│   └── AmountValidator.php           # 金额验证器
└── README.md                # 模块主文档

核心组件设计

1. 服务层 (Service)

TransferService.php - 对外提供的主要服务接口

主要方法：

• createTransferOut() - 创建转出订单（强类型参数）
• createTransferIn() - 创建转入订单（强类型参数）
• createTransferOutFromArray() - 创建转出订单（向后兼容）
• createTransferInFromArray() - 创建转入订单（向后兼容）
• getOrderInfo() - 获取订单信息
• getAppConfig() - 获取应用配置
• processCallback() - 处理回调结果
• calculateOutFee() - 计算转出手续费
• calculateInFee() - 计算转入手续费
• getFeeConfig() - 获取手续费配置
• getFeeStatistics() - 获取手续费统计

TransferThirdPartyService.php - 第三方平台服务接口

• createTransferOutForThirdParty() - 为第三方创建转出订单
• createTransferInForThirdParty() - 为第三方创建转入订单

2. 逻辑层 (Logic)

TransferLogic.php - 核心业务逻辑处理

• 订单创建逻辑
• 汇率转换计算
• 状态流转控制

OrderLogic.php - 订单处理逻辑

• 订单状态管理
• 资金操作处理
• 外部API调用

CallbackLogic.php - 回调处理逻辑

• 回调结果处理
• 订单状态更新
• 通知发送

3. 数据模型 (Model)

TransferApp.php - 划转应用配置模型

• 应用基本信息
• API配置信息
• 汇率配置
• 账户映射关系

TransferOrder.php - 划转订单模型

• 订单基本信息
• 金额信息
• 状态信息
• 关联关系

4. 枚举类型 (Enums)

TransferStatus.php - 订单状态枚举

enum TransferStatus: int
{
    case CREATED = 1;    // 已创建
    case PROCESSING = 20; // 处理中
    case CALLBACK = 30;   // 已回调
    case COMPLETED = 100; // 已完成
    case FAILED = -1;     // 失败
}

TransferType.php - 订单类型枚举

enum TransferType: int
{
    case IN = 1;   // 转入
    case OUT = 2;  // 转出
}

5. 验证系统

TransferInValidation.php - 转入验证类

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

TransferOutValidation.php - 转出验证类

• 用户身份验证
• 资金余额检查
• 应用配置验证
• 安全验证（密码、2FA）

6. OpenAPI集成

Transfer模块不直接提供API处理器，而是通过OpenAPI模块进行对外开放：

• Handler注册: 在OpenAPI模块中注册Transfer相关Handler
• 权限控制: 使用OpenAPI模块的权限系统
• 路由管理: 通过OpenAPI模块的路由系统暴露接口
• 认证授权: 使用OpenAPI模块的认证和授权机制

7. 队列任务 (Jobs)

ProcessTransferOrderJob.php - 订单处理任务

• 处理待处理的转入转出订单
• 执行资金操作和外部API调用
• 更新订单状态

SendCallbackJob.php - 回调发送任务

• 发送回调通知到外部应用
• 处理回调响应
• 支持重试机制

RetryFailedOrderJob.php - 重试失败订单任务

• 重新处理失败的订单
• 智能重试策略
• 错误日志记录

8. 事件系统 (Events & Listeners)

TransferOrderCreated.php - 订单创建事件

• 订单创建时触发
• 通知相关系统

TransferOrderCompleted.php - 订单完成事件

• 订单完成时触发
• 更新统计数据

TransferCallbackReceived.php - 回调接收事件

• 接收到外部回调时触发
• 处理回调数据

9. 异常处理 (Exceptions)

TransferException.php - 划转异常基类

• 所有划转相关异常的基类
• 统一异常处理机制

InsufficientBalanceException.php - 余额不足异常

• 用户余额不足时抛出
• 提供详细错误信息

ExternalApiException.php - 外部API异常

• 外部API调用失败时抛出
• 包含API响应详情

数据库设计

transfer_apps 表 - 划转应用配置

CREATE TABLE `kku_transfer_apps` (
  `id` int unsigned NOT NULL AUTO_INCREMENT,
  `keyname` varchar(50) NOT NULL COMMENT '应用标识',
  `title` varchar(100) NOT NULL COMMENT '应用名称',
  `description` text COMMENT '应用描述',
  `out_id2` int DEFAULT NULL COMMENT '开放接口ID',
  `out_id3` int DEFAULT NULL COMMENT '三方平台ID',
  `currency_id` int NOT NULL COMMENT '货币类型',
  `fund_id` int NOT NULL COMMENT '资金账户类型',
  `fund_to_uid` int DEFAULT NULL COMMENT '转入目标账户UID(转出时必须)',
  `fund_in_uid` int DEFAULT NULL COMMENT '转入来源账户UID(转入时必须)',
  `exchange_rate` decimal(10,4) NOT NULL DEFAULT '1.0000' COMMENT '汇率(1个外部币能兑换多少内部币)',
  `fee_in_rate` decimal(5,4) DEFAULT '0.0000' COMMENT '转入手续费率(0.0000-1.0000)',
  `fee_out_rate` decimal(5,4) DEFAULT '0.0000' COMMENT '转出手续费率(0.0000-1.0000)',
  `fee_in_min` decimal(15,4) DEFAULT '0.0000' COMMENT '转入最低手续费',
  `fee_in_max` decimal(15,4) DEFAULT '0.0000' COMMENT '转入最高手续费(0为不限制)',
  `fee_out_min` decimal(15,4) DEFAULT '0.0000' COMMENT '转出最低手续费',
  `fee_out_max` decimal(15,4) DEFAULT '0.0000' COMMENT '转出最高手续费(0为不限制)',
  `fee_account_uid` int DEFAULT '1' COMMENT '手续费收取账户UID',
  `transfer_in_enabled` tinyint(1) DEFAULT '1' COMMENT '是否允许转入',
  `transfer_out_enabled` tinyint(1) DEFAULT '1' COMMENT '是否允许转出',
  `order_callback_url` varchar(255) DEFAULT NULL COMMENT '结果通知API地址(为空则不通知)',
  `order_in_info_url` varchar(255) DEFAULT NULL COMMENT '转入查询API(为空则不查询)',
  `order_out_create_url` varchar(255) DEFAULT NULL COMMENT '转出创建API(为空则不创建)',
  `order_out_info_url` varchar(255) DEFAULT NULL COMMENT '转出查询API(为空则不查询)',
  `is_enabled` tinyint(1) NOT NULL DEFAULT '1' COMMENT '是否启用',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  `deleted_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `keyname` (`keyname`),
  KEY `out_id2` (`out_id2`),
  KEY `currency_id` (`currency_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='划转应用配置表';

transfer_orders 表 - 划转订单

CREATE TABLE `kku_transfer_orders` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `transfer_app_id` int unsigned NOT NULL COMMENT '划转应用ID',
  `out_id` int NOT NULL COMMENT '外部应用ID',
  `out_order_id` varchar(100) NOT NULL COMMENT '外部订单ID',
  `out_user_id` varchar(50) DEFAULT NULL COMMENT '外部用户ID',
  `user_id` int unsigned NOT NULL COMMENT '内部用户ID',
  `currency_id` int NOT NULL COMMENT '货币类型',
  `fund_id` int NOT NULL COMMENT '资金账户类型',
  `type` tinyint NOT NULL COMMENT '类型(1=转入,2=转出)',
  `status` tinyint NOT NULL DEFAULT '1' COMMENT '状态',
  `out_amount` decimal(30,10) NOT NULL COMMENT '外部金额',
  `amount` decimal(30,10) NOT NULL COMMENT '内部金额',
  `exchange_rate` decimal(10,4) NOT NULL COMMENT '使用汇率(1外部币=N内部币)',
  `fee_rate` decimal(5,4) DEFAULT '0.0000' COMMENT '手续费率',
  `fee_amount` decimal(15,4) DEFAULT '0.0000' COMMENT '手续费金额',
  `actual_amount` decimal(15,4) DEFAULT '0.0000' COMMENT '实际到账金额',
  `callback_data` json DEFAULT NULL COMMENT '回调数据',
  `error_message` text COMMENT '错误信息',
  `remark` varchar(255) DEFAULT NULL COMMENT '备注信息',
  `processed_at` timestamp NULL DEFAULT NULL COMMENT '处理时间',
  `callback_at` timestamp NULL DEFAULT NULL COMMENT '回调时间',
  `completed_at` timestamp NULL DEFAULT NULL COMMENT '完成时间',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  `deleted_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `out_order_unique` (`out_id`, `out_order_id`),
  KEY `transfer_app_id` (`transfer_app_id`),
  KEY `user_id` (`user_id`),
  KEY `status` (`status`),
  KEY `type` (`type`),
  KEY `created_at` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='划转订单表';

业务流程设计

处理模式说明

系统根据应用配置中的API地址字段来决定处理方式：

• 外部API处理: 当配置了相应的外部API地址时，调用外部API进行处理
• 本地处理: 当外部API地址为空时，跳过外部API调用步骤
• 回调处理: 当配置了回调URL时，发送回调通知；否则跳过回调步骤
• 状态管理: 根据是否需要外部处理来决定订单的最终状态
• 适用场景: 支持完全外部对接、部分外部对接、纯本地处理等多种场景

转出流程 (用户 → 外部应用)

1. 用户发起转出请求 → TransferOutHandler
2. 验证用户信息和余额 → TransferOutValidation
3. 创建转出订单 → TransferLogic
4. 验证fund_to_uid并进行用户间资金转移 → Fund模块
5. 判断外部API配置 → OrderLogic
   • 如果order_out_create_url不为空：调用外部API创建订单
   • 如果order_out_create_url为空：跳过外部调用，直接完成
6. 更新订单状态 → TransferOrder
   • 配置了外部API：状态更新为PROCESSING
   • 未配置外部API：状态直接更新为COMPLETED
7. 后续处理 (仅当配置了外部API时)
   • 定时查询外部订单状态 → TransferOutTask
   • 处理回调结果 → CallbackLogic
   • 更新最终状态 → TransferOrder

转入流程 (外部应用 → 用户)

1. 外部应用发起转入请求 → TransferInHandler
2. 验证外部应用和参数 → TransferInValidation
3. 创建转入订单 → TransferLogic
4. 验证fund_in_uid并从指定账户转账到用户 → Fund模块
5. 判断回调配置 → CallbackLogic
   • 如果order_callback_url不为空：发送回调通知
   • 如果order_callback_url为空：跳过回调，直接完成
6. 更新订单状态 → TransferOrder
   • 配置了回调URL：状态更新为PROCESSING，等待回调响应
   • 未配置回调URL：状态直接更新为COMPLETED
7. 后续处理 (仅当配置了回调URL时)
   • 处理回调响应 → TransferCallbackTask
   • 更新最终状态 → TransferOrder

接口设计

用户端功能

• 服务层调用: 通过 TransferService 供客户端模块调用
• 主要方法: createTransferOut(), getOrderInfo(), getAvailableApps()
• 返回格式: DTO对象或错误信息字符串

外部应用接口

• 集成方式: 通过OpenAPI模块进行对外开放
• Handler注册: 在OpenAPI模块中注册Transfer相关Handler
• 权限控制: 使用OpenAPI模块的权限系统进行访问控制
• 主要接口:
  • POST /openapi/transfer/in - 创建转入订单
  • POST /openapi/transfer/out - 创建转出订单
  • GET /openapi/transfer/order/{businessId} - 查询订单状态

管理端功能

• 后台控制器: TransferAppController, TransferOrderController
• 主要功能: 应用配置管理、订单管理、监控统计
• 访问方式: 后台管理界面，无API接口

开发计划

第一阶段：基础架构

• 创建目录结构
• 定义枚举类型
• 创建数据模型
• 设计数据库表

第二阶段：核心功能

• 实现服务层接口
• 开发业务逻辑层
• 创建验证系统
• 实现处理器

第三阶段：自动化处理

• 开发自动化任务
• 实现回调机制
• 添加补单功能
• 完善错误处理

第四阶段：管理功能

• 创建后台控制器
• 实现数据仓库
• 添加管理界面
• 完善监控功能

第五阶段：测试和优化

• 编写单元测试
• 集成测试
• 性能优化
• 文档完善

---

📚 相关文档

• API使用指南 - 详细的API使用说明和示例
• 手续费使用指南 - 手续费功能的配置和使用
• 汇率概念说明 - 汇率计算和转换规则
• 数据库设计文档 - 完整的数据库表结构设计
• 开发进度文档 - 模块开发进度和计划

---

文档创建时间: 2025-06-15 14:53 最后更新时间: 2025-06-19 03:43 基于模块: TransferOld 设计原则: 现代化架构 + 业务逻辑继承 维护状态: 🔄 持续维护中