更新达人等级逻辑文档：增加三代人数和三代活跃人数指标

- 在等级结构表中增加三代人数要求和三代活跃要求列
- 更新升级条件说明，从4个条件扩展到6个条件
- 修改calculateTalentLevel方法签名，增加三代统计参数
- 增加统计指标说明，区分20代和3代统计维度
- 更新数据库表结构，增加three_gen_count_required和three_gen_active_required字段
- 完善配置管理方法，支持三代条件检查
- 当前阶段三代人数/三代活跃人数数值等于团队人数/团队活跃人数

AiWork/now.md

@@ -12,6 +12,7 @@
 - [x] 重构UrsTalentLogic::calculateTeamStats()方法
 - [x] 添加20代统计的配置常量
 - [x] 测试验证修改结果
+- [x] 更新文档增加三代人数/三代活跃人数指标
 
 ## 工作详情（列表工作详细描述，保留5项工作的，旧的的删除）
 

app/Module/UrsPromotion/Docs/达人等级逻辑.md

@@ -24,14 +24,14 @@ URS推广模块的达人等级系统是整个推广体系的核心组件，通
 
 ### 2.1 等级结构
 
-| 等级 | 名称 | 直推要求 | 团队要求 | 活跃直推要求 | 活跃团队要求 | 描述 |
-|------|------|----------|----------|--------------|--------------|------|
-| 0 | 非达人 | 0人 | 0人 | 0人 | 0人 | 普通用户，无达人等级 |
-| 1 | URS初级达人 | 3人 | 10人 | 2人 | 3人 | 初级达人，享有基础推广收益 |
-| 2 | URS中级达人 | 8人 | 30人 | 5人 | 8人 | 中级达人，享有更高推广收益 |
-| 3 | URS高级达人 | 15人 | 80人 | 8人 | 15人 | 高级达人，享有优质推广收益 |
-| 4 | URS资深达人 | 30人 | 200人 | 15人 | 30人 | 资深达人，享有专业推广收益 |
-| 5 | URS顶级达人 | 50人 | 500人 | 25人 | 50人 | 顶级达人，享有最高推广收益 |
+| 等级 | 名称 | 直推要求 | 团队要求(20代) | 活跃直推要求 | 活跃团队要求(20代) | 三代人数要求 | 三代活跃要求 | 描述 |
+|------|------|----------|---------------|--------------|------------------|-------------|-------------|------|
+| 0 | 非达人 | 0人 | 0人 | 0人 | 0人 | 0人 | 0人 | 普通用户，无达人等级 |
+| 1 | URS初级达人 | 3人 | 10人 | 2人 | 3人 | 10人 | 3人 | 初级达人，享有基础推广收益 |
+| 2 | URS中级达人 | 8人 | 30人 | 5人 | 8人 | 30人 | 8人 | 中级达人，享有更高推广收益 |
+| 3 | URS高级达人 | 15人 | 80人 | 8人 | 15人 | 80人 | 15人 | 高级达人，享有优质推广收益 |
+| 4 | URS资深达人 | 30人 | 200人 | 15人 | 30人 | 200人 | 30人 | 资深达人，享有专业推广收益 |
+| 5 | URS顶级达人 | 50人 | 500人 | 25人 | 50人 | 500人 | 50人 | 顶级达人，享有最高推广收益 |
 
 ### 2.2 等级枚举定义
 
@@ -51,13 +51,19 @@ enum UrsTalentLevel: int
 
 ### 3.1 升级条件
 
-达人等级的升级需要同时满足四个条件：
+达人等级的升级需要同时满足六个条件：
 1. **直推人数**：用户直接推荐的下级用户数量
-2. **团队总人数**：包括直推、间推、三推的所有下级用户总数
+2. **团队总人数**：包括直推、间推、三推的所有下级用户总数（20代统计）
 3. **活跃直推人数**：直推用户中活跃用户的数量
-4. **活跃团队总人数**：团队中所有活跃用户的数量
+4. **活跃团队总人数**：团队中所有活跃用户的数量（20代统计）
+5. **三代人数**：包括直推、间推、三推的用户总数（3代统计）
+6. **三代活跃人数**：三代用户中活跃用户的数量（3代统计）
 
