kknongchang_2506/AiWork/202506/161222-实现推广数据获取Handler.md

实现推广数据获取Handler

创建时间: 2025年06月16日 12:22
任务类型: 功能开发
关联模块: AppGame、UrsPromotion

任务概述

为客户端推广数据获取需求实现两个Handler：RequestPromotionInfo和RequestPromotionList，对接URS推广模块，只返回已进入农场的用户数据。

实现内容

1. InfoHandler - 推广团队信息

文件: app/Module/AppGame/Handler/Promotion/InfoHandler.php

功能特性

• 获取用户推广团队统计信息
• 支持总人数、直推人数、间推人数统计
• 计算今日新增数据（基于映射创建时间）
• 计算活跃用户数据（24小时内活跃）
• 自动更新用户活动时间

响应字段

• total_count: 总人数
• direct_count: 直推人数
  
• indirect_count: 间推人数
• day_recent_count: 今日团队新增
• day_direct_count: 今日直推新增
• active_count: 团队活跃人数
• direct_active_count: 直推活跃人数

2. ListHandler - 推广团队成员列表

文件: app/Module/AppGame/Handler/Promotion/ListHandler.php

功能特性

• 获取用户推广团队成员列表
• 支持分页查询（最大100条/页）
• 支持等级筛选（0=全部，1=直推，2=间推，3=三推）
• 只返回已进入农场的用户数据
• 包含用户详细信息（昵称、头像、财富、房屋等级）

响应数据

• 分页信息（当前页、每页数量、总记录数、总页数、是否有下一页）
• 成员列表（用户ID、昵称、头像、钻石余额、贡献值、房屋等级）

3. 测试命令

文件: app/Module/AppGame/Commands/TestPromotionHandlerCommand.php

功能

• 验证Handler功能正确性
• 测试用户映射关系
• 测试推广信息获取
• 测试推广列表获取
• 详细的输出信息

使用方法

php artisan test:promotion-handler {user_id}

4. 文档

文件: app/Module/AppGame/Handler/Promotion/README.md

完整的Handler使用文档，包括：

• 功能说明
• 业务逻辑
• 请求响应格式
• 数据来源
• 重要特性
• 测试方法
• 注意事项

技术实现

数据来源集成

• UrsPromotion模块: 推广关系和用户映射
• User模块: 用户基本信息和活动时间
• Fund模块: 用户资金账户信息
• Farm模块: 用户房屋等级信息

关键特性

1. 数据过滤: 只返回已进入农场的用户
2. 错误处理: 完善的异常处理和日志记录
3. 性能优化: 批量获取和合理分页
4. 活跃度统计: 基于用户最后活动时间

修复问题

• 修复UserActivityService中STATUS枚举类型错误
• 修复protobuf分页字段名称问题
• 完善错误处理机制

测试结果

使用用户ID 8001进行测试：

InfoHandler测试结果

推广信息获取成功:
- 总人数: 2
- 直推人数: 2
- 间推人数: 0
- 今日团队新增: 2
- 今日直推新增: 2
- 团队活跃人数: 0
- 直推活跃人数: 0

ListHandler测试结果

推广列表获取成功:
- 当前页: 1
- 每页大小: 10
- 总记录数: 2
- 总页数: 1
- 是否有下一页: 否
- 当前页记录数: 2
  第1条:
    用户ID: 38997
    昵称: 用户**9002
    头像: 
    财富: 0
    贡献: 0
    房屋等级: 1
  第2条:
    用户ID: 38998
    昵称: 用户**9003
    头像: 
    财富: 0
    贡献: 0
    房屋等级: 1

文件清单

新增文件

• app/Module/AppGame/Handler/Promotion/InfoHandler.php
• app/Module/AppGame/Handler/Promotion/ListHandler.php
• app/Module/AppGame/Commands/TestPromotionHandlerCommand.php
• app/Module/AppGame/Handler/Promotion/README.md

修改文件

• app/Module/AppGame/Providers/AppGameServiceProvider.php - 注册测试命令
• app/Module/User/Services/UserActivityService.php - 修复枚举类型错误

部署说明

1. Handler已按照AppGame模块的命名规范创建
2. 路由会自动根据Handler类名生成：
   • promotion-info -> InfoHandler
   • promotion-list -> ListHandler
3. 需要确保用户已建立URS映射关系
4. 测试命令已注册，可直接使用

后续优化

1. 可考虑添加缓存机制提升性能
2. 可扩展贡献值计算逻辑
3. 可添加更多筛选条件
4. 可优化批量数据获取效率

总结

成功实现了推广数据获取的两个Handler，完整对接了URS推广模块，提供了完善的测试和文档。Handler具有良好的错误处理机制和性能优化，能够满足客户端推广数据获取的需求。