# 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** - 订单状态枚举 ```php enum TransferStatus: int { case CREATED = 1; // 已创建 case PROCESSING = 20; // 处理中 case CALLBACK = 30; // 已回调 case COMPLETED = 100; // 已完成 case FAILED = -1; // 失败 } ``` **TransferType.php** - 订单类型枚举 ```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 表 - 划转应用配置 ```sql 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 表 - 划转订单 ```sql 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_USAGE.md) - 详细的API使用说明和示例 - [手续费使用指南](FEE_USAGE.md) - 手续费功能的配置和使用 - [汇率概念说明](EXCHANGE_RATE_CONCEPT.md) - 汇率计算和转换规则 - [数据库设计文档](DATABASE.md) - 完整的数据库表结构设计 - [开发进度文档](DEV.md) - 模块开发进度和计划 --- > 文档创建时间: 2025-06-15 14:53 > 最后更新时间: 2025-06-19 03:43 > 基于模块: TransferOld > 设计原则: 现代化架构 + 业务逻辑继承 > 维护状态: 🔄 持续维护中