# URS推广模块20代关系缓存机制升级

**任务时间**: 2025年07月03日 14:15  
**任务类型**: 功能升级  
**模块**: UrsPromotion  

## 任务背景

用户询问URS推广模块关系缓存的创建时机，并要求支持20代的关系缓存，原有系统只支持3代关系。

## 问题分析

### 原有限制
1. **层级限制**: 原有枚举只支持3代关系（直推、间推、三推）
2. **性能瓶颈**: 深层级关系查询需要多次递归查询
3. **业务需求**: 实际业务需要支持更深层级的推荐关系

## 解决方案

### 1. 枚举类升级
修改`UrsPromotionRelationLevel`枚举类：
- 移除固定的三级枚举
- 支持动态的20代关系
- 添加深度相关的辅助方法

### 2. 缓存逻辑优化
升级`UrsRelationCacheLogic`：
- 支持20代关系缓存生成
- 添加深度限制检查
- 优化缓存生成算法

### 3. 查询性能提升
优化`UrsProfitLogic`：
- 支持20代关系查询
- 添加查询日志记录
- 保持降级机制

## 实现详情

### 1. 关系缓存创建时机

#### 自动创建时机
1. **推荐关系建立时**
   - 位置: `UrsReferralService::createReferral()`
   - 触发: 新用户建立推荐关系
   - 范围: 创建完整的20代上级关系缓存

2. **用户进入农场时**
   - 位置: `UrsUserMappingService::createMapping()`
   - 触发: URS用户首次进入农场
   - 范围: 更新缓存中的农场用户ID字段

#### 手动创建时机
1. **命令行重建**
   ```bash
   php artisan urs:rebuild-relation-cache
   php artisan urs:rebuild-relation-cache --check
   php artisan urs:rebuild-relation-cache --fix
   ```

2. **后台管理界面**
   - 路径: `/admin/urs-promotion/user-relation-cache`
   - 功能: 重建缓存、检查完整性

3. **测试工具**
   ```bash
   php artisan urs:test-relation-cache generate --user-id=10016
   php artisan urs:test-relation-cache batch --users=10016,10015
   ```

### 2. 20代关系缓存结构

#### 数据结构
```sql
-- 20代关系缓存示例
user_id | related_user_id | urs_user_id | urs_related_user_id | level | depth | generation
--------|-----------------|-------------|---------------------|-------|-------|------------
39135   | 39134          | 10016       | 10015               | 1     | 1     | 直推
39135   | 39128          | 10016       | 10007               | 2     | 2     | 2级间推
39135   | 39127          | 10016       | 10006               | 2     | 3     | 3级间推
...     | ...            | ...         | ...                 | 2     | 20    | 20级间推
```

#### 层级定义
- **第1代**: 直推关系 (level=1, depth=1)
- **第2-20代**: 间推关系 (level=2, depth=2-20)

### 3. 缓存生成算法

```php
public function generateUserRelationCache(int $ursUserId): bool
{
    // 1. 清除现有缓存
    $this->clearUserRelationCache($ursUserId);
    
    // 2. 创建直接关系缓存（第1代）
    $this->createDirectRelationCache($ursUserId, $referral);
    
    // 3. 获取推荐人的所有上级（最多19级）
    $upperRelations = UrsUserRelationCache::where('urs_user_id', $ursReferrerId)
        ->where('depth', '<', 20)
        ->get();
    
    // 4. 创建间接关系缓存（第2-20代）
    foreach ($upperRelations as $upperRelation) {
        $newDepth = $upperRelation->depth + 1;
        if ($newDepth <= 20) {
            $this->createIndirectRelationCache($ursUserId, $upperRelation, $newDepth);
        }
    }
    
    return true;
}
```

### 4. 查询性能优化

#### 优化前（递归查询）
```php
// 需要20次数据库查询
for ($level = 1; $level <= 20; $level++) {
    $referral = UrsUserReferral::where('user_id', $currentUserId)->first();
    // 每次查询一级关系
}
```

#### 优化后（缓存查询）
```php
// 只需1次数据库查询
$relations = UrsUserRelationCache::where('user_id', $userId)
    ->where('depth', '<=', 20)
    ->orderBy('depth')
    ->get();
// 一次性获取所有20代关系
```

## 测试验证

### 1. 功能测试
✅ 20代关系缓存生成正确
✅ 查询性能显著提升
✅ 后台管理界面正常显示
✅ 命令行工具功能完整

### 2. 性能测试
✅ 单次查询获取20代关系链
✅ 查询响应时间大幅降低
✅ 内存使用合理
✅ 存储空间可控

### 3. 数据验证
```sql
-- 测试查询结果
SELECT 
    depth as level,
    related_user_id as referrer_farm_id,
    urs_related_user_id as referrer_urs_id,
    CASE 
        WHEN depth = 1 THEN '直推'
        ELSE CONCAT(depth, '级间推')
    END as relation_name
FROM kku_urs_promotion_user_relation_cache 
WHERE user_id = 39135 AND depth <= 20
ORDER BY depth;
```

## 文件修改清单

### 核心文件
- `app/Module/UrsPromotion/Enums/UrsPromotionRelationLevel.php` - 支持20代的枚举类
- `app/Module/UrsPromotion/Logics/UrsRelationCacheLogic.php` - 20代缓存生成逻辑
- `app/Module/UrsPromotion/Logics/UrsProfitLogic.php` - 优化的收益分发逻辑
- `app/Module/UrsPromotion/AdminControllers/UrsUserRelationCacheController.php` - 后台管理控制器

### 新增文档
- `app/Module/UrsPromotion/Docs/关系缓存创建时机.md` - 详细的创建时机说明

## 技术特点

### 1. 扩展性强
- 支持20代深度关系
- 可配置的最大深度限制
- 灵活的层级定义

### 2. 性能优异
- 查询复杂度从O(n)降低到O(1)
- 单次查询获取所有关系
- 大幅减少数据库访问

### 3. 维护便捷
- 自动缓存生成和更新
- 完整的管理工具
- 详细的监控和日志

## 业务价值

1. **收益分发优化**: 20代收益分发查询性能大幅提升
2. **团队统计加速**: 快速统计各代团队规模
3. **关系查询高效**: 瞬间获取完整推荐关系链
4. **系统扩展性**: 为更复杂的推广业务奠定基础

## 总结

URS推广模块20代关系缓存机制升级已全面完成。通过支持20代推荐关系，系统不仅满足了当前的业务需求，还为未来的扩展提供了强大的技术支撑。查询性能的大幅提升将显著改善用户体验，为推广业务的发展奠定了坚实的技术基础。