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

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

任务背景

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

问题分析

原有限制

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

解决方案

1. 枚举类升级

修改UrsPromotionRelationLevel枚举类：

移除固定的三级枚举
支持动态的20代关系
添加深度相关的辅助方法

2. 缓存逻辑优化

升级UrsRelationCacheLogic：

支持20代关系缓存生成
添加深度限制检查
优化缓存生成算法

3. 查询性能提升

优化UrsProfitLogic：

支持20代关系查询
添加查询日志记录
保持降级机制

实现详情

1. 关系缓存创建时机

自动创建时机

推荐关系建立时
- 位置: UrsReferralService::createReferral()
- 触发: 新用户建立推荐关系
- 范围: 创建完整的20代上级关系缓存
用户进入农场时
- 位置: UrsUserMappingService::createMapping()
- 触发: URS用户首次进入农场
- 范围: 更新缓存中的农场用户ID字段

手动创建时机

命令行重建

php artisan urs:rebuild-relation-cache
php artisan urs:rebuild-relation-cache --check
php artisan urs:rebuild-relation-cache --fix

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

测试工具

php artisan urs:test-relation-cache generate --user-id=10016
php artisan urs:test-relation-cache batch --users=10016,10015

2. 20代关系缓存结构

数据结构

-- 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. 缓存生成算法

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. 查询性能优化

优化前（递归查询）

// 需要20次数据库查询
for ($level = 1; $level <= 20; $level++) {
    $referral = UrsUserReferral::where('user_id', $currentUserId)->first();
    // 每次查询一级关系
}

优化后（缓存查询）

// 只需1次数据库查询
$relations = UrsUserRelationCache::where('user_id', $userId)
    ->where('depth', '<=', 20)
    ->orderBy('depth')
    ->get();
// 一次性获取所有20代关系

测试验证

1. 功能测试

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

2. 性能测试

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

3. 数据验证

-- 测试查询结果
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. 维护便捷

自动缓存生成和更新
完整的管理工具
详细的监控和日志

业务价值

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

总结

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

031415-URS推广模块20代关系缓存机制升级.md 6.0 KB Permalink History Raw