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

主要变更：
- 支持三代推广关系（直推、间推、三推）
- 新增两种收益类型：推广收益和种植收益
- 创建完整的枚举类型定义
- 实现模型、逻辑层、服务层和仓库层
- 更新数据库表结构支持新功能
- 优化达人等级配置支持不同收益类型分成比例
- 更新相关文档说明新的业务逻辑

app/Module/UrsPromotion/Databases/createsql/create_urs_promotion_tables.sql

@@ -0,0 +1,106 @@
+-- URS推广模块数据库表创建SQL
+-- 创建时间: 2025-06-15
+-- 版本: v2.0.0 (三代推广版本)
+
+-- 1. URS用户推荐关系表
+CREATE TABLE `kku_urs_promotion_user_referrals` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
+  `referrer_id` bigint unsigned NOT NULL COMMENT '推荐人ID',
+  `referral_code` varchar(32) DEFAULT NULL COMMENT '使用的推荐码',
+  `referral_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '推荐时间',
+  `status` tinyint NOT NULL DEFAULT '1' COMMENT '状态:1有效,0无效',
+  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_user_id` (`user_id`),
+  KEY `idx_referrer_id` (`referrer_id`),
+  KEY `idx_referral_code` (`referral_code`),
+  KEY `idx_referral_time` (`referral_time`),
+  KEY `idx_status` (`status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='URS用户推荐关系表';
+
+-- 2. URS达人等级表
+CREATE TABLE `kku_urs_promotion_user_talents` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
+  `talent_level` tinyint NOT NULL DEFAULT '0' COMMENT 'URS达人等级:0无,1初级,2中级,3高级,4资深,5顶级',
+  `direct_count` int NOT NULL DEFAULT '0' COMMENT '直推人数',
+  `indirect_count` int NOT NULL DEFAULT '0' COMMENT '间推人数',
+  `third_count` int NOT NULL DEFAULT '0' COMMENT '三推人数',
+  `promotion_count` int NOT NULL DEFAULT '0' COMMENT '团队总人数',
+  `last_level_update_time` timestamp NULL DEFAULT NULL COMMENT '最后等级更新时间',
+  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_user_id` (`user_id`),
+  KEY `idx_talent_level` (`talent_level`),
+  KEY `idx_direct_count` (`direct_count`),
+  KEY `idx_promotion_count` (`promotion_count`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='URS达人等级表';
+
+-- 3. URS团队收益记录表
+CREATE TABLE `kku_urs_promotion_profits` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `user_id` bigint unsigned NOT NULL COMMENT '获得收益的用户ID',
+  `promotion_member_id` bigint unsigned NOT NULL COMMENT '团队成员ID(产生收益的用户)',
+  `source_id` bigint unsigned NOT NULL COMMENT '收益来源ID',
+  `source_type` varchar(32) NOT NULL COMMENT '收益来源类型',
+  `profit_type` varchar(32) NOT NULL COMMENT '收益类型:promotion_reward推广收益,planting_reward种植收益',
+  `relation_level` tinyint NOT NULL DEFAULT '1' COMMENT '推荐层级:1直推,2间推,3三推',
+  `original_amount` decimal(30,10) NOT NULL DEFAULT '0.0000000000' COMMENT '原始收益金额',
+  `profit_amount` decimal(30,10) NOT NULL DEFAULT '0.0000000000' COMMENT '分成收益金额',
+  `profit_rate` decimal(8,6) NOT NULL DEFAULT '0.000000' COMMENT '分成比例',
+  `talent_level` tinyint NOT NULL DEFAULT '0' COMMENT '获得收益时的达人等级',
+  `status` tinyint NOT NULL DEFAULT '1' COMMENT '状态:1正常,0取消',
+  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_user_id` (`user_id`),
+  KEY `idx_promotion_member_id` (`promotion_member_id`),
+  KEY `idx_source` (`source_type`,`source_id`),
+  KEY `idx_profit_type` (`profit_type`),
+  KEY `idx_relation_level` (`relation_level`),
+  KEY `idx_created_at` (`created_at`),
+  KEY `idx_status` (`status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='URS团队收益记录表';
+
+-- 4. URS推荐码表
+CREATE TABLE `kku_urs_promotion_referral_codes` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
+  `code` varchar(32) NOT NULL COMMENT '推荐码',
+  `type` varchar(16) NOT NULL DEFAULT 'default' COMMENT '推荐码类型:default默认,custom自定义',
+  `usage_count` int NOT NULL DEFAULT '0' COMMENT '使用次数',
+  `max_usage` int NOT NULL DEFAULT '0' COMMENT '最大使用次数,0为无限制',
+  `expire_time` timestamp NULL DEFAULT NULL COMMENT '过期时间,NULL为永不过期',
+  `status` tinyint NOT NULL DEFAULT '1' COMMENT '状态:1启用,0禁用',
+  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_code` (`code`),
+  KEY `idx_user_id` (`user_id`),
+  KEY `idx_type` (`type`),
+  KEY `idx_status` (`status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='URS推荐码表';
+
+-- 5. URS达人等级配置表
+CREATE TABLE `kku_urs_promotion_talent_configs` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `level` tinyint NOT NULL COMMENT '等级:0无,1初级,2中级,3高级,4资深,5顶级',
+  `name` varchar(32) NOT NULL COMMENT '等级名称',
+  `direct_count_required` int NOT NULL DEFAULT '0' COMMENT '所需直推人数',
+  `promotion_count_required` int NOT NULL DEFAULT '0' COMMENT '所需团队总人数',
+  `promotion_reward_rates` json DEFAULT NULL COMMENT '推广收益分成比例配置',
+  `planting_reward_rates` json DEFAULT NULL COMMENT '种植收益分成比例配置',
+  `icon` varchar(255) DEFAULT NULL COMMENT '等级图标',
+  `description` text COMMENT '等级描述',
+  `sort_order` int NOT NULL DEFAULT '0' COMMENT '排序权重',
+  `status` tinyint NOT NULL DEFAULT '1' COMMENT '状态:1启用,0禁用',
+  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_level` (`level`),
+  KEY `idx_sort_order` (`sort_order`),
+  KEY `idx_status` (`status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='URS达人等级配置表';

app/Module/UrsPromotion/Databases/createsql/init_urs_promotion_data.sql

@@ -0,0 +1,71 @@
+-- URS推广模块初始化数据SQL
+-- 创建时间: 2025-06-15
+-- 版本: v2.0.0 (三代推广版本)
+
+-- 1. 初始化URS达人等级配置
+INSERT INTO `kku_urs_promotion_talent_configs` (
+    `level`, 
+    `name`, 
+    `direct_count_required`, 
+    `promotion_count_required`, 
+    `promotion_reward_rates`, 
+    `planting_reward_rates`,
+    `description`,
+    `sort_order`,
+    `status`
+) VALUES
+-- 0级：非达人
+(0, '非达人', 0, 0, 
+ '{"1": 0, "2": 0, "3": 0}', 
+ '{"1": 0, "2": 0, "3": 0}',
+ '普通用户，无达人等级，无推广收益', 0, 1),
+
+-- 1级：初级达人
+(1, 'URS初级达人', 3, 5, 
+ '{"1": 0.05, "2": 0.02, "3": 0.01}', 
+ '{"1": 0.03, "2": 0.01, "3": 0.005}',
+ '初级达人，享有基础推广收益：直推5%，间推2%，三推1%', 1, 1),
+
+-- 2级：中级达人
+(2, 'URS中级达人', 8, 15, 
+ '{"1": 0.08, "2": 0.04, "3": 0.02}', 
+ '{"1": 0.05, "2": 0.02, "3": 0.01}',
+ '中级达人，享有更高推广收益：直推8%，间推4%，三推2%', 2, 1),
+
+-- 3级：高级达人
+(3, 'URS高级达人', 15, 30, 
+ '{"1": 0.12, "2": 0.06, "3": 0.03}', 
+ '{"1": 0.08, "2": 0.04, "3": 0.02}',
+ '高级达人，享有优质推广收益：直推12%，间推6%，三推3%', 3, 1),
+
+-- 4级：资深达人
+(4, 'URS资深达人', 30, 80, 
+ '{"1": 0.15, "2": 0.08, "3": 0.04}', 
+ '{"1": 0.10, "2": 0.05, "3": 0.025}',
+ '资深达人，享有专业推广收益：直推15%，间推8%，三推4%', 4, 1),
+
+-- 5级：顶级达人
+(5, 'URS顶级达人', 50, 150, 
+ '{"1": 0.20, "2": 0.10, "3": 0.05}', 
+ '{"1": 0.15, "2": 0.08, "3": 0.04}',
+ '顶级达人，享有最高推广收益：直推20%，间推10%，三推5%', 5, 1);
+
+-- 注释说明：
+-- promotion_reward_rates: 推广收益分成比例
+--   "1": 直推分成比例
+--   "2": 间推分成比例  
+--   "3": 三推分成比例
+-- 
+-- planting_reward_rates: 种植收益分成比例
+--   "1": 直推分成比例
+--   "2": 间推分成比例
+--   "3": 三推分成比例
+--
+-- 收益类型说明：
+-- 1. 推广收益(promotion_reward)：下级用户进入农场时发放的奖励
+-- 2. 种植收益(planting_reward)：下级用户收获作物时发放的奖励
+--
+-- 推荐层级说明：
+-- 1. 直推(level=1)：用户A直接推荐用户B
+-- 2. 间推(level=2)：用户A推荐用户B，用户B推荐用户C，A获得C的间推收益
+-- 3. 三推(level=3)：用户A推荐用户B，用户B推荐用户C，用户C推荐用户D，A获得D的三推收益

app/Module/UrsPromotion/Docs/数据库设计.md

@@ -1,4 +1,4 @@
-# URS推广模块数据库设计
+# URS推广模块数据库设计 (三代推广版本)
 
 ## 1. 数据库表概览
 
@@ -9,11 +9,14 @@ URS推广模块包含以下核心数据表：
 3. **urs_promotion_profits** - URS团队收益记录表
 4. **urs_promotion_referral_codes** - URS推荐码表
 5. **urs_promotion_talent_configs** - URS达人等级配置表
-6. **urs_promotion_profit_rules** - URS收益分成规则表
-7. **urs_promotion_referral_changes** - URS推荐关系修改记录表
-8. **urs_promotion_user_relation_cache** - URS用户关系缓存表
-9. **urs_promotion_invite_rewards** - URS邀请奖励记录表
-10. **urs_promotion_referral_code_usages** - URS邀请码使用记录表
+
+## 1.1 版本更新说明
+
+**v2.0.0 (三代推广版本) 主要变更：**
+- 支持三代推广关系（直推、间推、三推）
+- 新增两种收益类型：推广收益和种植收益
+- 达人等级配置支持不同收益类型的分成比例
+- 优化数据库表结构，提升查询性能
 
 ## 2. 表结构详细设计
 
@@ -49,6 +52,8 @@ URS推广模块包含以下核心数据表：
 | user_id | bigint unsigned | - | - | 用户ID |
 | talent_level | tinyint | - | 0 | URS达人等级:0无,1初级,2中级,3高级,4资深,5顶级 |
 | direct_count | int | - | 0 | 直推人数 |
+| indirect_count | int | - | 0 | 间推人数 |
+| third_count | int | - | 0 | 三推人数 |
 | promotion_count | int | - | 0 | 团队总人数 |
 | last_level_update_time | timestamp | - | NULL | 最后等级更新时间 |
 | created_at | timestamp | - | CURRENT_TIMESTAMP | 创建时间 |
@@ -72,8 +77,8 @@ URS推广模块包含以下核心数据表：
 | promotion_member_id | bigint unsigned | - | - | 团队成员ID(产生收益的用户) |
 | source_id | bigint unsigned | - | - | 收益来源ID |
 | source_type | varchar | 32 | - | 收益来源类型 |
-| relation_type | varchar | 16 | - | 关系类型:direct直推,indirect间推 |
-| relation_level | tinyint | - | 1 | 推荐层级:1直推,2-20间推 |
+| profit_type | varchar | 32 | - | 收益类型:promotion_reward推广收益,planting_reward种植收益 |
+| relation_level | tinyint | - | 1 | 推荐层级:1直推,2间推,3三推 |
 | original_amount | decimal | 30,10 | 0.0000000000 | 原始收益金额 |
 | profit_amount | decimal | 30,10 | 0.0000000000 | 分成收益金额 |
 | profit_rate | decimal | 8,6 | 0.000000 | 分成比例 |
@@ -87,8 +92,10 @@ URS推广模块包含以下核心数据表：
 - KEY `idx_user_id` (`user_id`)
 - KEY `idx_promotion_member_id` (`promotion_member_id`)
 - KEY `idx_source` (`source_type`,`source_id`)
-- KEY `idx_relation_type` (`relation_type`)
+- KEY `idx_profit_type` (`profit_type`)
+- KEY `idx_relation_level` (`relation_level`)
 - KEY `idx_created_at` (`created_at`)
+- KEY `idx_status` (`status`)
 
 ### 2.4 URS推荐码表 (urs_promotion_referral_codes)
 
@@ -125,8 +132,8 @@ URS推广模块包含以下核心数据表：
 | name | varchar | 32 | - | 等级名称 |
 | direct_count_required | int | - | 0 | 所需直推人数 |
 | promotion_count_required | int | - | 0 | 所需团队总人数 |
-| profit_rate | decimal | 8,6 | 0.000000 | 间推分成比例 |
-| benefits | json | - | NULL | 等级权益JSON |
+| promotion_reward_rates | json | - | NULL | 推广收益分成比例配置 |
+| planting_reward_rates | json | - | NULL | 种植收益分成比例配置 |
 | icon | varchar | 255 | NULL | 等级图标 |
 | description | text | - | NULL | 等级描述 |
 | sort_order | int | - | 0 | 排序权重 |
@@ -140,6 +147,11 @@ URS推广模块包含以下核心数据表：
 - KEY `idx_sort_order` (`sort_order`)
 - KEY `idx_status` (`status`)
 
+**分成比例配置说明：**
+- `promotion_reward_rates`: 推广收益分成比例，JSON格式：`{"1": 0.05, "2": 0.03, "3": 0.01}`
+- `planting_reward_rates`: 种植收益分成比例，JSON格式：`{"1": 0.05, "2": 0.03, "3": 0.01}`
+- 键值对应推荐层级：1=直推，2=间推，3=三推
+
 ## 3. 索引设计说明
 
 ### 3.1 主要查询场景
@@ -171,21 +183,52 @@ URS推广模块包含以下核心数据表：
 
 ### 5.1 URS达人等级配置初始化
 ```sql
-INSERT INTO `kku_urs_promotion_talent_configs` (`level`, `name`, `direct_count_required`, `promotion_count_required`, `profit_rate`, `sort_order`) VALUES
-(0, '非URS达人', 0, 0, 0.000000, 0),
-(1, 'URS初级达人', 5, 10, 0.010000, 1),
-(2, 'URS中级达人', 10, 30, 0.015000, 2),
-(3, 'URS高级达人', 20, 100, 0.020000, 3),
-(4, 'URS资深达人', 50, 300, 0.025000, 4),
-(5, 'URS顶级达人', 100, 1000, 0.030000, 5);
-```
-
-### 5.2 URS收益分成规则初始化
-```sql
-INSERT INTO `kku_urs_promotion_profit_rules` (`source_type`, `name`, `direct_profit_rate`, `max_indirect_level`, `sort_order`) VALUES
-('urs_farm_harvest', 'URS农场收获', 0.050000, 20, 1),
-('urs_task_complete', 'URS任务完成', 0.030000, 10, 2),
-('urs_item_sell', 'URS物品出售', 0.020000, 5, 3);
+INSERT INTO `kku_urs_promotion_talent_configs` (
+    `level`,
+    `name`,
+    `direct_count_required`,
+    `promotion_count_required`,
+    `promotion_reward_rates`,
+    `planting_reward_rates`,
+    `description`,
+    `sort_order`,
+    `status`
+) VALUES
+-- 0级：非达人
+(0, '非达人', 0, 0,
+ '{"1": 0, "2": 0, "3": 0}',
+ '{"1": 0, "2": 0, "3": 0}',
+ '普通用户，无达人等级，无推广收益', 0, 1),
+
+-- 1级：初级达人
+(1, 'URS初级达人', 3, 5,
+ '{"1": 0.05, "2": 0.02, "3": 0.01}',
+ '{"1": 0.03, "2": 0.01, "3": 0.005}',
+ '初级达人，享有基础推广收益', 1, 1),
+
+-- 2级：中级达人
+(2, 'URS中级达人', 8, 15,
+ '{"1": 0.08, "2": 0.04, "3": 0.02}',
+ '{"1": 0.05, "2": 0.02, "3": 0.01}',
+ '中级达人，享有更高推广收益', 2, 1),
+
+-- 3级：高级达人
+(3, 'URS高级达人', 15, 30,
+ '{"1": 0.12, "2": 0.06, "3": 0.03}',
+ '{"1": 0.08, "2": 0.04, "3": 0.02}',
+ '高级达人，享有优质推广收益', 3, 1),
+
+-- 4级：资深达人
+(4, 'URS资深达人', 30, 80,
+ '{"1": 0.15, "2": 0.08, "3": 0.04}',
+ '{"1": 0.10, "2": 0.05, "3": 0.025}',
+ '资深达人，享有专业推广收益', 4, 1),
+
+-- 5级：顶级达人
+(5, 'URS顶级达人', 50, 150,
+ '{"1": 0.20, "2": 0.10, "3": 0.05}',
+ '{"1": 0.15, "2": 0.08, "3": 0.04}',
+ '顶级达人，享有最高推广收益', 5, 1);
 ```
 
 ## 6. 性能优化建议

app/Module/UrsPromotion/Docs/设计概述.md

@@ -1,18 +1,38 @@
-# URS推广模块设计概述
+# URS推广模块设计概述 (三代推广版本)
 
 ## 1. 模块定位
 
-URS推广模块是开心农场系统的专用推广模块，专门为URS业务场景设计。该模块负责管理URS用户之间的推荐关系、团队结构、达人等级和收益分成机制。通过建立用户间的直推和间推关系，形成URS团队结构，并在团队成员产生收益时进行分成，鼓励用户发展URS团队，形成良性的社交生态。
+URS推广模块是开心农场系统的专用推广模块，专门为URS业务场景设计。该模块负责管理URS用户之间的推荐关系、团队结构、达人等级和收益分成机制。通过建立用户间的直推、间推和三推关系，形成三代URS团队结构，并在团队成员产生收益时进行分成，鼓励用户发展URS团队，形成良性的社交生态。
+
+### 1.1 版本更新 (v2.0.0)
+
+**主要变更：**
+- 推广关系从二代扩展为三代（直推、间推、三推）
+- 收益类型分为两种：推广收益和种植收益
+- 达人等级配置支持不同收益类型的分成比例
+- 优化业务逻辑，提升系统性能
 
 ## 2. 设计目标
 
-1. **建立完整的URS用户推荐体系**：支持直推和间推关系，形成多层级的URS团队结构
+1. **建立完整的URS用户推荐体系**：支持三代推荐关系（直推、间推、三推），形成多层级的URS团队结构
 2. **实现灵活的URS达人等级系统**：根据团队规模和活跃度评定用户的URS达人等级
 3. **提供公平的URS收益分成机制**：根据推荐关系和URS达人等级分配团队收益
-4. **支持多种URS收益来源**：支持农场收获、任务完成等多种收益来源的分成
+4. **支持多种URS收益类型**：支持推广收益和种植收益两种不同的收益分成
 5. **保证系统的可扩展性**：预留URS达人等级、分成比例和收益来源的扩展空间
 6. **确保与现有模块的隔离性**：与Promotion模块完全独立，避免数据和功能冲突
 
+### 2.1 收益类型说明
+
+**推广收益 (promotion_reward)**：
+- 触发条件：下级用户进入农场时
+- 分成对象：直推、间推、三推上级
+- 分成比例：根据达人等级确定
+
+**种植收益 (planting_reward)**：
+- 触发条件：下级用户收获作物时
+- 分成对象：直推、间推、三推上级
+- 分成比例：根据达人等级确定
+
 ## 3. 架构设计
 
 ### 3.1 模块结构

app/Module/UrsPromotion/Enums/UrsProfitType.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace App\Module\UrsPromotion\Enums;
+
+/**
+ * URS收益类型枚举
+ * 
+ * 定义URS推广系统中的收益类型
+ */
+enum UrsProfitType: string
+{
+    /**
+     * 推广收益 - 下级进入农场发放奖励
+     */
+    case PROMOTION_REWARD = 'promotion_reward';
+    
+    /**
+     * 种植收益 - 下级收获给予奖励
+     */
+    case PLANTING_REWARD = 'planting_reward';
+
+    /**
+     * 获取收益类型名称
+     */
+    public function getName(): string
+    {
+        return match($this) {
+            self::PROMOTION_REWARD => '推广收益',
+            self::PLANTING_REWARD => '种植收益',
+        };
+    }
+
+    /**
+     * 获取收益类型描述
+     */
+    public function getDescription(): string
+    {
+        return match($this) {
+            self::PROMOTION_REWARD => '下级用户进入农场时发放的推广奖励',
+            self::PLANTING_REWARD => '下级用户收获作物时发放的种植奖励',
+        };
+    }
+
+    /**
+     * 获取所有收益类型
+     */
+    public static function getAllTypes(): array
+    {
+        return [
+            self::PROMOTION_REWARD->value => self::PROMOTION_REWARD->getName(),
+            self::PLANTING_REWARD->value => self::PLANTING_REWARD->getName(),
+        ];
+    }
+
+    /**
+     * 检查是否为有效收益类型
+     */
+    public static function isValidType(string $type): bool
+    {
+        return in_array($type, [self::PROMOTION_REWARD->value, self::PLANTING_REWARD->value]);
+    }
+
+    /**
+     * 从字符串创建枚举实例
+     */
+    public static function fromString(string $type): ?self
+    {
+        return match($type) {
+            'promotion_reward' => self::PROMOTION_REWARD,
+            'planting_reward' => self::PLANTING_REWARD,
+            default => null,
+        };
+    }
+}

app/Module/UrsPromotion/Enums/UrsPromotionRelationLevel.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace App\Module\UrsPromotion\Enums;
+
+/**
+ * URS推广关系层级枚举
+ * 
+ * 定义URS推广系统中的推荐关系层级
+ */
+enum UrsPromotionRelationLevel: int
+{
+    /**
+     * 直推关系 - 第一层级
+     */
+    case DIRECT = 1;
+    
+    /**
+     * 间推关系 - 第二层级
+     */
+    case INDIRECT = 2;
+    
+    /**
+     * 三推关系 - 第三层级
+     */
+    case THIRD = 3;
+
+    /**
+     * 获取层级名称
+     */
+    public function getName(): string
+    {
+        return match($this) {
+            self::DIRECT => '直推',
+            self::INDIRECT => '间推',
+            self::THIRD => '三推',
+        };
+    }
+
+    /**
+     * 获取层级描述
+     */
+    public function getDescription(): string
+    {
+        return match($this) {
+            self::DIRECT => '直接推荐的下级用户',
+            self::INDIRECT => '间接推荐的下级用户（下级的下级）',
+            self::THIRD => '三级推荐的下级用户（下级的下级的下级）',
+        };
+    }
+
+    /**
+     * 获取所有层级
+     */
+    public static function getAllLevels(): array
+    {
+        return [
+            self::DIRECT->value => self::DIRECT->getName(),
+            self::INDIRECT->value => self::INDIRECT->getName(),
+            self::THIRD->value => self::THIRD->getName(),
+        ];
+    }
+
+    /**
+     * 检查是否为有效层级
+     */
+    public static function isValidLevel(int $level): bool
+    {
+        return in_array($level, [self::DIRECT->value, self::INDIRECT->value, self::THIRD->value]);
+    }
+
+    /**
+     * 获取最大层级
+     */
+    public static function getMaxLevel(): int
+    {
+        return self::THIRD->value;
+    }
+}

app/Module/UrsPromotion/Enums/UrsTalentLevel.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace App\Module\UrsPromotion\Enums;
+
+/**
+ * URS达人等级枚举
+ * 
+ * 定义URS推广系统中的达人等级
+ */
+enum UrsTalentLevel: int
+{
+    /**
+     * 非达人 - 默认等级
+     */
+    case NONE = 0;
+    
+    /**
+     * 初级达人
+     */
+    case JUNIOR = 1;
+    
+    /**
+     * 中级达人
+     */
+    case INTERMEDIATE = 2;
+    
+    /**
+     * 高级达人
+     */
+    case SENIOR = 3;
+    
+    /**
+     * 资深达人
+     */
+    case EXPERT = 4;
+    
+    /**
+     * 顶级达人
+     */
+    case MASTER = 5;
+
+    /**
+     * 获取等级名称
+     */
+    public function getName(): string
+    {
+        return match($this) {
+            self::NONE => '非达人',
+            self::JUNIOR => 'URS初级达人',
+            self::INTERMEDIATE => 'URS中级达人',
+            self::SENIOR => 'URS高级达人',
+            self::EXPERT => 'URS资深达人',
+            self::MASTER => 'URS顶级达人',
+        };
+    }
+
+    /**
+     * 获取等级描述
+     */
+    public function getDescription(): string
+    {
+        return match($this) {
+            self::NONE => '普通用户，无达人等级',
+            self::JUNIOR => '初级达人，享有基础推广收益',
+            self::INTERMEDIATE => '中级达人，享有更高推广收益',
+            self::SENIOR => '高级达人，享有优质推广收益',
+            self::EXPERT => '资深达人，享有专业推广收益',
+            self::MASTER => '顶级达人，享有最高推广收益',
+        };
+    }
+
+    /**
+     * 获取所有等级
+     */
+    public static function getAllLevels(): array
+    {
+        return [
+            self::NONE->value => self::NONE->getName(),
+            self::JUNIOR->value => self::JUNIOR->getName(),
+            self::INTERMEDIATE->value => self::INTERMEDIATE->getName(),
+            self::SENIOR->value => self::SENIOR->getName(),
+            self::EXPERT->value => self::EXPERT->getName(),
+            self::MASTER->value => self::MASTER->getName(),
+        ];
+    }
+
+    /**
+     * 检查是否为有效等级
+     */
+    public static function isValidLevel(int $level): bool
+    {
+        return in_array($level, [
+            self::NONE->value,
+            self::JUNIOR->value,
+            self::INTERMEDIATE->value,
+            self::SENIOR->value,
+            self::EXPERT->value,
+            self::MASTER->value,
+        ]);
+    }
+
+    /**
+     * 获取最高等级
+     */
+    public static function getMaxLevel(): int
+    {
+        return self::MASTER->value;
+    }
+
+    /**
+     * 检查是否为达人等级（非0级）
+     */
+    public function isTalent(): bool
+    {
+        return $this !== self::NONE;
+    }
+
+    /**
+     * 从整数创建枚举实例
+     */
+    public static function fromInt(int $level): ?self
+    {
+        return match($level) {
+            0 => self::NONE,
+            1 => self::JUNIOR,
+            2 => self::INTERMEDIATE,
+            3 => self::SENIOR,
+            4 => self::EXPERT,
+            5 => self::MASTER,
+            default => null,
+        };
+    }
+}

app/Module/UrsPromotion/Logics/UrsProfitLogic.php

@@ -0,0 +1,295 @@
+<?php
+
+namespace App\Module\UrsPromotion\Logics;
+
+use App\Module\UrsPromotion\Models\UrsUserReferral;
+use App\Module\UrsPromotion\Models\UrsUserTalent;
+use App\Module\UrsPromotion\Models\UrsProfit;
+use App\Module\UrsPromotion\Models\UrsTalentConfig;
+use App\Module\UrsPromotion\Enums\UrsProfitType;
+use App\Module\UrsPromotion\Enums\UrsPromotionRelationLevel;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * URS收益分成逻辑类
+ * 
+ * 处理URS推广系统的收益分成逻辑，支持三代推广关系
+ */
+class UrsProfitLogic
+{
+    /**
+     * 计算并分发URS推广收益
+     * 
+     * @param int $userId 产生收益的用户ID
+     * @param string $sourceType 收益来源类型
+     * @param int $sourceId 收益来源ID
+     * @param UrsProfitType $profitType 收益类型
+     * @param string $originalAmount 原始收益金额
+     * @return array 分成记录
+     */
+    public function distributeProfit(
+        int $userId, 
+        string $sourceType, 
+        int $sourceId, 
+        UrsProfitType $profitType, 
+        string $originalAmount
+    ): array {
+        $profits = [];
+        
+        try {
+            // 获取用户的推荐关系链（三代）
+            $referralChain = $this->getUserReferralChain($userId);
+            
+            if (empty($referralChain)) {
+                Log::info("用户 {$userId} 无推荐关系，无需分成");
+                return $profits;
+            }
+            
+            // 获取达人等级配置
+            $talentConfigs = $this->getTalentConfigs();
+            
+            // 为每一级推荐人计算分成
+            foreach ($referralChain as $level => $referrerId) {
+                $profit = $this->calculateLevelProfit(
+                    $referrerId,
+                    $userId,
+                    $sourceType,
+                    $sourceId,
+                    $profitType,
+                    $level,
+                    $originalAmount,
+                    $talentConfigs
+                );
+                
+                if ($profit) {
+                    $profits[] = $profit;
+                }
+            }
+            
+            Log::info("用户 {$userId} 收益分成完成", [
+                'source_type' => $sourceType,
+                'source_id' => $sourceId,
+                'profit_type' => $profitType->value,
+                'original_amount' => $originalAmount,
+                'profits_count' => count($profits)
+            ]);
+            
+        } catch (\Exception $e) {
+            Log::error("URS收益分成失败", [
+                'user_id' => $userId,
+                'source_type' => $sourceType,
+                'source_id' => $sourceId,
+                'profit_type' => $profitType->value,
+                'error' => $e->getMessage()
+            ]);
+        }
+        
+        return $profits;
+    }
+    
+    /**
+     * 获取用户的推荐关系链（三代）
+     * 
+     * @param int $userId 用户ID
+     * @return array [level => referrer_id] 1:直推 2:间推 3:三推
+     */
+    private function getUserReferralChain(int $userId): array
+    {
+        $chain = [];
+        $currentUserId = $userId;
+        
+        // 最多查找三代
+        for ($level = 1; $level <= UrsPromotionRelationLevel::getMaxLevel(); $level++) {
+            $referral = UrsUserReferral::where('user_id', $currentUserId)
+                ->where('status', UrsUserReferral::STATUS_VALID)
+                ->first();
+                
+            if (!$referral) {
+                break;
+            }
+            
+            $chain[$level] = $referral->referrer_id;
+            $currentUserId = $referral->referrer_id;
+        }
+        
+        return $chain;
+    }
+    
+    /**
+     * 获取达人等级配置
+     * 
+     * @return array [level => config]
+     */
+    private function getTalentConfigs(): array
+    {
+        static $configs = null;
+        
+        if ($configs === null) {
+            $configs = UrsTalentConfig::where('status', UrsTalentConfig::STATUS_ENABLED)
+                ->get()
+                ->keyBy('level')
+                ->toArray();
+        }
+        
+        return $configs;
+    }
+    
+    /**
+     * 计算单级推荐人的分成收益
+     * 
+     * @param int $referrerId 推荐人ID
+     * @param int $memberId 团队成员ID
+     * @param string $sourceType 收益来源类型
+     * @param int $sourceId 收益来源ID
+     * @param UrsProfitType $profitType 收益类型
+     * @param int $relationLevel 推荐层级
+     * @param string $originalAmount 原始收益金额
+     * @param array $talentConfigs 达人等级配置
+     * @return UrsProfit|null
+     */
+    private function calculateLevelProfit(
+        int $referrerId,
+        int $memberId,
+        string $sourceType,
+        int $sourceId,
+        UrsProfitType $profitType,
+        int $relationLevel,
+        string $originalAmount,
+        array $talentConfigs
+    ): ?UrsProfit {
+        // 获取推荐人的达人等级
+        $talent = UrsUserTalent::where('user_id', $referrerId)->first();
+        $talentLevel = $talent ? $talent->talent_level : 0;
+        
+        // 获取对应等级的配置
+        $config = $talentConfigs[$talentLevel] ?? null;
+        if (!$config) {
+            Log::warning("推荐人 {$referrerId} 达人等级 {$talentLevel} 配置不存在");
+            return null;
+        }
+        
+        // 获取分成比例
+        $profitRate = $this->getProfitRate($config, $profitType, $relationLevel);
+        if ($profitRate <= 0) {
+            Log::debug("推荐人 {$referrerId} 等级 {$talentLevel} 层级 {$relationLevel} 分成比例为0");
+            return null;
+        }
+        
+        // 计算分成金额
+        $profitAmount = bcmul($originalAmount, (string)$profitRate, 10);
+        
+        // 创建收益记录
+        $profit = UrsProfit::create([
+            'user_id' => $referrerId,
+            'promotion_member_id' => $memberId,
+            'source_id' => $sourceId,
+            'source_type' => $sourceType,
+            'profit_type' => $profitType->value,
+            'relation_level' => $relationLevel,
+            'original_amount' => $originalAmount,
+            'profit_amount' => $profitAmount,
+            'profit_rate' => $profitRate,
+            'talent_level' => $talentLevel,
+            'status' => UrsProfit::STATUS_NORMAL,
+        ]);
+        
+        Log::info("URS收益分成记录创建", [
+            'profit_id' => $profit->id,
+            'referrer_id' => $referrerId,
+            'member_id' => $memberId,
+            'relation_level' => $relationLevel,
+            'talent_level' => $talentLevel,
+            'profit_rate' => $profitRate,
+            'profit_amount' => $profitAmount
+        ]);
+        
+        return $profit;
+    }
+    
+    /**
+     * 获取分成比例
+     * 
+     * @param array $config 达人等级配置
+     * @param UrsProfitType $profitType 收益类型
+     * @param int $relationLevel 推荐层级
+     * @return float
+     */
+    private function getProfitRate(array $config, UrsProfitType $profitType, int $relationLevel): float
+    {
+        $ratesField = match($profitType) {
+            UrsProfitType::PROMOTION_REWARD => 'promotion_reward_rates',
+            UrsProfitType::PLANTING_REWARD => 'planting_reward_rates',
+        };
+        
+        $rates = $config[$ratesField] ?? [];
+        if (is_string($rates)) {
+            $rates = json_decode($rates, true) ?? [];
+        }
+        
+        return (float)($rates[$relationLevel] ?? 0);
+    }
+    
+    /**
+     * 获取用户的收益统计
+     * 
+     * @param int $userId 用户ID
+     * @param UrsProfitType|null $profitType 收益类型
+     * @param string|null $startDate 开始日期
+     * @param string|null $endDate 结束日期
+     * @return array
+     */
+    public function getUserProfitStats(
+        int $userId, 
+        ?UrsProfitType $profitType = null, 
+        ?string $startDate = null, 
+        ?string $endDate = null
+    ): array {
+        $query = UrsProfit::where('user_id', $userId)
+            ->where('status', UrsProfit::STATUS_NORMAL);
+            
+        if ($profitType) {
+            $query->where('profit_type', $profitType->value);
+        }
+        
+        if ($startDate) {
+            $query->where('created_at', '>=', $startDate);
+        }
+        
+        if ($endDate) {
+            $query->where('created_at', '<=', $endDate);
+        }
+        
+        $profits = $query->get();
+        
+        $stats = [
+            'total_amount' => '0',
+            'total_count' => 0,
+            'by_type' => [],
+            'by_level' => [],
+        ];
+        
+        foreach ($profits as $profit) {
+            $stats['total_amount'] = bcadd($stats['total_amount'], $profit->profit_amount, 10);
+            $stats['total_count']++;
+            
+            // 按收益类型统计
+            $type = $profit->profit_type;
+            if (!isset($stats['by_type'][$type])) {
+                $stats['by_type'][$type] = ['amount' => '0', 'count' => 0];
+            }
+            $stats['by_type'][$type]['amount'] = bcadd($stats['by_type'][$type]['amount'], $profit->profit_amount, 10);
+            $stats['by_type'][$type]['count']++;
+            
+            // 按推荐层级统计
+            $level = $profit->relation_level;
+            if (!isset($stats['by_level'][$level])) {
+                $stats['by_level'][$level] = ['amount' => '0', 'count' => 0];
+            }
+            $stats['by_level'][$level]['amount'] = bcadd($stats['by_level'][$level]['amount'], $profit->profit_amount, 10);
+            $stats['by_level'][$level]['count']++;
+        }
+        
+        return $stats;
+    }
+}

app/Module/UrsPromotion/Logics/UrsTalentLogic.php

@@ -0,0 +1,300 @@
+<?php
+
+namespace App\Module\UrsPromotion\Logics;
+
+use App\Module\UrsPromotion\Models\UrsUserReferral;
+use App\Module\UrsPromotion\Models\UrsUserTalent;
+use App\Module\UrsPromotion\Models\UrsTalentConfig;
+use App\Module\UrsPromotion\Enums\UrsTalentLevel;
+use App\Module\UrsPromotion\Enums\UrsPromotionRelationLevel;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * URS达人等级逻辑类
+ * 
+ * 处理URS推广系统的达人等级计算和升级逻辑
+ */
+class UrsTalentLogic
+{
+    /**
+     * 更新用户的团队统计和达人等级
+     * 
+     * @param int $userId 用户ID
+     * @return UrsUserTalent|null
+     */
+    public function updateUserTalent(int $userId): ?UrsUserTalent
+    {
+        try {
+            // 计算团队统计数据
+            $teamStats = $this->calculateTeamStats($userId);
+            
+            // 获取或创建用户达人记录
+            $talent = UrsUserTalent::firstOrCreate(
+                ['user_id' => $userId],
+                [
+                    'talent_level' => 0,
+                    'direct_count' => 0,
+                    'indirect_count' => 0,
+                    'third_count' => 0,
+                    'promotion_count' => 0,
+                ]
+            );
+            
+            // 更新团队统计
+            $talent->updateTeamStats(
+                $teamStats['direct_count'],
+                $teamStats['indirect_count'],
+                $teamStats['third_count']
+            );
+            
+            // 计算新的达人等级
+            $newLevel = $this->calculateTalentLevel(
+                $teamStats['direct_count'],
+                $teamStats['promotion_count']
+            );
+            
+            // 检查是否需要升级
+            if ($newLevel > $talent->talent_level) {
+                $oldLevel = $talent->talent_level;
+                $talent->upgradeTalentLevel($newLevel);
+                
+                Log::info("用户达人等级升级", [
+                    'user_id' => $userId,
+                    'old_level' => $oldLevel,
+                    'new_level' => $newLevel,
+                    'direct_count' => $teamStats['direct_count'],
+                    'promotion_count' => $teamStats['promotion_count']
+                ]);
+            }
+            
+            $talent->save();
+            
+            return $talent;
+            
+        } catch (\Exception $e) {
+            Log::error("更新用户达人等级失败", [
+                'user_id' => $userId,
+                'error' => $e->getMessage()
+            ]);
+            return null;
+        }
+    }
+    
+    /**
+     * 计算用户的团队统计数据
+     * 
+     * @param int $userId 用户ID
+     * @return array
+     */
+    private function calculateTeamStats(int $userId): array
+    {
+        $stats = [
+            'direct_count' => 0,
+            'indirect_count' => 0,
+            'third_count' => 0,
+            'promotion_count' => 0,
+        ];
+        
+        // 获取直推用户
+        $directUsers = UrsUserReferral::where('referrer_id', $userId)
+            ->where('status', UrsUserReferral::STATUS_VALID)
+            ->pluck('user_id')
+            ->toArray();
+            
+        $stats['direct_count'] = count($directUsers);
+        
+        if (empty($directUsers)) {
+            return $stats;
+        }
+        
+        // 获取间推用户（直推用户的直推）
+        $indirectUsers = UrsUserReferral::whereIn('referrer_id', $directUsers)
+            ->where('status', UrsUserReferral::STATUS_VALID)
+            ->pluck('user_id')
+            ->toArray();
+            
+        $stats['indirect_count'] = count($indirectUsers);
+        
+        if (empty($indirectUsers)) {
+            $stats['promotion_count'] = $stats['direct_count'];
+            return $stats;
+        }
+        
+        // 获取三推用户（间推用户的直推）
+        $thirdUsers = UrsUserReferral::whereIn('referrer_id', $indirectUsers)
+            ->where('status', UrsUserReferral::STATUS_VALID)
+            ->pluck('user_id')
+            ->toArray();
+            
+        $stats['third_count'] = count($thirdUsers);
+        $stats['promotion_count'] = $stats['direct_count'] + $stats['indirect_count'] + $stats['third_count'];
+        
+        return $stats;
+    }
+    
+    /**
+     * 根据团队数据计算达人等级
+     * 
+     * @param int $directCount 直推人数
+     * @param int $promotionCount 团队总人数
+     * @return int
+     */
+    private function calculateTalentLevel(int $directCount, int $promotionCount): int
+    {
+        // 获取所有启用的达人等级配置，按等级倒序
+        $configs = UrsTalentConfig::where('status', UrsTalentConfig::STATUS_ENABLED)
+            ->orderBy('level', 'desc')
+            ->get();
+            
+        foreach ($configs as $config) {
+            if ($config->meetsRequirements($directCount, $promotionCount)) {
+                return $config->level;
+            }
+        }
+        
+        return 0; // 默认为非达人
+    }
+    
+    /**
+     * 批量更新推荐人的达人等级
+     * 
+     * @param array $userIds 用户ID数组
+     * @return array 更新结果
+     */
+    public function batchUpdateTalents(array $userIds): array
+    {
+        $results = [
+            'success' => 0,
+            'failed' => 0,
+            'upgraded' => [],
+        ];
+        
+        foreach ($userIds as $userId) {
+            $talent = $this->updateUserTalent($userId);
+            
+            if ($talent) {
+                $results['success']++;
+                
+                // 记录升级的用户
+                if ($talent->wasChanged('talent_level')) {
+                    $results['upgraded'][] = [
+                        'user_id' => $userId,
+                        'old_level' => $talent->getOriginal('talent_level'),
+                        'new_level' => $talent->talent_level,
+                    ];
+                }
+            } else {
+                $results['failed']++;
+            }
+        }
+        
+        return $results;
+    }
+    
+    /**
+     * 获取用户的推荐关系树（三代）
+     * 
+     * @param int $userId 用户ID
+     * @return array
+     */
+    public function getUserReferralTree(int $userId): array
+    {
+        $tree = [
+            'user_id' => $userId,
+            'direct' => [],
+            'indirect' => [],
+            'third' => [],
+        ];
+        
+        // 获取直推用户
+        $directUsers = UrsUserReferral::where('referrer_id', $userId)
+            ->where('status', UrsUserReferral::STATUS_VALID)
+            ->with('user')
+            ->get();
+            
+        foreach ($directUsers as $referral) {
+            $tree['direct'][] = [
+                'user_id' => $referral->user_id,
+                'referral_time' => $referral->referral_time,
+                'user' => $referral->user,
+            ];
+        }
+        
+        // 获取间推用户
+        if (!empty($tree['direct'])) {
+            $directUserIds = array_column($tree['direct'], 'user_id');
+            $indirectUsers = UrsUserReferral::whereIn('referrer_id', $directUserIds)
+                ->where('status', UrsUserReferral::STATUS_VALID)
+                ->with('user')
+                ->get();
+                
+            foreach ($indirectUsers as $referral) {
+                $tree['indirect'][] = [
+                    'user_id' => $referral->user_id,
+                    'referrer_id' => $referral->referrer_id,
+                    'referral_time' => $referral->referral_time,
+                    'user' => $referral->user,
+                ];
+            }
+        }
+        
+        // 获取三推用户
+        if (!empty($tree['indirect'])) {
+            $indirectUserIds = array_column($tree['indirect'], 'user_id');
+            $thirdUsers = UrsUserReferral::whereIn('referrer_id', $indirectUserIds)
+                ->where('status', UrsUserReferral::STATUS_VALID)
+                ->with('user')
+                ->get();
+                
+            foreach ($thirdUsers as $referral) {
+                $tree['third'][] = [
+                    'user_id' => $referral->user_id,
+                    'referrer_id' => $referral->referrer_id,
+                    'referral_time' => $referral->referral_time,
+                    'user' => $referral->user,
+                ];
+            }
+        }
+        
+        return $tree;
+    }
+    
+    /**
+     * 获取达人等级配置列表
+     * 
+     * @return array
+     */
+    public function getTalentConfigs(): array
+    {
+        return UrsTalentConfig::where('status', UrsTalentConfig::STATUS_ENABLED)
+            ->orderBy('sort_order')
+            ->get()
+            ->toArray();
+    }
+    
+    /**
+     * 检查用户是否可以升级到指定等级
+     * 
+     * @param int $userId 用户ID
+     * @param int $targetLevel 目标等级
+     * @return bool
+     */
+    public function canUpgradeToLevel(int $userId, int $targetLevel): bool
+    {
+        $talent = UrsUserTalent::where('user_id', $userId)->first();
+        if (!$talent) {
+            return false;
+        }
+        
+        $config = UrsTalentConfig::where('level', $targetLevel)
+            ->where('status', UrsTalentConfig::STATUS_ENABLED)
+            ->first();
+            
+        if (!$config) {
+            return false;
+        }
+        
+        return $config->meetsRequirements($talent->direct_count, $talent->promotion_count);
+    }
+}

app/Module/UrsPromotion/Models/UrsProfit.php

@@ -0,0 +1,173 @@
+<?php
+
+namespace App\Module\UrsPromotion\Models;
+
+use UCore\ModelCore;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use App\Models\User;
+use App\Module\UrsPromotion\Enums\UrsProfitType;
+use App\Module\UrsPromotion\Enums\UrsPromotionRelationLevel;
+use App\Module\UrsPromotion\Enums\UrsTalentLevel;
+
+/**
+ * URS团队收益记录模型
+ * 
+ * @property int $id 主键ID
+ * @property int $user_id 获得收益的用户ID
+ * @property int $promotion_member_id 团队成员ID(产生收益的用户)
+ * @property int $source_id 收益来源ID
+ * @property string $source_type 收益来源类型
+ * @property string $profit_type 收益类型
+ * @property int $relation_level 推荐层级
+ * @property string $original_amount 原始收益金额
+ * @property string $profit_amount 分成收益金额
+ * @property string $profit_rate 分成比例
+ * @property int $talent_level 获得收益时的达人等级
+ * @property int $status 状态:1正常,0取消
+ * @property \Carbon\Carbon $created_at 创建时间
+ * @property \Carbon\Carbon $updated_at 更新时间
+ * 
+ * @property-read User $user 获得收益的用户
+ * @property-read User $promotionMember 团队成员
+ */
+class UrsProfit extends ModelCore
+{
+    /**
+     * 数据库表名
+     */
+    protected $table = 'urs_promotion_profits';
+
+    // field start
+    /**
+     * 可批量赋值的属性
+     */
+    protected $fillable = [
+        'user_id',
+        'promotion_member_id',
+        'source_id',
+        'source_type',
+        'profit_type',
+        'relation_level',
+        'original_amount',
+        'profit_amount',
+        'profit_rate',
+        'talent_level',
+        'status',
+    ];
+    // field end
+
+    /**
+     * 属性类型转换
+     */
+    protected $casts = [
+        'user_id' => 'integer',
+        'promotion_member_id' => 'integer',
+        'source_id' => 'integer',
+        'relation_level' => 'integer',
+        'original_amount' => 'decimal:10',
+        'profit_amount' => 'decimal:10',
+        'profit_rate' => 'decimal:6',
+        'talent_level' => 'integer',
+        'status' => 'integer',
+        'created_at' => 'datetime',
+        'updated_at' => 'datetime',
+    ];
+
+    /**
+     * 状态常量
+     */
+    const STATUS_CANCELLED = 0; // 取消
+    const STATUS_NORMAL = 1;    // 正常
+
+    /**
+     * 获取用户关系
+     */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'user_id');
+    }
+
+    /**
+     * 获取团队成员关系
+     */
+    public function promotionMember(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'promotion_member_id');
+    }
+
+    /**
+     * 获取收益类型枚举
+     */
+    public function getProfitTypeEnum(): ?UrsProfitType
+    {
+        return UrsProfitType::fromString($this->profit_type);
+    }
+
+    /**
+     * 获取收益类型名称
+     */
+    public function getProfitTypeName(): string
+    {
+        return $this->getProfitTypeEnum()?->getName() ?? '未知';
+    }
+
+    /**
+     * 获取推荐层级枚举
+     */
+    public function getRelationLevelEnum(): ?UrsPromotionRelationLevel
+    {
+        return UrsPromotionRelationLevel::tryFrom($this->relation_level);
+    }
+
+    /**
+     * 获取推荐层级名称
+     */
+    public function getRelationLevelName(): string
+    {
+        return $this->getRelationLevelEnum()?->getName() ?? '未知';
+    }
+
+    /**
+     * 获取达人等级枚举
+     */
+    public function getTalentLevelEnum(): UrsTalentLevel
+    {
+        return UrsTalentLevel::fromInt($this->talent_level) ?? UrsTalentLevel::NONE;
+    }
+
+    /**
+     * 获取达人等级名称
+     */
+    public function getTalentLevelName(): string
+    {
+        return $this->getTalentLevelEnum()->getName();
+    }
+
+    /**
+     * 检查收益是否正常
+     */
+    public function isNormal(): bool
+    {
+        return $this->status === self::STATUS_NORMAL;
+    }
+
+    /**
+     * 取消收益
+     */
+    public function cancel(): void
+    {
+        $this->status = self::STATUS_CANCELLED;
+    }
+
+    /**
+     * 获取状态文本
+     */
+    public function getStatusText(): string
+    {
+        return match($this->status) {
+            self::STATUS_NORMAL => '正常',
+            self::STATUS_CANCELLED => '取消',
+            default => '未知',
+        };
+    }
+}

