URS达人等级逻辑修改 - 扩展团队统计到20代

任务概述

修改URS推广模块的达人等级逻辑，将团队总人数和活跃团队总人数的统计范围从3代扩展到20代，并在文档中增加三代人数和三代活跃人数指标。

任务时间

开始时间：2025年07月03日 14:37:38 CST
完成时间：2025年07月03日 15:20:00 CST
总耗时：约43分钟

任务背景

用户需求：达人升级指标逻辑变更，团队总人数统计20代，活跃团队总人数也统计二十代的活跃人数。同时需要在文档中增加三代人数/三代活跃人数指标，当前阶段数值先等于团队人数/团队活跃人数。

修改内容

1. 代码修改

1.1 UrsReferralService.php

修改getTeamMembers()方法：
- 默认maxLevels参数从3改为使用UrsPromotionRelationLevel::getTeamStatsDepth()
- 支持null参数，自动使用配置的20代深度
- 更新方法注释说明支持20代统计
修改updateReferrerStats()方法：
- 使用20代团队成员统计
- 重构团队总人数计算逻辑，支持动态层级统计
- 更新注释说明

1.2 UrsActiveUserService.php

修改getActiveTeamMembers()方法：
- 调用UrsReferralService::getTeamMembers()时使用默认20代深度
- 更新注释说明支持达人等级统计

1.3 UrsTalentLogic.php

重构calculateTeamStats()方法：
- 增加getAllTeamMembers()私有方法支持20代递归统计
- 修改promotion_count计算逻辑，使用20代总人数
- 保持直推、间推、三推的单独统计不变
新增getAllTeamMembers()方法：
- 支持动态层级参数，默认使用配置的团队统计深度
- 递归获取所有团队成员，支持20代深度
- 返回去重后的用户ID数组

1.4 UrsPromotionRelationLevel.php

新增getTeamStatsDepth()方法：
- 返回团队统计深度常量20
- 专门用于达人等级计算的团队统计

2. 文档更新

2.1 达人等级逻辑.md

更新等级结构表：
- 增加"三代人数要求"和"三代活跃要求"列
- 明确标注团队要求和活跃团队要求为20代统计
- 当前阶段三代人数要求等于团队要求
更新升级条件说明：
- 从4个条件扩展到6个条件
- 增加三代人数和三代活跃人数条件
- 区分20代统计和3代统计的应用场景
更新算法示例：
- calculateTalentLevel方法增加三代统计参数
- 完善条件检查逻辑
增加统计指标说明：
- 详细说明20代和3代统计的区别
- 解释指标设计的业务价值
- 说明当前阶段的数值设置策略
更新数据库表结构：
- 增加three_gen_count_required字段
- 增加three_gen_active_required字段
完善配置管理方法：
- 更新meetsRequirements方法支持全部6个条件检查

3. 测试验证

3.1 功能测试

后台管理界面测试：
- 访问URS达人等级管理页面正常
- 点击"更新等级"按钮功能正常
- 显示"达人等级更新成功"消息
数据验证：
- 团队统计数据重新计算正确
- 20代统计逻辑生效
- 等级更新功能正常工作

3.2 单元测试

创建UrsTeamStatsTest.php：
- 测试团队统计深度配置
- 测试getTeamMembers默认参数
- 测试活跃团队成员统计
- 测试层级名称生成和验证

技术要点

1. 向后兼容性

保持原有API接口不变
支持显式传入层级参数
默认使用新的20代配置

2. 性能考虑

递归统计使用循环实现，避免栈溢出
支持提前终止，当没有下级时停止查询
使用数组去重确保数据准确性

3. 配置化设计

通过枚举类提供配置常量
便于后续调整统计深度
代码可维护性强

4. 数据一致性

所有相关方法统一使用新的配置
确保团队统计数据的一致性
保持直推、间推、三推的传统统计

业务影响

1. 正面影响

更全面的团队评估：20代统计提供更完整的团队规模数据
激励深度推广：鼓励用户发展更深层的推广网络
数据准确性提升：统计范围扩大，数据更真实
业务扩展性：为未来业务发展预留空间

2. 注意事项

数据变化：现有用户的团队统计数据可能发生变化
等级影响：部分用户的达人等级可能受到影响
性能监控：需要关注20代统计的查询性能

提交记录

Commit 1: `4111f41b`

修改URS达人等级逻辑：扩展团队统计到20代

- 修改UrsReferralService::getTeamMembers()默认参数从3代改为20代
- 修改UrsActiveUserService::getActiveTeamMembers()使用20代统计
- 重构UrsTalentLogic::calculateTeamStats()支持20代递归统计
- 在UrsPromotionRelationLevel枚举中添加getTeamStatsDepth()常量方法
- 更新updateReferrerStats()方法计算20代总人数
- 所有团队统计现在支持20代深度，提升达人等级计算准确性

Commit 2: `51b0cf7b`

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

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

文件变更清单

修改的文件

app/Module/UrsPromotion/Services/UrsReferralService.php
app/Module/UrsPromotion/Services/UrsActiveUserService.php
app/Module/UrsPromotion/Logics/UrsTalentLogic.php
app/Module/UrsPromotion/Enums/UrsPromotionRelationLevel.php
app/Module/UrsPromotion/Docs/达人等级逻辑.md
AiWork/now.md

新增的文件

tests/Unit/UrsPromotion/UrsTeamStatsTest.php

后续建议

1. 监控和优化

监控20代统计查询的性能表现
关注用户等级变化情况
收集用户反馈，优化统计逻辑

2. 功能完善

考虑实现三代人数和三代活跃人数的独立统计
优化批量更新等级的性能
增加更详细的统计分析功能

3. 文档维护

持续更新文档，保持与代码同步
增加更多使用示例和最佳实践
完善错误处理和异常情况说明

总结

本次任务成功完成了URS达人等级逻辑的重要升级，将团队统计从3代扩展到20代，为业务发展提供了更强大的数据支持。同时通过文档更新，为未来的三代统计功能预留了扩展空间。整个修改过程保持了向后兼容性，确保了系统的稳定性和可维护性。

031450-URS达人等级逻辑修改扩展团队统计到20代.md 6.8 KB Permalink History Raw