Transfer模块手续费功能开发

任务时间: 2025-06-18 20:27
任务类型: 功能开发
状态: ✅ 已完成

任务概述

为 Transfer 模块增加手续费功能，支持转入/转出订单的手续费配置、计算和收取。实现了可配置的手续费率、最低/最高手续费限制，以及手续费统计功能。

功能特性

1. 手续费配置

转入手续费率: 可配置0-100%的手续费率
转出手续费率: 可配置0-100%的手续费率
最低手续费: 设置最低手续费金额
最高手续费: 设置最高手续费金额（0为不限制）
手续费账户: 指定手续费收取的账户UID

2. 手续费计算

智能计算: 按比例计算，应用最低/最高限制
精确计算: 使用bcmath确保4位小数精度
实时计算: 创建订单时自动计算手续费
透明显示: 清晰显示原金额、手续费、实际到账金额

3. 资金处理

转出订单: 从用户账户扣除全额，分别转入目标账户和手续费账户
转入订单: 从来源账户扣除全额，用户收到扣除手续费后的实际金额
安全处理: 手续费收取失败时记录日志但不影响主要业务

4. 统计功能

手续费统计: 按应用、时间范围统计手续费收入
收入分析: 提供日报、月报等统计报表
异常监控: 监控异常高的手续费订单

数据库设计

应用表新增字段 (transfer_apps)

ALTER TABLE kku_transfer_apps 
ADD COLUMN fee_in_rate DECIMAL(5,4) DEFAULT 0.0000 COMMENT '转入手续费率',
ADD COLUMN fee_out_rate DECIMAL(5,4) DEFAULT 0.0000 COMMENT '转出手续费率',
ADD COLUMN fee_in_min DECIMAL(15,4) DEFAULT 0.0000 COMMENT '转入最低手续费',
ADD COLUMN fee_in_max DECIMAL(15,4) DEFAULT 0.0000 COMMENT '转入最高手续费',
ADD COLUMN fee_out_min DECIMAL(15,4) DEFAULT 0.0000 COMMENT '转出最低手续费',
ADD COLUMN fee_out_max DECIMAL(15,4) DEFAULT 0.0000 COMMENT '转出最高手续费',
ADD COLUMN fee_account_uid INT DEFAULT 0 COMMENT '手续费收取账户UID';

订单表新增字段 (transfer_orders)

ALTER TABLE kku_transfer_orders
ADD COLUMN fee_rate DECIMAL(5,4) DEFAULT 0.0000 COMMENT '使用的手续费率',
ADD COLUMN fee_amount DECIMAL(15,4) DEFAULT 0.0000 COMMENT '手续费金额',
ADD COLUMN actual_amount DECIMAL(15,4) DEFAULT 0.0000 COMMENT '实际到账金额';

核心代码实现

1. 模型层增强

TransferApp 模型新增方法:

calculateInFee() - 计算转入手续费
calculateOutFee() - 计算转出手续费
isFeeEnabled() - 检查是否启用手续费
getFeeAccount() - 获取手续费账户信息

TransferOrder 模型新增方法:

hasFee() - 判断是否有手续费
setFeeInfo() - 设置手续费信息
calculateFeeFromApp() - 从应用配置计算手续费

2. 服务层扩展

TransferService 新增方法:

calculateInFee() - 计算转入手续费
calculateOutFee() - 计算转出手续费
getFeeConfig() - 获取手续费配置
getFeeStatistics() - 获取手续费统计
getAppFeeIncome() - 获取应用手续费收入

新增 FeeService 服务:

专门处理手续费相关逻辑
提供手续费计算、统计、验证功能
支持手续费配置验证和格式化

3. 逻辑层更新

TransferLogic 更新:

创建订单时自动计算手续费
资金转移时处理手续费收取
支持手续费账户的资金分配

4. DTO层增强

TransferOrderDto 新增字段:

fee_rate - 手续费率
fee_amount - 手续费金额
actual_amount - 实际到账金额
新增手续费相关的格式化方法