-#### 3.1.1 有效人数（活跃人数）定义
+#### 3.1.1 统计指标说明
+
+**团队统计维度**：
+- **20代团队统计**：团队总人数和活跃团队总人数使用20代深度统计，包含所有下级用户
+- **3代团队统计**：三代人数和三代活跃人数仅统计直推、间推、三推三个层级
 
 **活跃用户判定标准**：
 - **时间范围**：最近15天内有活动记录
@@ -70,6 +76,11 @@ enum UrsTalentLevel: int
 - `last_activity_check`：最后活跃检查时间
 - `active_days_count`：活跃天数统计
 
+**指标设计说明**：
+- **三代人数/三代活跃人数**：当前阶段数值等于团队人数/团队活跃人数，为后续业务扩展预留
+- **20代统计**：提供更全面的团队规模评估，支持深度推广激励
+- **3代统计**：保持传统推广模式的兼容性，便于业务对比分析
+
 **活跃用户的业务价值**：
 - 提升推广体系的质量和真实性
 - 避免僵尸用户影响达人等级评估
@@ -82,7 +93,9 @@ private static function calculateTalentLevel(
     int $directCount,
     int $totalCount,
     int $activeDirectCount = 0,
-    int $activeTotalCount = 0
+    int $activeTotalCount = 0,
+    int $threeGenCount = 0,
+    int $threeGenActiveCount = 0
 ): int {
     // 获取等级配置（按等级倒序排列）
     $configs = UrsTalentConfig::where('status', 1)
@@ -98,7 +111,12 @@ private static function calculateTalentLevel(
         $activeDirectMet = $activeDirectCount >= $config->active_direct_required;
         $activeTotalMet = $activeTotalCount >= $config->active_count_required;
 
-        if ($directCountMet && $totalCountMet && $activeDirectMet && $activeTotalMet) {
+        // 检查三代条件
+        $threeGenCountMet = $threeGenCount >= $config->three_gen_count_required;
+        $threeGenActiveMet = $threeGenActiveCount >= $config->three_gen_active_required;
+
+        if ($directCountMet && $totalCountMet && $activeDirectMet && $activeTotalMet
+            && $threeGenCountMet && $threeGenActiveMet) {
             return $config->level;
         }
     }
@@ -447,6 +465,8 @@ class UrsTalentConfig extends ModelCore
     // promotion_count_required: 所需团队总人数
     // active_direct_required: 所需活跃直推人数
     // active_count_required: 所需活跃团队总人数
+    // three_gen_count_required: 所需三代人数
+    // three_gen_active_required: 所需三代活跃人数
     // promotion_direct_group: 直推奖励组ID
     // promotion_indirect_group: 间推奖励组ID
     // promotion_third_group: 三推奖励组ID
@@ -538,6 +558,8 @@ CREATE TABLE `kku_urs_promotion_talent_configs` (
   `promotion_count_required` int NOT NULL DEFAULT '0' COMMENT '所需团队总人数',
   `active_direct_required` int NOT NULL DEFAULT '0' COMMENT '所需活跃直推人数',
   `active_count_required` int NOT NULL DEFAULT '0' COMMENT '所需活跃团队总人数',
+  `three_gen_count_required` int NOT NULL DEFAULT '0' COMMENT '所需三代人数',
+  `three_gen_active_required` int NOT NULL DEFAULT '0' COMMENT '所需三代活跃人数',
   `icon` varchar(255) DEFAULT NULL COMMENT '等级图标',
   `description` text COMMENT '等级描述',
   `sort_order` int NOT NULL DEFAULT '0' COMMENT '排序权重',
@@ -595,10 +617,20 @@ public function getPlantingRewardRate(int $relationLevel): float
 }
 
 // 检查是否满足升级条件
-public function meetsRequirements(int $directCount, int $promotionCount): bool
-{
+public function meetsRequirements(
+    int $directCount,
+    int $promotionCount,
+    int $activeDirectCount = 0,
+    int $activeTotalCount = 0,
+    int $threeGenCount = 0,
+    int $threeGenActiveCount = 0
+): bool {
     return $directCount >= $this->direct_count_required
-        && $promotionCount >= $this->promotion_count_required;
+        && $promotionCount >= $this->promotion_count_required
+        && $activeDirectCount >= $this->active_direct_required
+        && $activeTotalCount >= $this->active_count_required
+        && $threeGenCount >= $this->three_gen_count_required
+        && $threeGenActiveCount >= $this->three_gen_active_required;
 }
 ```