kknongchang_2506/app/Module/Transfer/Docs/DEV.md

Transfer 模块开发进度

更新时间: 2025-06-15 14:53
模块: Transfer
基于: TransferOld

开发概述

Transfer 模块是基于 TransferOld 模块重新设计的现代化资金划转系统。采用分层架构设计，遵循用户偏好的代码规范，提供完整的资金转入转出功能。

开发阶段规划

🔄 第一阶段：基础架构搭建

目标: 建立模块基础架构和核心组件
预计工期: 2天

任务清单

• [ ] 目录结构创建

  • 创建完整的目录结构(参考物品模块)
  • AdminControllers/ - 后台管理控制器和辅助类
  • Casts/ - 模型转换器
  • Commands/ - 命令行工具

  • [ ] Config/ - 配置文件

  • [ ] Databases/ - 数据库相关文件

  • [ ] Dtos/ - 数据传输对象

  • [ ] Enums/ - 枚举类

  • [ ] Events/ - 事件类

  • [ ] Exceptions/ - 异常类

  • [ ] Jobs/ - 队列任务

  • [ ] Listeners/ - 事件监听器

  • [ ] Logics/ - 逻辑层

  • [ ] Models/ - 数据模型

  • [ ] Providers/ - 服务提供者

  • [ ] Repositories/ - 数据仓库

  • [ ] Routes/ - 路由文件

  • [ ] Services/ - 服务层

  • [ ] Tests/ - 测试文件

  • [ ] Validations/ - 验证类

  • [ ] Validators/ - 验证器

  • [ ] 添加各目录的 README.md 说明文件

  • [ ] 设置命名空间和自动加载

• [ ] 枚举类型定义

  • TransferStatus.php - 订单状态枚举
  • TransferType.php - 订单类型枚举
  • 遵循 PSR-4 命名标准
  • 使用 PHP enum 语法

• [ ] 数据模型创建

  • TransferApp.php - 划转应用模型
  • TransferOrder.php - 划转订单模型
  • 继承自 \UCore\ModelCore
  • 添加 field start/end 注释块
  • 定义模型关联关系

• [ ] 数据库表设计

  • 创建 kku_transfer_apps 表
  • 创建 kku_transfer_orders 表
  • 设置索引和外键约束
  • 初始化示例数据

完成标准

• 所有基础文件创建完成
• 数据库表结构正确
• 模型类可正常使用
• 枚举类型定义完整

---

🔄 第二阶段：核心业务逻辑

目标: 实现核心业务逻辑和服务层
预计工期: 3天

任务清单

• [ ] 服务层实现

  • TransferService.php - 对外服务接口
  • ExternalApiService.php - 外部API服务
  • StatisticsService.php - 统计服务
  • 提供静态方法供其他模块调用
  • 返回 DTO 对象而非 Model
  • 实现模块间交互接口

• [ ] 逻辑层开发

  • TransferLogic.php - 核心业务逻辑
  • OrderLogic.php - 订单处理逻辑
  • CallbackLogic.php - 回调处理逻辑
  • ExternalApiLogic.php - 外部API调用逻辑
  • 不在逻辑层开启事务
  • 使用 Fund 模块进行资金操作

• [ ] DTO 对象创建

  • TransferAppDto.php - 应用数据传输对象
  • TransferOrderDto.php - 订单数据传输对象
  • CallbackResultDto.php - 回调结果DTO
  • 定义完整的属性和类型

• [ ] Cast 转换器

  • TransferAppCast.php - 应用转换器
  • TransferOrderCast.php - 订单转换器
  • CallbackDataCast.php - 回调数据转换器
  • 独立的 Cast 类，不共用

• [ ] 事件和监听器

  • TransferOrderCreated.php - 订单创建事件
  • TransferOrderCompleted.php - 订单完成事件
  • TransferCallbackReceived.php - 回调接收事件
  • TransferOrderListener.php - 订单事件监听器
  • TransferCallbackListener.php - 回调事件监听器

• [ ] 异常类创建

  • TransferException.php - 划转异常基类
  • InsufficientBalanceException.php - 余额不足异常
  • ExternalApiException.php - 外部API异常

完成标准

• 服务层接口完整
• 业务逻辑正确实现
• DTO 对象定义完整
• Cast 转换器正常工作

---

🔄 第三阶段：验证和处理器

目标: 实现验证系统和请求处理器
预计工期: 3天

任务清单

• [ ] 验证类开发

  • TransferInValidation.php - 转入验证
  • TransferOutValidation.php - 转出验证
  • 参考 GodActivationValidation 模式
  • 禁止动态属性赋值

• [ ] 验证器实现

  • TransferAppValidator.php - 应用验证器
  • BusinessIdValidator.php - 业务ID验证器
  • TransferOpenValidator.php - 划转开放验证器
  • 使用 addError 方法处理错误
  • 字段Key使用 $arg 参数传入

• [ ] OpenAPI模块集成

  • 在OpenAPI模块中创建Transfer相关Handler
  • TransferInHandler.php - 转入处理器
  • TransferOutHandler.php - 转出处理器
  • TransferQueryHandler.php - 查询处理器
  • 在SCOPE_TYPE枚举中添加Transfer权限
  • 注册Handler到OpenAPI路由系统
  • 配置权限和认证机制

完成标准

• 验证系统完整
• 处理器逻辑正确
• 错误处理完善
• 响应格式统一

---

🔄 第四阶段：自动化任务

目标: 实现自动化处理和定时任务
预计工期: 2天

任务清单

