升级URS推广模块为三代推广系统

任务时间: 2025年06月15日 00:24
任务类型: 功能升级
模块: UrsPromotion

任务概述

根据用户需求，将原有的URS推广模块从二代推广升级为三代推广系统，并新增两种收益类型：推广收益和种植收益。

主要变更

1. 推广关系扩展

原有: 支持直推和间推（二代）
升级: 支持直推、间推、三推（三代）
影响: 扩大了推广收益的覆盖范围

2. 收益类型分类

推广收益 (promotion_reward): 下级用户进入农场时发放奖励
种植收益 (planting_reward): 下级用户收获作物时发放奖励
分成比例: 不同达人等级享有不同的分成比例

3. 达人等级配置优化

配置结构: 支持两种收益类型的独立分成比例配置
JSON格式: {"1": 直推比例, "2": 间推比例, "3": 三推比例}
等级要求: 调整了各等级的团队人数要求

技术实现

1. 数据库结构调整

新增字段

urs_promotion_user_talents.indirect_count: 间推人数
urs_promotion_user_talents.third_count: 三推人数
urs_promotion_profits.profit_type: 收益类型
urs_promotion_profits.relation_level: 推荐层级

配置表优化

urs_promotion_talent_configs.promotion_reward_rates: 推广收益分成比例
urs_promotion_talent_configs.planting_reward_rates: 种植收益分成比例

2. 枚举类型定义

UrsPromotionRelationLevel

enum UrsPromotionRelationLevel: int
{
    case DIRECT = 1;    // 直推
    case INDIRECT = 2;  // 间推
    case THIRD = 3;     // 三推
}

UrsProfitType

enum UrsProfitType: string
{
    case PROMOTION_REWARD = 'promotion_reward';  // 推广收益
    case PLANTING_REWARD = 'planting_reward';    // 种植收益
}

UrsTalentLevel

enum UrsTalentLevel: int
{
    case NONE = 0;          // 非达人
    case JUNIOR = 1;        // 初级达人
    case INTERMEDIATE = 2;  // 中级达人
    case SENIOR = 3;        // 高级达人
    case EXPERT = 4;        // 资深达人
    case MASTER = 5;        // 顶级达人
}

3. 核心业务逻辑

收益分成逻辑 (UrsProfitLogic)

支持三代推广关系的收益分成计算
根据达人等级和收益类型确定分成比例
自动记录详细的分成明细

达人等级逻辑 (UrsTalentLogic)

计算三代团队统计数据
根据团队规模自动升级达人等级
支持批量更新和关系树查询

4. 服务接口

UrsProfitService

distributePromotionReward(): 分发推广收益
distributePlantingReward(): 分发种植收益
getUserProfitStats(): 获取用户收益统计

UrsTalentService

updateUserTalent(): 更新用户达人等级
getUserReferralTree(): 获取用户推荐关系树
getUserTeamStats(): 获取用户团队统计

配置数据

达人等级配置

等级	名称	直推要求	团队要求	推广收益分成	种植收益分成
0	非达人	0	0	0%/0%/0%	0%/0%/0%
1	初级达人	3	5	5%/2%/1%	3%/1%/0.5%
2	中级达人	8	15	8%/4%/2%	5%/2%/1%
3	高级达人	15	30	12%/6%/3%	8%/4%/2%
4	资深达人	30	80	15%/8%/4%	10%/5%/2.5%
5	顶级达人	50	150	20%/10%/5%	15%/8%/4%

注: 分成比例格式为直推%/间推%/三推%

测试验证

1. 数据库测试

✅ 创建所有数据库表
✅ 插入初始化配置数据
✅ 创建测试推荐关系数据
✅ 验证收益分成记录

2. 功能测试

创建了测试命令 TestUrsProfitCommand 和 TestUrsTalentCommand
可以通过命令行测试收益分成和达人等级功能

3. 测试数据

-- 测试推荐关系: 1001 -> 1002 -> 1003 -> 1004
-- 用户1001: 初级达人，3直推+1间推+1三推=5人团队
-- 收益分成测试: 用户1004收获100金币，1001获得0.5金币三推种植收益

文件变更清单

新增文件

