kknongchang_2506/app/Module/AppGame/Handler/Promotion/README.md

推广数据获取Handler

概述

本目录包含客户端推广数据获取的Handler实现，用于对接URS推广模块，为客户端提供推广团队信息和成员列表数据。

Handler列表

1. InfoHandler - 推广团队信息

请求: RequestPromotionInfo 响应: ResponsePromotionInfo 路由: promotion-info

功能说明

获取用户的推广团队统计信息，包括：

• 总人数、直推人数、间推人数
• 今日新增统计（团队新增、直推新增）
• 团队活跃人数统计（24小时内活跃）

业务逻辑

1. 通过UrsUserMappingService将农场用户ID转换为URS用户ID
2. 如果用户未进入URS推广系统，返回空数据
3. 调用UrsReferralService获取推广关系统计
4. 计算今日新增数据（基于映射创建时间）
5. 计算活跃用户数据（基于用户最后活动时间）

响应字段

• total_count: 总人数
• direct_count: 直推人数
• indirect_count: 间推人数
• day_recent_count: 今日团队新增
• day_direct_count: 今日直推新增
• active_count: 团队活跃人数
• direct_active_count: 直推活跃人数
• today_reward: 今日收益（推广收益和种植收益）
• total_reward: 总收益（推广收益和种植收益）
• star_level: 达人等级（0=无等级，1-5=对应达人等级）

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

请求: RequestPromotionList 响应: ResponsePromotionList 路由: promotion-list

功能说明

获取用户的推广团队成员列表，支持：

• 分页查询（最大100条/页）
• 等级筛选（0=全部，1=直推，2=间推，3=三推）
• 只返回已进入农场的用户数据

业务逻辑

1. 通过UrsUserMappingService将农场用户ID转换为URS用户ID
2. 如果用户未进入URS推广系统，返回空列表
3. 调用UrsReferralService获取团队成员
4. 根据等级参数筛选成员
5. 过滤出已进入农场的用户（通过映射关系）
6. 分页处理并获取用户详细信息

请求参数

• page: 分页信息
  • page: 页码（从1开始）
  • per_page: 每页数量（默认20，最大100）
• level: 等级筛选（0=全部，1=直推，2=间推，3=三推）

响应字段

• page: 分页信息
  • current_page: 当前页码
  • per_page: 每页数量
  • total: 总记录数
  • last_page: 总页数
  • has_more: 是否有下一页
• list: 成员列表
  • user_id: 用户ID（农场用户ID）
  • nickname: 昵称
  • avatar: 头像
  • fund2: 财富（钻石余额，整数显示）
  • contribution: 贡献值（暂时为0）
  • house_level: 房屋等级

数据来源

URS推广模块

• UrsUserMappingService: 用户映射关系管理
• UrsReferralService: 推荐关系管理
• UrsTalentService: 达人等级管理

用户模块

• UserService: 用户基本信息
• UserActivityService: 用户活动时间

资金模块

• AccountService: 用户资金账户信息

农场模块

• FarmUser: 用户房屋等级信息

重要特性

1. 数据过滤

• 只返回已进入农场的用户数据
• 未进入农场的用户会被跳过，不影响统计

2. 错误处理

• 用户未进入URS推广系统时返回空数据
• 发生异常时返回空数据，不影响客户端正常运行
• 详细的错误日志记录

3. 性能优化

• 批量获取用户信息
• 合理的分页限制
• 缓存友好的数据结构

4. 活跃度统计

• 基于用户最后活动时间（24小时内）
• 自动更新用户活动时间

测试

使用测试命令验证Handler功能：

php artisan test:promotion-handler {user_id}

示例：

php artisan test:promotion-handler 8001

注意事项

1. 用户映射关系: 必须确保用户已通过UrsUserMappingService建立映射关系
2. 数据一致性: 推广关系数据来自URS推广模块，需要保持数据同步
3. 权限控制: Handler需要用户登录，会自动更新用户活动时间
4. 财富显示: 钻石余额转换为整数显示（乘以10^10）
5. 分页限制: 最大支持100条/页，防止数据量过大

相关文档

• URS推广模块文档
• 用户活动时间功能
• 资金模块文档