app/Module/UrsPromotion/Models/UrsTalentConfig.php

@@ -0,0 +1,155 @@
+<?php
+
+namespace App\Module\UrsPromotion\Models;
+
+use UCore\ModelCore;
+use App\Module\UrsPromotion\Enums\UrsTalentLevel;
+
+/**
+ * URS达人等级配置模型
+ * 
+ * @property int $id 主键ID
+ * @property int $level 等级
+ * @property string $name 等级名称
+ * @property int $direct_count_required 所需直推人数
+ * @property int $promotion_count_required 所需团队总人数
+ * @property array $promotion_reward_rates 推广收益分成比例配置
+ * @property array $planting_reward_rates 种植收益分成比例配置
+ * @property string|null $icon 等级图标
+ * @property string|null $description 等级描述
+ * @property int $sort_order 排序权重
+ * @property int $status 状态:1启用,0禁用
+ * @property \Carbon\Carbon $created_at 创建时间
+ * @property \Carbon\Carbon $updated_at 更新时间
+ */
+class UrsTalentConfig extends ModelCore
+{
+    /**
+     * 数据库表名
+     */
+    protected $table = 'urs_promotion_talent_configs';
+
+    // field start
+    /**
+     * 可批量赋值的属性
+     */
+    protected $fillable = [
+        'level',
+        'name',
+        'direct_count_required',
+        'promotion_count_required',
+        'promotion_reward_rates',
+        'planting_reward_rates',
+        'icon',
+        'description',
+        'sort_order',
+        'status',
+    ];
+    // field end
+
+    /**
+     * 属性类型转换
+     */
+    protected $casts = [
+        'level' => 'integer',
+        'direct_count_required' => 'integer',
+        'promotion_count_required' => 'integer',
+        'promotion_reward_rates' => 'array',
+        'planting_reward_rates' => 'array',
+        'sort_order' => 'integer',
+        'status' => 'integer',
+        'created_at' => 'datetime',
+        'updated_at' => 'datetime',
+    ];
+
+    /**
+     * 状态常量
+     */
+    const STATUS_DISABLED = 0; // 禁用
+    const STATUS_ENABLED = 1;  // 启用
+
+    /**
+     * 获取达人等级枚举
+     */
+    public function getTalentLevelEnum(): UrsTalentLevel
+    {
+        return UrsTalentLevel::fromInt($this->level) ?? UrsTalentLevel::NONE;
+    }
+
+    /**
+     * 检查配置是否启用
+     */
+    public function isEnabled(): bool
+    {
+        return $this->status === self::STATUS_ENABLED;
+    }
+
+    /**
+     * 获取推广收益分成比例
+     * 
+     * @param int $relationLevel 推荐层级 1:直推 2:间推 3:三推
+     * @return float
+     */
+    public function getPromotionRewardRate(int $relationLevel): float
+    {
+        $rates = $this->promotion_reward_rates ?? [];
+        return (float)($rates[$relationLevel] ?? 0);
+    }
+
+    /**
+     * 获取种植收益分成比例
+     * 
+     * @param int $relationLevel 推荐层级 1:直推 2:间推 3:三推
+     * @return float
+     */
+    public function getPlantingRewardRate(int $relationLevel): float
+    {
+        $rates = $this->planting_reward_rates ?? [];
+        return (float)($rates[$relationLevel] ?? 0);
+    }
+
+    /**
+     * 设置推广收益分成比例
+     * 
+     * @param array $rates 分成比例配置 [1 => 0.05, 2 => 0.03, 3 => 0.01]
+     */
+    public function setPromotionRewardRates(array $rates): void
+    {
+        $this->promotion_reward_rates = $rates;
+    }
+
+    /**
+     * 设置种植收益分成比例
+     * 
+     * @param array $rates 分成比例配置 [1 => 0.05, 2 => 0.03, 3 => 0.01]
+     */
+    public function setPlantingRewardRates(array $rates): void
+    {
+        $this->planting_reward_rates = $rates;
+    }
+
+    /**
+     * 检查是否满足升级条件
+     * 
+     * @param int $directCount 直推人数
+     * @param int $promotionCount 团队总人数
+     * @return bool
+     */
+    public function meetsRequirements(int $directCount, int $promotionCount): bool
+    {
+        return $directCount >= $this->direct_count_required 
+            && $promotionCount >= $this->promotion_count_required;
+    }
+
+    /**
+     * 获取状态文本
+     */
+    public function getStatusText(): string
+    {
+        return match($this->status) {
+            self::STATUS_ENABLED => '启用',
+            self::STATUS_DISABLED => '禁用',
+            default => '未知',
+        };
+    }
+}