Enums/UrsPromotionRelationLevel.php - 推广关系层级枚举
Enums/UrsProfitType.php - 收益类型枚举
Enums/UrsTalentLevel.php - 达人等级枚举
Models/UrsUserReferral.php - 用户推荐关系模型
Models/UrsUserTalent.php - 用户达人等级模型
Models/UrsProfit.php - 团队收益记录模型
Models/UrsTalentConfig.php - 达人等级配置模型
Logics/UrsProfitLogic.php - 收益分成逻辑
Logics/UrsTalentLogic.php - 达人等级逻辑
Services/UrsProfitService.php - 收益分成服务
Services/UrsTalentService.php - 达人等级服务
Repositorys/ - 各种Repository类
Commands/TestUrsProfitCommand.php - 收益分成测试命令
Commands/TestUrsTalentCommand.php - 达人等级测试命令
Commands/InsertUrsPromotionAdminMenuCommand.php - 后台菜单配置命令
Commands/UrsPromotionIntegrationTestCommand.php - 集成测试命令
Controllers/UrsPromotionApiController.php - API控制器
AdminControllers/ - 4个后台管理控制器
AdminControllers/Helper/ - 16个Helper辅助类
Events/ - 3个事件类
Listeners/ - 3个监听器类
Providers/UrsPromotionServiceProvider.php - 服务提供者
Routes/api.php - API路由配置
Routes/admin.php - 后台管理路由配置
Databases/createsql/create_urs_promotion_tables.sql - 数据库创建SQL
Databases/createsql/init_urs_promotion_data.sql - 初始化数据SQL

修改文件

README.md - 更新模块说明
Docs/设计概述.md - 更新设计文档
Docs/数据库设计.md - 更新数据库设计文档

后续开发完成

1. 后台管理界面 ✅

✅ 创建4个后台管理控制器：UrsUserReferralController、UrsUserTalentController、UrsProfitController、UrsTalentConfigController
✅ 创建16个Helper辅助类：Grid、Show、Form、Filter四套完整辅助类
✅ 配置后台管理菜单：URS推广管理主菜单，包含4个子菜单
✅ 支持达人等级批量更新、收益统计展示、推荐关系树查看

2. API接口开发 ✅

✅ 创建UrsPromotionApiController，提供7个核心API接口
✅ 用户达人信息查询、推荐关系树查询、收益统计查询
✅ 推广收益分发、种植收益分发、达人等级更新
✅ 达人等级配置查询，完整的RESTful API设计

3. 事件系统 ✅

✅ 创建3个事件类：UrsReferralCreatedEvent、UrsTalentLevelUpEvent、UrsProfitGeneratedEvent
✅ 创建3个监听器：自动更新达人等级、记录升级日志、记录收益日志
✅ 支持异步队列处理，提升系统性能

4. 集成测试 ✅

✅ 创建UrsPromotionIntegrationTestCommand集成测试命令
✅ 全面测试达人等级配置、推荐关系、等级计算、收益分成、统计功能
✅ 测试结果：三代推广关系正常，收益分成准确，统计功能完整

5. 服务注册 ✅

✅ 创建UrsPromotionServiceProvider服务提供者
✅ 注册命令、路由、定时任务
✅ 在config/app.php中注册服务提供者

待完成工作

1. 模块集成

与Farm模块集成，监听收获事件自动分发种植收益
与User模块集成，处理用户注册时的推荐关系创建
与Fund模块集成，实际发放收益到用户账户

2. 性能优化

添加Redis缓存机制，缓存达人等级和推荐关系
优化查询性能，添加必要的数据库索引
考虑大数据量时的分表策略

3. 监控告警

添加业务监控，监控收益分成异常
异常情况告警，如分成比例异常、达人等级计算错误
数据一致性检查，定期校验推荐关系和收益数据

总结

本次升级成功将URS推广模块从二代推广扩展为三代推广系统，新增了推广收益和种植收益两种类型，完善了达人等级配置，为后续的业务发展奠定了坚实的技术基础。

系统设计遵循了模块化、可扩展的原则，通过枚举类型、服务层、逻辑层的分离，确保了代码的可维护性和可测试性。

任务状态: ✅ 已完成 提交记录:

572cfb18 - 升级URS推广模块为三代推广系统
7e972549 - 完成URS推广模块后台管理和API接口开发

15-0024-升级URS推广模块为三代推广系统.md 8.2 KB Permalink History Raw