• [ ] 队列任务开发

  • ProcessTransferOrderJob.php - 处理订单任务
  • SendCallbackJob.php - 发送回调任务
  • RetryFailedOrderJob.php - 重试失败订单任务
  • 实现队列任务支持

• [ ] 命令行工具

  • TransferProcessCommand.php - 订单处理命令
  • TransferCallbackCommand.php - 回调处理命令
  • TransferStatsCommand.php - 统计命令
  • TransferCleanCommand.php - 数据清理命令

• [ ] 定时任务配置

  • 创建 Console Command
  • 配置任务调度
  • 设置执行频率
  • 添加错误处理

• [ ] 回调机制

  • 实现回调发送
  • 处理回调响应
  • 支持重试机制
  • 记录回调日志

完成标准

• 自动化任务正常运行
• 定时任务配置正确
• 回调机制完善
• 错误处理完整

---

🔄 第五阶段：后台管理

目标: 实现后台管理功能
预计工期: 2天

任务清单

• [ ] 数据仓库层

  • TransferAppRepository.php - 应用仓库
  • TransferOrderRepository.php - 订单仓库
  • 参考 Fund 模块 Repository 实现
  • 仅供后台控制器使用

• [ ] 后台控制器

  • TransferAppController.php - 应用管理
  • TransferOrderController.php - 订单管理
  • 继承自 UCore\DcatAdmin\AdminController
  • 使用 Grid/Show/Form 的 make 方法
  • 使用 Helper 辅助类
  • 不提供API接口，仅后台管理界面

• [ ] 后台辅助类

  • TransferAppHelper.php - 应用管理辅助类
  • TransferOrderHelper.php - 订单管理辅助类
  • FilterHelper.php - 筛选辅助类
  • GridHelper.php - 表格辅助类
  • ShowHelper.php - 详情辅助类
  • FormHelper.php - 表单辅助类

• [ ] 后台工具

  • RetryOrderTool.php - 重试订单工具
  • ManualCompleteTool.php - 手动补单工具
  • ExportOrderTool.php - 订单导出工具

• [ ] 后台界面

  • 应用配置管理界面
  • 订单列表和详情界面
  • 订单重试和补单功能
  • 监控统计界面
  • 添加路由注释
  • 加入后台菜单

• [ ] 路由配置

  • admin.php - 后台路由
  • OpenAPI模块中配置外部API路由

完成标准

• 后台管理界面完整
• 数据操作正常
• 权限控制正确
• 菜单配置完成

---

🔄 第六阶段：测试和优化

目标: 完善测试和性能优化
预计工期: 2天

任务清单

• [ ] 单元测试

  • TransferServiceTest.php - 服务层测试
  • TransferLogicTest.php - 逻辑层测试
  • TransferValidationTest.php - 验证测试
  • 使用 phpunit 运行测试

• [ ] 功能测试

  • TransferApiTest.php - API测试
  • TransferFlowTest.php - 流程测试
  • 测试完整业务流程
  • 测试异常情况处理
  • 测试并发场景
  • 验证数据一致性

• [ ] 配置和服务提供者

  • transfer.php - 模块配置文件
  • TransferServiceProvider.php - 服务提供者
  • 注册服务绑定和事件监听

• [ ] 性能优化

  • 数据库查询优化
  • 缓存策略实现
  • 批量操作优化
  • 内存使用优化

• [ ] 文档完善

  • 更新 API 文档
  • 完善使用说明
  • 添加故障排除指南
  • 更新开发进度

完成标准

• 测试覆盖率达标
• 性能指标合格
• 文档内容完整
• 代码质量达标

---

技术要求

代码规范

• 使用中文注释
• 遵循 PSR-4 命名标准
• 避免魔法数字，使用枚举
• 类名以功能结尾 (Validator, Repository)
• 功能拆分为独立简单静态类

架构设计

• 模型继承自 \UCore\ModelCore
• 服务层返回 DTO 对象
• 逻辑层不开启事务
• 模块间通过 Service 层交互
• 使用独立的 Cast 类

数据库设计

• 表前缀 kkutransfer
• 使用 DECIMAL(30,10) 存储金额
• 不使用迁移类，直接提供 SQL
• 设置合适的索引和约束

风险评估

高风险项

• 资金安全: 涉及资金操作，需确保事务完整性
• 数据一致性: 多表操作需保证数据一致
• 外部API: 依赖外部接口，需处理网络异常

中风险项

• 性能问题: 大量订单处理可能影响性能
• 并发处理: 同时处理多个订单需考虑锁机制
• 回调重试: 回调失败重试机制需完善

低风险项

• 界面展示: 后台管理界面相对简单
• 日志记录: 标准的日志记录功能
• 配置管理: 应用配置管理功能

质量标准

代码质量

• 代码覆盖率 > 80%
• 无严重安全漏洞
• 符合 PSR 标准
• 通过静态分析

性能指标

• 订单创建响应时间 < 500ms
• 查询接口响应时间 < 200ms
• 支持并发处理 > 100 TPS
• 内存使用 < 128MB

功能完整性

• 所有 API 接口正常
• 业务流程完整
• 异常处理完善
• 日志记录完整

---

当前状态

阶段: 📋 设计阶段
进度: 0% (0/6 阶段完成)
状态: 设计文档已完成，等待开发启动

已完成项目

• 需求分析和设计
• 技术方案确定
• 文档结构设计
• 数据库表设计
• API 接口设计

下一步计划

1. 创建目录结构
2. 定义枚举类型
3. 创建数据模型
4. 建立数据库表

---

文档更新时间: 2025-06-15 14:53
负责人: AI Assistant
预计完成时间: 2025-06-29