app/Module/UrsPromotion/Models/UrsUserReferral.php

@@ -0,0 +1,113 @@
+<?php
+
+namespace App\Module\UrsPromotion\Models;
+
+use UCore\ModelCore;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use App\Models\User;
+
+/**
+ * URS用户推荐关系模型
+ * 
+ * @property int $id 主键ID
+ * @property int $user_id 用户ID
+ * @property int $referrer_id 推荐人ID
+ * @property string|null $referral_code 使用的推荐码
+ * @property \Carbon\Carbon $referral_time 推荐时间
+ * @property int $status 状态:1有效,0无效
+ * @property \Carbon\Carbon $created_at 创建时间
+ * @property \Carbon\Carbon $updated_at 更新时间
+ * 
+ * @property-read User $user 用户
+ * @property-read User $referrer 推荐人
+ */
+class UrsUserReferral extends ModelCore
+{
+    /**
+     * 数据库表名
+     */
+    protected $table = 'urs_promotion_user_referrals';
+
+    // field start
+    /**
+     * 可批量赋值的属性
+     */
+    protected $fillable = [
+        'user_id',
+        'referrer_id', 
+        'referral_code',
+        'referral_time',
+        'status',
+    ];
+    // field end
+
+    /**
+     * 属性类型转换
+     */
+    protected $casts = [
+        'user_id' => 'integer',
+        'referrer_id' => 'integer',
+        'referral_time' => 'datetime',
+        'status' => 'integer',
+        'created_at' => 'datetime',
+        'updated_at' => 'datetime',
+    ];
+
+    /**
+     * 状态常量
+     */
+    const STATUS_INVALID = 0; // 无效
+    const STATUS_VALID = 1;   // 有效
+
+    /**
+     * 获取用户关系
+     */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'user_id');
+    }
+
+    /**
+     * 获取推荐人关系
+     */
+    public function referrer(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'referrer_id');
+    }
+
+    /**
+     * 检查推荐关系是否有效
+     */
+    public function isValid(): bool
+    {
+        return $this->status === self::STATUS_VALID;
+    }
+
+    /**
+     * 设置为有效状态
+     */
+    public function setValid(): void
+    {
+        $this->status = self::STATUS_VALID;
+    }
+
+    /**
+     * 设置为无效状态
+     */
+    public function setInvalid(): void
+    {
+        $this->status = self::STATUS_INVALID;
+    }
+
+    /**
+     * 获取状态文本
+     */
+    public function getStatusText(): string
+    {
+        return match($this->status) {
+            self::STATUS_VALID => '有效',
+            self::STATUS_INVALID => '无效',
+            default => '未知',
+        };
+    }
+}

