实现URS推广模块活跃用户功能

任务时间: 2025年06月16日 16:13
任务类型: 功能开发
模块: UrsPromotion

任务概述

为URS推广模块新增活跃用户概念，将用户活跃度作为达人等级升级的新条件，提升推广体系的质量和真实性。

需求背景

活跃用户定义：最近15天操作活跃的人（基于last_activity_time）
存储位置：用户绑定关系表（urs_promotion_user_mappings）
更新机制：每日定时任务更新活跃状态
业务影响：达人等级新增活跃人数条件

完成内容

1. 数据库结构扩展

1.1 用户映射表扩展

文件: app/Module/UrsPromotion/Database/add_active_user_fields.sql

新增字段:

is_active TINYINT(1) - 是否活跃:1活跃,0不活跃
last_activity_check TIMESTAMP - 最后活跃检查时间
active_days_count INT - 活跃天数统计

索引优化:

idx_is_active - 活跃状态索引
idx_last_activity_check - 检查时间索引

1.2 达人等级配置表扩展

新增字段:

active_count_required INT - 所需活跃人数
active_direct_required INT - 所需直推活跃人数

配置示例: | 等级 | 名称 | 直推要求 | 团队要求 | 活跃直推要求 | 活跃团队要求 | |------|------|----------|----------|--------------|--------------| | 1 | 初级达人 | 3 | 10 | 2 | 3 | | 2 | 中级达人 | 8 | 30 | 5 | 8 | | 3 | 高级达人 | 15 | 80 | 8 | 15 | | 4 | 资深达人 | 30 | 200 | 15 | 30 | | 5 | 顶级达人 | 50 | 500 | 25 | 50 |

2. 核心服务实现

2.1 UrsActiveUserService (新增)

文件: app/Module/UrsPromotion/Services/UrsActiveUserService.php

核心方法:

updateUserActiveStatus() - 更新单个用户活跃状态
batchUpdateActiveStatus() - 批量更新活跃状态
checkUserActivity() - 检查用户活跃状态
getActiveTeamMembers() - 获取活跃团队成员
getActiveUserStats() - 获取活跃用户统计

活跃判定规则:

const ACTIVE_DAYS_THRESHOLD = 15; // 活跃天数阈值

public static function checkUserActivity(User $user): bool
{
    if (!$user->last_activity_time) {
        return false;
    }
    
    $threshold = Carbon::now()->subDays(self::ACTIVE_DAYS_THRESHOLD);
    return $user->last_activity_time >= $threshold;
}

2.2 模型扩展

UrsUserMapping模型更新:

新增活跃状态相关字段和类型转换
添加活跃状态常量和映射
实现活跃用户查询方法
支持批量更新活跃状态

UrsTalentConfig模型更新:

新增活跃人数配置字段
更新字段类型转换

2.3 服务层集成

UrsTalentService扩展:

更新calculateTalentLevel()方法，集成活跃用户条件
更新checkUpgradeEligibility()方法，检查活跃用户要求
支持活跃直推人数和活跃团队人数条件

UrsUserMappingService扩展:

添加活跃用户统计方法
支持批量更新活跃状态
提供活跃用户查询接口

3. 定时任务实现

3.1 UrsUpdateActiveStatusCommand

文件: app/Module/UrsPromotion/Commands/UrsUpdateActiveStatusCommand.php

功能特性:

支持批量更新用户活跃状态
提供试运行模式（--dry-run）
支持限制处理数量（--limit）
支持重置所有状态（--reset）
详细的执行统计和进度显示

使用示例:

# 正常更新
php artisan urs:update-active-status

# 限制处理500个用户
php artisan urs:update-active-status --limit=500

# 试运行模式
php artisan urs:update-active-status --dry-run

# 重置所有状态
php artisan urs:update-active-status --reset

建议crontab配置:

# 每日凌晨2点执行
0 2 * * * cd /path/to/project && php artisan urs:update-active-status

4. 后台管理界面

4.1 用户映射关系管理

文件: app/Module/UrsPromotion/AdminControllers/UrsUserMappingController.php

新增功能:

列表页面显示活跃状态、活跃天数、最后检查时间
支持按活跃状态筛选
详情页面显示完整的活跃用户信息
活跃状态使用颜色标签区分

4.2 达人等级配置管理

文件: app/Module/UrsPromotion/AdminControllers/UrsTalentConfigController.php

新增功能:

配置表单支持设置活跃用户要求
列表页面显示活跃人数要求
详情页面显示活跃用户要求信息
提供活跃用户定义的帮助信息

