kknongchang_2506/AiWork/202506/251328-URS合伙人分红功能开发.md

URS合伙人分红功能开发

任务时间: 2025-06-25 13:28
任务类型: 功能开发
状态: ✅ 已完成

任务概述

为URS推广模块开发合伙人分红功能，顶级达人（等级5）享受手续费分红。每天11:30执行分红，将当日总手续费的20%平均分给所有合伙人。

需求分析

根据需求文档 app/Module/UrsPromotion/Docs/合伙人分红.md：

• 顶级达人就是合伙人，享受手续费分红
• 钻石每天兑出的手续费中的20％均分给全网的合伙人
• 11:30执行分红
• 使用Transfer模块的手续费统计功能读取今天的统计
• 使用Transfer模块的手续费转移功能进行分红

完成的功能

1. 数据库设计

合伙人分红记录表 (kku_urs_promotion_partner_dividend_records)

• 记录每日分红的基本信息
• 包含分红日期、总手续费、分红金额、合伙人数量等
• 支持状态管理：pending、processing、completed、failed

合伙人分红详情表 (kku_urs_promotion_partner_dividend_details)

• 记录每个合伙人的分红详情
• 包含用户ID、URS用户ID、分红金额、转账状态等
• 关联转账订单ID用于追踪

2. 模型层

UrsPartnerDividendRecord 模型

• 继承自 ModelCore
• 完整的字段定义和类型转换
• 关联 TransferApp 和分红详情
• 提供便捷的查询方法

UrsPartnerDividendDetail 模型

• 记录单个合伙人的分红详情
• 关联用户、分红记录、转账订单
• 提供状态管理和查询方法

3. 服务层架构

UrsPartnerDividendService (对外服务接口)

• executeDailyDividend(): 执行每日分红
• getPartnerList(): 获取合伙人列表
• getDividendHistory(): 获取分红历史
• getDividendDetails(): 获取分红详情
• getUserDividendHistory(): 获取用户分红历史
• getDividendStatistics(): 获取分红统计信息

UrsPartnerDividendLogic (内部业务逻辑)

• 处理分红的核心业务逻辑
• 获取手续费统计数据
• 计算分红金额（总手续费的20%）
• 获取所有合伙人（顶级达人，等级5）
• 执行手续费转移
• 记录分红结果

4. 命令行工具

UrsPartnerDividendCommand (urs-promotion:partner-dividend)

• 支持指定分红日期：--date=2025-06-24
• 支持强制执行：--force
• 显示合伙人信息和分红结果
• 完整的错误处理和日志记录

5. 定时任务

在 UrsPromotionServiceProvider 中注册定时任务：

• 每天11:30执行分红：dailyAt('11:30')
• 防止重复执行：withoutOverlapping()
• 后台运行：runInBackground()

6. 后台管理界面

UrsPartnerDividendController

• 分红记录列表页面
• 分红详情查看
• 手动执行分红功能
• 分红统计页面

UrsPartnerDividendRepository

• 仅供后台管理数据访问使用
• 支持预加载关系

核心算法

分红计算逻辑

1. 获取指定日期的手续费统计数据
2. 计算总手续费金额
3. 计算分红金额 = 总手续费 × 20%
4. 获取所有合伙人（talent_level = 5）
5. 计算每人分红 = 分红金额 ÷ 合伙人数量
6. 使用Transfer模块的手续费转移功能进行转账

合伙人识别

• 从 urs_promotion_user_talents 表获取 talent_level = 5 的用户
• 通过 UrsUserMappingService 获取对应的URS用户ID
• 确保用户有效且已进入农场

测试验证

测试数据

• 创建测试合伙人：用户ID 39118，URS用户ID 10002
• 手续费统计：2025-06-24 总手续费 11.25 钻石

测试结果

php artisan urs-promotion:partner-dividend --date=2025-06-24

执行结果：

• 分红日期: 2025-06-24
• 当日总手续费: 11.2500000000 钻石
• 分红总金额: 2.2500000000 钻石 (20%)
• 合伙人数量: 1 人
• 每人分红: 2.2500000000 钻石
• 成功转账: 1 人
• 成功率: 100%

数据验证

• 分红记录表：成功创建记录，状态为 completed
• 分红详情表：成功创建详情，状态为 completed
• 资金日志：用户成功收到 2.25 钻石
• 重复执行检查：正确提示已处理过

技术特点

1. 安全性

• 事务处理确保数据一致性
• 重复执行检查防止重复分红
• 完整的错误处理和日志记录

2. 可扩展性

• 模块化设计，易于维护
• 支持多个转账应用
• 灵活的状态管理

3. 可监控性

• 详细的日志记录
• 完整的分红历史
• 统计信息展示

文件清单

新增文件

• app/Module/UrsPromotion/Models/UrsPartnerDividendRecord.php
• app/Module/UrsPromotion/Models/UrsPartnerDividendDetail.php
• app/Module/UrsPromotion/Logics/UrsPartnerDividendLogic.php
• app/Module/UrsPromotion/Services/UrsPartnerDividendService.php
• app/Module/UrsPromotion/Commands/UrsPartnerDividendCommand.php
• app/Module/UrsPromotion/AdminControllers/UrsPartnerDividendController.php
• app/Module/UrsPromotion/Repositories/UrsPartnerDividendRepository.php
• app/Module/UrsPromotion/Database/create_partner_dividend_tables.sql

修改文件

• app/Module/UrsPromotion/Providers/UrsPromotionServiceProvider.php

部署说明

1. 执行SQL创建数据库表
2. 确保定时任务正常运行
3. 验证Transfer模块手续费统计功能正常
4. 测试分红命令执行

后续优化建议

1. 添加分红规则配置（分红比例、最小分红金额等）
2. 支持分红暂停/恢复功能
3. 添加分红通知功能
4. 优化大量合伙人的分红性能
5. 添加分红报表和图表展示

提交信息

Git提交: dbc44665 - 完成URS合伙人分红功能开发