app/Module/UrsPromotion/Models/UrsUserTalent.php

@@ -0,0 +1,124 @@
+<?php
+
+namespace App\Module\UrsPromotion\Models;
+
+use UCore\ModelCore;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use App\Models\User;
+use App\Module\UrsPromotion\Enums\UrsTalentLevel;
+
+/**
+ * URS用户达人等级模型
+ * 
+ * @property int $id 主键ID
+ * @property int $user_id 用户ID
+ * @property int $talent_level URS达人等级
+ * @property int $direct_count 直推人数
+ * @property int $indirect_count 间推人数
+ * @property int $third_count 三推人数
+ * @property int $promotion_count 团队总人数
+ * @property \Carbon\Carbon|null $last_level_update_time 最后等级更新时间
+ * @property \Carbon\Carbon $created_at 创建时间
+ * @property \Carbon\Carbon $updated_at 更新时间
+ * 
+ * @property-read User $user 用户
+ */
+class UrsUserTalent extends ModelCore
+{
+    /**
+     * 数据库表名
+     */
+    protected $table = 'urs_promotion_user_talents';
+
+    // field start
+    /**
+     * 可批量赋值的属性
+     */
+    protected $fillable = [
+        'user_id',
+        'talent_level',
+        'direct_count',
+        'indirect_count',
+        'third_count',
+        'promotion_count',
+        'last_level_update_time',
+    ];
+    // field end
+
+    /**
+     * 属性类型转换
+     */
+    protected $casts = [
+        'user_id' => 'integer',
+        'talent_level' => 'integer',
+        'direct_count' => 'integer',
+        'indirect_count' => 'integer',
+        'third_count' => 'integer',
+        'promotion_count' => 'integer',
+        'last_level_update_time' => 'datetime',
+        'created_at' => 'datetime',
+        'updated_at' => 'datetime',
+    ];
+
+    /**
+     * 获取用户关系
+     */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'user_id');
+    }
+
+    /**
+     * 获取达人等级枚举
+     */
+    public function getTalentLevelEnum(): UrsTalentLevel
+    {
+        return UrsTalentLevel::fromInt($this->talent_level) ?? UrsTalentLevel::NONE;
+    }
+
+    /**
+     * 获取达人等级名称
+     */
+    public function getTalentLevelName(): string
+    {
+        return $this->getTalentLevelEnum()->getName();
+    }
+
+    /**
+     * 检查是否为达人
+     */
+    public function isTalent(): bool
+    {
+        return $this->getTalentLevelEnum()->isTalent();
+    }
+
+    /**
+     * 更新团队统计数据
+     */
+    public function updateTeamStats(int $directCount, int $indirectCount, int $thirdCount): void
+    {
+        $this->direct_count = $directCount;
+        $this->indirect_count = $indirectCount;
+        $this->third_count = $thirdCount;
+        $this->promotion_count = $directCount + $indirectCount + $thirdCount;
+    }
+
+    /**
+     * 升级达人等级
+     */
+    public function upgradeTalentLevel(int $newLevel): void
+    {
+        if ($newLevel > $this->talent_level) {
+            $this->talent_level = $newLevel;
+            $this->last_level_update_time = now();
+        }
+    }
+
+    /**
+     * 获取团队总人数
+     */
+    public function getTotalTeamCount(): int
+    {
+        return $this->direct_count + $this->indirect_count + $this->third_count;
+    }
+}