5. 测试验证

5.1 TestActiveUserCommand

文件: app/Module/UrsPromotion/Commands/TestActiveUserCommand.php

测试功能:

活跃用户统计测试（--stats）
活跃状态更新测试（--update）
达人等级计算测试（--talent）
指定用户测试（--user-id）
完整功能测试

使用示例:

# 运行完整测试
php artisan urs:test-active-user

# 测试活跃用户统计
php artisan urs:test-active-user --stats

# 测试指定用户
php artisan urs:test-active-user --user-id=1001

6. 文档完善

6.1 活跃用户功能文档

文件: app/Module/UrsPromotion/Docs/活跃用户功能.md

内容结构:

功能概述和业务价值
技术实现详细说明
活跃用户判定规则
达人等级集成方案
后台管理功能
API接口说明
测试和验证方法
监控和维护建议
扩展规划
最佳实践

6.2 用户绑定关系文档更新

文件: app/Module/UrsPromotion/Docs/用户绑定关系.md

更新内容:

添加活跃用户相关字段说明
补充活跃状态定义
更新数据结构文档

6.3 开发进度记录

文件: app/Module/UrsPromotion/Docs/DEV.md

更新内容:

详细记录活跃用户功能的实施进度
列出所有新增和修改的文件
总结技术实现要点
提供部署和使用指南

技术要点总结

1. 设计原则

分离存储：活跃状态存储在用户映射表中，与推广关系解耦
自动化管理：通过定时任务自动维护活跃状态
向后兼容：新增活跃用户条件，不影响现有等级计算
性能优化：通过索引和批量处理提高查询和更新效率

2. 核心算法

活跃判定：基于last_activity_time字段，15天内有活动即为活跃
等级计算：在原有条件基础上增加活跃用户数量要求
批量处理：支持大规模用户的高效批量更新

3. 数据一致性

事务保护：关键操作使用数据库事务确保数据一致性
异常处理：完善的错误处理和日志记录机制
状态验证：提供数据验证和修复功能

4. 监控和维护

执行日志：详细记录定时任务的执行情况
统计监控：提供活跃用户的实时统计和分析
性能监控：监控批量更新的执行效率

部署指南

1. 数据库迁移

# 执行数据库迁移脚本
mysql -u username -p database_name < app/Module/UrsPromotion/Database/add_active_user_fields.sql

2. 定时任务配置

# 添加到crontab
0 2 * * * cd /path/to/project && php artisan urs:update-active-status

3. 功能验证

# 运行功能测试
php artisan urs:test-active-user

# 试运行活跃状态更新
php artisan urs:update-active-status --dry-run

文件清单

新增文件

app/Module/UrsPromotion/Services/UrsActiveUserService.php
app/Module/UrsPromotion/Commands/UrsUpdateActiveStatusCommand.php
app/Module/UrsPromotion/Commands/TestActiveUserCommand.php
app/Module/UrsPromotion/Database/add_active_user_fields.sql
app/Module/UrsPromotion/Docs/活跃用户功能.md

修改文件

app/Module/UrsPromotion/Models/UrsUserMapping.php
app/Module/UrsPromotion/Models/UrsTalentConfig.php
app/Module/UrsPromotion/Services/UrsTalentService.php
app/Module/UrsPromotion/Services/UrsUserMappingService.php
app/Module/UrsPromotion/AdminControllers/UrsUserMappingController.php
app/Module/UrsPromotion/AdminControllers/UrsTalentConfigController.php
app/Module/UrsPromotion/Docs/用户绑定关系.md
app/Module/UrsPromotion/Docs/DEV.md

提交信息

Git提交: ae0723a5
提交信息: 实现URS推广模块活跃用户功能

任务价值

提升推广质量：通过活跃度筛选，确保推广团队的真实活跃度
优化激励机制：基于活跃用户数量的等级体系更加公平合理
数据驱动决策：提供详细的活跃用户数据支持运营决策
防止刷量行为：通过活跃度要求减少虚假推广行为
系统完整性：完善URS推广模块的功能体系

后续建议

监控部署：建立活跃用户功能的监控和告警机制
性能优化：根据实际使用情况优化批量处理性能
功能扩展：考虑增加更精细的活跃度评分机制
用户反馈：收集用户对新等级要求的反馈并适时调整

任务完成时间: 2025年06月16日 16:13
功能开发状态: ✅ 已完成

161613-实现URS推广模块活跃用户功能.md 8.9 KB Permalink History Raw