API使用示例

手续费计算

// 计算转出手续费
$feeInfo = TransferService::calculateOutFee(
    transferAppId: 1,
    amount: '100.00'
);
// 返回: ['fee_rate' => 0.01, 'fee_amount' => '1.0000', 'actual_amount' => '99.0000']

// 计算转入手续费
$feeInfo = TransferService::calculateInFee(
    transferAppId: 1,
    amount: '100.00'
);

创建订单（自动计算手续费）

// 转出订单 - 自动扣除手续费
$result = TransferService::createTransferOut(
    transferAppId: 1,
    userId: 12345,
    amount: '100.00',
    password: 'password'
);

// 转入订单 - 自动计算实际到账金额
$result = TransferService::createTransferIn(
    transferAppId: 1,
    userId: 12345,
    businessId: 'BIZ_001',
    amount: '100.00'
);

手续费统计

// 获取手续费配置
$config = TransferService::getFeeConfig(transferAppId: 1);

// 获取手续费统计
$stats = TransferService::getFeeStatistics(
    appId: 1,
    startDate: '2025-06-01',
    endDate: '2025-06-30'
);

// 获取应用收入统计
$income = TransferService::getAppFeeIncome(appId: 1, days: 30);

手续费计算规则

计算公式

按比例计算: 手续费 = 金额 × 手续费率
最低限制: if (手续费 < 最低手续费) 手续费 = 最低手续费
最高限制: if (最高手续费 > 0 && 手续费 > 最高手续费) 手续费 = 最高手续费
实际到账: 实际到账金额 = 原金额 - 手续费

示例计算

应用配置: 费率1%, 最低0.5, 最高10

金额	按比例	应用限制	实际到账
10.00	0.10	0.50	9.50
100.00	1.00	1.00	99.00
1500.00	15.00	10.00	1490.00

资金流向

转出订单

用户账户 → 目标账户 (实际到账金额，扣除手续费后)
用户账户 → 手续费账户 (手续费，默认UID 1)

转入订单

来源账户 → 用户账户 (实际到账金额，扣除手续费后)
来源账户 → 手续费账户 (手续费，默认UID 1)

默认手续费账户机制

默认账户: UID 1
使用规则: 当应用未配置 fee_account_uid 或配置为0时，自动使用UID 1
优先级: 应用配置 > 默认UID 1
确保收取: 无论是否配置，手续费都会被正确收取

后台管理界面

应用管理增强

手续费配置标签页: 新增专门的手续费配置界面
转入手续费设置: 费率、最低/最高手续费配置
转出手续费设置: 费率、最低/最高手续费配置
手续费账户设置: 指定手续费收取账户UID
表单验证: 完整的手续费配置验证逻辑
配置显示: 列表页面显示手续费配置概览

订单管理增强

手续费信息列: 显示费率、手续费金额、实际到账金额
详情页面: 完整的手续费信息展示
统计功能: 手续费收入统计和分析
导出功能: 支持包含手续费信息的数据导出

界面特性

用户友好: 清晰的配置说明和帮助文本
实时验证: 前端表单验证确保数据正确性
响应式设计: 适配不同屏幕尺寸
操作便捷: 一键配置手续费策略

文件结构

app/Module/Transfer/
├── Database/
│   └── fee_feature.sql          # 手续费功能数据库脚本
├── Services/
│   ├── TransferService.php      # 更新：新增手续费方法
│   └── FeeService.php           # 新增：手续费专用服务
├── Models/
│   ├── TransferApp.php          # 更新：新增手续费字段和方法
│   └── TransferOrder.php        # 更新：新增手续费字段和方法
├── Dtos/
│   └── TransferOrderDto.php     # 更新：新增手续费字段
├── Logics/
│   └── TransferLogic.php        # 更新：集成手续费计算
├── AdminControllers/
│   ├── TransferAppController.php    # 更新：新增手续费统计接口
│   └── Helper/
│       ├── TransferAppHelper.php    # 更新：新增手续费配置界面
│       └── TransferOrderHelper.php  # 更新：新增手续费显示
└── Docs/
    ├── FEE_USAGE.md             # 新增：手续费使用指南
    └── API_USAGE.md             # 更新：包含手续费API