app/Module/UrsPromotion/README.md

@@ -50,9 +50,21 @@ URS达人等级分为6个级别：
 - **5级**：URS顶级达人
 
 ### 3. URS收益分成
-- **直推分成**：固定5%的分成比例
-- **间推分成**：根据URS达人等级确定分成比例
-- **分成范围**：最多支持20代间推关系
+URS收益分成支持三代推广关系，包含两种收益类型：
+
+#### 3.1 推广收益
+- **直推分成**：下级进入农场时发放奖励，根据达人等级确定分成比例
+- **间推分成**：下级的下级进入农场时发放奖励，根据达人等级确定分成比例
+- **三推分成**：下级的下级的下级进入农场时发放奖励，根据达人等级确定分成比例
+
+#### 3.2 种植收益
+- **直推分成**：下级收获作物时发放奖励，根据达人等级确定分成比例
+- **间推分成**：下级的下级收获作物时发放奖励，根据达人等级确定分成比例
+- **三推分成**：下级的下级的下级收获作物时发放奖励，根据达人等级确定分成比例
+
+#### 3.3 分成范围
+- **推广关系层级**：支持三代推广关系（直推、间推、三推）
+- **达人等级影响**：不同达人等级享有不同的分成比例
 
 ## 核心数据表
 
@@ -72,6 +84,8 @@ URS达人等级分为6个级别：
 | user_id | bigint | 用户ID |
 | talent_level | tinyint | URS达人等级 |
 | direct_count | int | 直推人数 |
