# 推广数据获取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功能：

```bash
php artisan test:promotion-handler {user_id}
```

示例：
```bash
php artisan test:promotion-handler 8001
```

## 注意事项

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

## 相关文档

- [URS推广模块文档](../../UrsPromotion/README.md)
- [用户活动时间功能](../../User/Docs/用户活动时间功能.md)
- [资金模块文档](../../Fund/README.md)