|
|
@@ -0,0 +1,167 @@
|
|
|
+# 实现推广数据获取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功能正确性
|
|
|
+- 测试用户映射关系
|
|
|
+- 测试推广信息获取
|
|
|
+- 测试推广列表获取
|
|
|
+- 详细的输出信息
|
|
|
+
|
|
|
+#### 使用方法
|
|
|
+```bash
|
|
|
+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具有良好的错误处理机制和性能优化，能够满足客户端推广数据获取的需求。
|
notfff