+| indirect_count | int | 间推人数 |
+| third_count | int | 三推人数 |
 | promotion_count | int | 团队总人数 |
 
 ### 3. URS团队收益记录表 (urs_promotion_profits)
@@ -82,9 +96,22 @@ URS达人等级分为6个级别：
 | promotion_member_id | bigint | 团队成员ID |
 | source_id | bigint | 收益来源ID |
 | source_type | varchar | 收益来源类型 |
+| profit_type | varchar | 收益类型：promotion_reward推广收益，planting_reward种植收益 |
+| relation_level | tinyint | 推荐层级：1直推，2间推，3三推 |
 | profit_amount | decimal | 分成收益数量 |
 | profit_rate | decimal | 分成比例 |
 
+### 4. URS达人等级配置表 (urs_promotion_talent_configs)
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| id | bigint | 主键ID |
+| level | tinyint | 达人等级 |
+| name | varchar | 等级名称 |
+| direct_count_required | int | 所需直推人数 |
+| promotion_count_required | int | 所需团队总人数 |
+| promotion_reward_rates | json | 推广收益分成比例配置 |
+| planting_reward_rates | json | 种植收益分成比例配置 |
+
 ## 核心服务
 
 ### 1. URS推荐关系服务 (UrsReferralService)

app/Module/UrsPromotion/Repositorys/UrsProfitRepository.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Module\UrsPromotion\Repositorys;
+
+use App\Module\UrsPromotion\Models\UrsProfit;
+
+/**
+ * URS团队收益记录仓库
+ * 
+ * 用于后台管理数据访问
+ */
+class UrsProfitRepository
+{
+    // 此类仅用于后台管理数据访问，不包含任何方法
+}

