|
|
@@ -0,0 +1,298 @@
|
|
|
+# 实现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()` - 获取活跃用户统计
|
|
|
+
|
|
|
+**活跃判定规则**:
|
|
|
+```php
|
|
|
+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)
|
|
|
+- 详细的执行统计和进度显示
|
|
|
+
|
|
|
+**使用示例**:
|
|
|
+```bash
|
|
|
+# 正常更新
|
|
|
+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配置**:
|
|
|
+```bash
|
|
|
+# 每日凌晨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)
|
|
|
+- 完整功能测试
|
|
|
+
|
|
|
+**使用示例**:
|
|
|
+```bash
|
|
|
+# 运行完整测试
|
|
|
+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`
|
|
|
+
|
|
|
+**内容结构**:
|
|
|
+1. 功能概述和业务价值
|
|
|
+2. 技术实现详细说明
|
|
|
+3. 活跃用户判定规则
|
|
|
+4. 达人等级集成方案
|
|
|
+5. 后台管理功能
|
|
|
+6. API接口说明
|
|
|
+7. 测试和验证方法
|
|
|
+8. 监控和维护建议
|
|
|
+9. 扩展规划
|
|
|
+10. 最佳实践
|
|
|
+
|
|
|
+#### 6.2 用户绑定关系文档更新
|
|
|
+**文件**: `app/Module/UrsPromotion/Docs/用户绑定关系.md`
|
|
|
+
|
|
|
+**更新内容**:
|
|
|
+- 添加活跃用户相关字段说明
|
|
|
+- 补充活跃状态定义
|
|
|
+- 更新数据结构文档
|
|
|
+
|
|
|
+#### 6.3 开发进度记录
|
|
|
+**文件**: `app/Module/UrsPromotion/Docs/DEV.md`
|
|
|
+
|
|
|
+**更新内容**:
|
|
|
+- 详细记录活跃用户功能的实施进度
|
|
|
+- 列出所有新增和修改的文件
|
|
|
+- 总结技术实现要点
|
|
|
+- 提供部署和使用指南
|
|
|
+
|
|
|
+## 技术要点总结
|
|
|
+
|
|
|
+### 1. 设计原则
|
|
|
+- **分离存储**:活跃状态存储在用户映射表中,与推广关系解耦
|
|
|
+- **自动化管理**:通过定时任务自动维护活跃状态
|
|
|
+- **向后兼容**:新增活跃用户条件,不影响现有等级计算
|
|
|
+- **性能优化**:通过索引和批量处理提高查询和更新效率
|
|
|
+
|
|
|
+### 2. 核心算法
|
|
|
+- **活跃判定**:基于last_activity_time字段,15天内有活动即为活跃
|
|
|
+- **等级计算**:在原有条件基础上增加活跃用户数量要求
|
|
|
+- **批量处理**:支持大规模用户的高效批量更新
|
|
|
+
|
|
|
+### 3. 数据一致性
|
|
|
+- **事务保护**:关键操作使用数据库事务确保数据一致性
|
|
|
+- **异常处理**:完善的错误处理和日志记录机制
|
|
|
+- **状态验证**:提供数据验证和修复功能
|
|
|
+
|
|
|
+### 4. 监控和维护
|
|
|
+- **执行日志**:详细记录定时任务的执行情况
|
|
|
+- **统计监控**:提供活跃用户的实时统计和分析
|
|
|
+- **性能监控**:监控批量更新的执行效率
|
|
|
+
|
|
|
+## 部署指南
|
|
|
+
|
|
|
+### 1. 数据库迁移
|
|
|
+```bash
|
|
|
+# 执行数据库迁移脚本
|
|
|
+mysql -u username -p database_name < app/Module/UrsPromotion/Database/add_active_user_fields.sql
|
|
|
+```
|
|
|
+
|
|
|
+### 2. 定时任务配置
|
|
|
+```bash
|
|
|
+# 添加到crontab
|
|
|
+0 2 * * * cd /path/to/project && php artisan urs:update-active-status
|
|
|
+```
|
|
|
+
|
|
|
+### 3. 功能验证
|
|
|
+```bash
|
|
|
+# 运行功能测试
|
|
|
+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推广模块活跃用户功能
|
|
|
+
|
|
|
+## 任务价值
|
|
|
+
|
|
|
+1. **提升推广质量**:通过活跃度筛选,确保推广团队的真实活跃度
|
|
|
+2. **优化激励机制**:基于活跃用户数量的等级体系更加公平合理
|
|
|
+3. **数据驱动决策**:提供详细的活跃用户数据支持运营决策
|
|
|
+4. **防止刷量行为**:通过活跃度要求减少虚假推广行为
|
|
|
+5. **系统完整性**:完善URS推广模块的功能体系
|
|
|
+
|
|
|
+## 后续建议
|
|
|
+
|
|
|
+1. **监控部署**:建立活跃用户功能的监控和告警机制
|
|
|
+2. **性能优化**:根据实际使用情况优化批量处理性能
|
|
|
+3. **功能扩展**:考虑增加更精细的活跃度评分机制
|
|
|
+4. **用户反馈**:收集用户对新等级要求的反馈并适时调整
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+**任务完成时间**: 2025年06月16日 16:13
|
|
|
+**功能开发状态**: ✅ 已完成
|