测试和验证

✅ 功能测试完成

测试时间: 2025-06-18 21:25

测试结果: 所有功能测试通过 ✅

手续费配置测试

✅ 转入手续费率: 0.00% (未启用)
✅ 转出手续费率: 1.00% (已启用)
✅ 手续费账户: UID 1 (默认账户)
✅ 配置获取API正常工作

手续费计算测试

✅ 转出手续费计算: 10元→0.1元手续费, 100元→1元手续费, 1000元→10元手续费
✅ 转入手续费计算: 无手续费(未启用)
✅ 边界条件: 0金额、小金额、大金额计算正确
✅ 实际到账金额计算准确

模型方法测试

✅ isFeeEnabled() 方法正确判断启用状态
✅ getFeeAccountUid() 方法返回正确账户UID
✅ calculateOutFee() 和 calculateInFee() 计算准确

后台管理界面测试

✅ 应用列表页面显示手续费配置概览
✅ 应用编辑页面手续费配置标签页正常
✅ 应用详情页面完整显示手续费信息
✅ 订单管理页面包含手续费信息列
✅ 表单验证和保存功能正常

统计功能测试

✅ 手续费统计API正常工作
✅ 应用统计包含手续费数据
✅ 空数据情况处理正确

监控和维护

监控指标

手续费收入统计
异常手续费订单监控
手续费账户余额监控

日志记录

手续费计算日志
手续费收取失败日志
异常情况告警

向后兼容

现有订单的手续费字段默认为0
保留原有API接口，新增手续费相关方法
数据库字段使用默认值确保兼容性

安全考虑

手续费率限制在0-100%范围内
手续费计算使用精确的bcmath函数
手续费收取失败不影响主要业务流程
敏感操作记录详细日志

性能优化

手续费计算在内存中完成，无额外数据库查询
批量统计使用数据库聚合函数
索引优化支持手续费相关查询

总结

手续费功能的成功实现为 Transfer 模块提供了：

灵活配置 - 支持多种手续费策略，可通过后台界面轻松配置
精确计算 - 确保金额计算的准确性，使用bcmath保证精度
透明处理 - 用户可清楚了解手续费情况，后台可查看详细统计
完整统计 - 提供详细的收入分析和手续费统计功能
安全可靠 - 确保资金处理的安全性，默认手续费账户机制
管理便捷 - 完整的后台管理界面，支持可视化配置和监控
用户友好 - 清晰的界面设计和操作流程

🎯 核心亮点

默认手续费账户机制: 解决了手续费去向问题，确保手续费正确收取到UID 1
完整的后台管理: 从配置到统计的全流程管理界面
API参数优化: 将数组参数改为明确参数列表，提高代码可读性
向后兼容: 保留原有接口，平滑升级现有系统
精确计算: 使用bcmath确保手续费计算精度
灵活配置: 支持费率、最低/最高手续费等多种策略

📊 最终验证结果

完成时间: 2025-06-18 21:30 测试状态: ✅ 全部通过 部署状态: ✅ 已上线

该功能已完全集成到现有的Transfer模块中，保持了良好的向后兼容性，为业务运营提供了强有力的支持。通过完善的后台管理界面，运营人员可以轻松配置和监控手续费策略，实现精细化的收入管理。

项目成果:

🎯 解决了用户关心的手续费去向问题
💰 为平台提供了新的收入来源管理工具
🔧 优化了API接口的可读性和维护性
📊 提供了完整的手续费统计和分析功能
🖥️ 实现了用户友好的后台管理界面

182027-Transfer模块手续费功能.md 12 KB 永久連結 文件歷史 原始文件