app/Module/UrsPromotion/Repositorys/UrsTalentConfigRepository.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Module\UrsPromotion\Repositorys;
+
+use App\Module\UrsPromotion\Models\UrsTalentConfig;
+
+/**
+ * URS达人等级配置仓库
+ * 
+ * 用于后台管理数据访问
+ */
+class UrsTalentConfigRepository
+{
+    // 此类仅用于后台管理数据访问，不包含任何方法
+}

app/Module/UrsPromotion/Repositorys/UrsUserReferralRepository.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Module\UrsPromotion\Repositorys;
+
+use App\Module\UrsPromotion\Models\UrsUserReferral;
+
+/**
+ * URS用户推荐关系仓库
+ * 
+ * 用于后台管理数据访问
+ */
+class UrsUserReferralRepository
+{
+    // 此类仅用于后台管理数据访问，不包含任何方法
+}

app/Module/UrsPromotion/Repositorys/UrsUserTalentRepository.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Module\UrsPromotion\Repositorys;
+
+use App\Module\UrsPromotion\Models\UrsUserTalent;
+
+/**
+ * URS用户达人等级仓库
+ * 
+ * 用于后台管理数据访问
+ */
+class UrsUserTalentRepository
+{
+    // 此类仅用于后台管理数据访问，不包含任何方法
+}

app/Module/UrsPromotion/Services/UrsProfitService.php

@@ -0,0 +1,127 @@
+<?php
+
+namespace App\Module\UrsPromotion\Services;
+
+use App\Module\UrsPromotion\Logics\UrsProfitLogic;
+use App\Module\UrsPromotion\Enums\UrsProfitType;
+
+/**
+ * URS收益分成服务
+ * 
+ * 对外提供URS收益分成相关的服务接口
+ */
+class UrsProfitService
+{
+    /**
+     * 分发推广收益
+     * 
+     * 当下级用户进入农场时调用此方法分发推广收益
+     * 
+     * @param int $userId 产生收益的用户ID
+     * @param string $sourceType 收益来源类型
+     * @param int $sourceId 收益来源ID
+     * @param string $originalAmount 原始收益金额
+     * @return array 分成记录
+     */
+    public static function distributePromotionReward(
+        int $userId, 
+        string $sourceType, 
+        int $sourceId, 
+        string $originalAmount
+    ): array {
+        $logic = new UrsProfitLogic();
+        
+        return $logic->distributeProfit(
+            $userId,
+            $sourceType,
+            $sourceId,
+            UrsProfitType::PROMOTION_REWARD,
+            $originalAmount
+        );
+    }
+    
+    /**
+     * 分发种植收益
+     * 
+     * 当下级用户收获作物时调用此方法分发种植收益
+     * 
+     * @param int $userId 产生收益的用户ID
+     * @param string $sourceType 收益来源类型
+     * @param int $sourceId 收益来源ID
+     * @param string $originalAmount 原始收益金额
+     * @return array 分成记录
+     */
+    public static function distributePlantingReward(
+        int $userId, 
+        string $sourceType, 
+        int $sourceId, 
+        string $originalAmount
+    ): array {
+        $logic = new UrsProfitLogic();
+        
+        return $logic->distributeProfit(
+            $userId,
+            $sourceType,
+            $sourceId,
+            UrsProfitType::PLANTING_REWARD,
+            $originalAmount
+        );
+    }
+    
+    /**
+     * 获取用户的收益统计
+     * 
+     * @param int $userId 用户ID
+     * @param string|null $profitType 收益类型
+     * @param string|null $startDate 开始日期
+     * @param string|null $endDate 结束日期
+     * @return array
+     */
+    public static function getUserProfitStats(
+        int $userId, 
+        ?string $profitType = null, 
+        ?string $startDate = null, 
+        ?string $endDate = null
+    ): array {
+        $logic = new UrsProfitLogic();
+        
+        $profitTypeEnum = null;
+        if ($profitType) {
+            $profitTypeEnum = UrsProfitType::fromString($profitType);
+        }
+        
+        return $logic->getUserProfitStats($userId, $profitTypeEnum, $startDate, $endDate);
+    }
+    
+    /**
+     * 获取用户的推广收益统计
+     * 
+     * @param int $userId 用户ID
+     * @param string|null $startDate 开始日期
+     * @param string|null $endDate 结束日期
+     * @return array
+     */
+    public static function getUserPromotionRewardStats(
+        int $userId, 
+        ?string $startDate = null, 
+        ?string $endDate = null
+    ): array {
+        return self::getUserProfitStats($userId, UrsProfitType::PROMOTION_REWARD->value, $startDate, $endDate);
+    }
+    
+    /**
+     * 获取用户的种植收益统计
+     * 
+     * @param int $userId 用户ID
+     * @param string|null $startDate 开始日期
+     * @param string|null $endDate 结束日期
+     * @return array
+     */
+    public static function getUserPlantingRewardStats(
+        int $userId, 
+        ?string $startDate = null, 
+        ?string $endDate = null
+    ): array {
+        return self::getUserProfitStats($userId, UrsProfitType::PLANTING_REWARD->value, $startDate, $endDate);
+    }
+}

app/Module/UrsPromotion/Services/UrsTalentService.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace App\Module\UrsPromotion\Services;
+
+use App\Module\UrsPromotion\Logics\UrsTalentLogic;
+use App\Module\UrsPromotion\Models\UrsUserTalent;
+
+/**
+ * URS达人等级服务
+ * 
+ * 对外提供URS达人等级相关的服务接口
+ */
+class UrsTalentService
+{
+    /**
+     * 更新用户的达人等级
+     * 
+     * @param int $userId 用户ID
+     * @return UrsUserTalent|null
+     */
+    public static function updateUserTalent(int $userId): ?UrsUserTalent
+    {
+        $logic = new UrsTalentLogic();
+        return $logic->updateUserTalent($userId);
+    }
+    
+    /**
+     * 批量更新用户的达人等级
+     * 
+     * @param array $userIds 用户ID数组
+     * @return array 更新结果
+     */
+    public static function batchUpdateTalents(array $userIds): array
+    {
+        $logic = new UrsTalentLogic();
+        return $logic->batchUpdateTalents($userIds);
+    }
+    
+    /**
+     * 获取用户的达人信息
+     * 
+     * @param int $userId 用户ID
+     * @return UrsUserTalent|null
+     */
+    public static function getUserTalent(int $userId): ?UrsUserTalent
+    {
+        return UrsUserTalent::where('user_id', $userId)->first();
+    }
+    
+    /**
+     * 获取用户的推荐关系树
+     * 
+     * @param int $userId 用户ID
+     * @return array
+     */
+    public static function getUserReferralTree(int $userId): array
+    {
+        $logic = new UrsTalentLogic();
+        return $logic->getUserReferralTree($userId);
+    }
+    
+    /**
+     * 获取达人等级配置列表
+     * 
+     * @return array
+     */
+    public static function getTalentConfigs(): array
+    {
+        $logic = new UrsTalentLogic();
+        return $logic->getTalentConfigs();
+    }
+    
+    /**
+     * 检查用户是否可以升级到指定等级
+     * 
+     * @param int $userId 用户ID
+     * @param int $targetLevel 目标等级
+     * @return bool
+     */
+    public static function canUpgradeToLevel(int $userId, int $targetLevel): bool
+    {
+        $logic = new UrsTalentLogic();
+        return $logic->canUpgradeToLevel($userId, $targetLevel);
+    }
+    
+    /**
+     * 获取用户的团队统计信息
+     * 
+     * @param int $userId 用户ID
+     * @return array
+     */
+    public static function getUserTeamStats(int $userId): array
+    {
+        $talent = self::getUserTalent($userId);
+        
+        if (!$talent) {
+            return [
+                'direct_count' => 0,
+                'indirect_count' => 0,
+                'third_count' => 0,
+                'promotion_count' => 0,
+                'talent_level' => 0,
+                'talent_level_name' => '非达人',
+            ];
+        }
+        
+        return [
+            'direct_count' => $talent->direct_count,
+            'indirect_count' => $talent->indirect_count,
+            'third_count' => $talent->third_count,
+            'promotion_count' => $talent->promotion_count,
+            'talent_level' => $talent->talent_level,
+            'talent_level_name' => $talent->getTalentLevelName(),
+        ];
+    }
+}