# URS达人等级更新命令输出优化

## 任务概述

**时间**: 2025年07月05日 03:54  
**任务**: 优化URS达人等级更新命令的输出，增加活跃直推数据显示  
**问题**: 用户39296没有升级，需要查看详细的升级条件和活跃用户数据

## 问题分析

### 1. 初始问题
- 用户39296有521个直推，691个团队总人数，但达人等级仍为0（青铜）
- 命令输出信息不够详细，无法看到活跃用户数据和升级条件

### 2. 根本原因
- **活跃用户数据缺失**: UrsActiveUserService中checkUserActivity方法使用了不存在的last_activity_time字段
- **活动时间字段位置错误**: 活动时间在UserInfo表中，不在User表中
- **命令注册缺失**: UrsUpdateActiveStatusCommand没有在ServiceProvider中注册
- **输出信息不完整**: 缺少活跃用户数据和升级条件详情

## 解决方案

### 1. 修复活跃用户检查逻辑

#### 1.1 修正活动时间字段访问
**文件**: `app/Module/UrsPromotion/Services/UrsActiveUserService.php`

```php
// 修改前：直接访问User模型的last_activity_time（不存在）
if (!$user->last_activity_time) {
    return false;
}

// 修改后：通过UserInfo关联访问
$userInfo = $user->info;
if (!$userInfo || !$userInfo->last_activity_time) {
    return false;
}
```

#### 1.2 优化数据预加载
**文件**: `app/Module/UrsPromotion/Models/UrsUserMapping.php`

```php
// 在getUsersNeedActivityCheck方法中预加载用户信息关联
->with(['user', 'user.info']) // 预加载用户和用户信息关联
```

### 2. 添加活跃直推专用方法

#### 2.1 新增getActiveDirectMembers方法
**文件**: `app/Module/UrsPromotion/Services/UrsActiveUserService.php`

```php
/**
 * 获取指定URS用户的活跃直推成员（仅直推层级）
 * 
 * 针对达人等级升级条件优化，只统计直推活跃用户
 * 相比getActiveTeamMembers方法，此方法只关注直推层级，性能更优
 */
public static function getActiveDirectMembers(int $ursUserId): array
{
    // 只获取直推成员（第1层级）
    $directMembers = UrsReferralService::getDirectReferrals($ursUserId);
    
    if (empty($directMembers)) {
        return [
            'active_direct_count' => 0,
            'active_direct_members' => []
        ];
    }
    
    // 获取活跃的直推成员
    $activeDirectIds = UrsUserMapping::getActiveUrsUserIds($directMembers);
    
    return [
        'active_direct_count' => count($activeDirectIds),
        'active_direct_members' => $activeDirectMembers
    ];
}
```

### 3. 注册活跃状态更新命令

#### 3.1 添加命令注册
**文件**: `app/Module/UrsPromotion/Providers/UrsPromotionServiceProvider.php`

```php
$this->commands([
    // ... 其他命令
    \App\Module\UrsPromotion\Commands\UrsUpdateActiveStatusCommand::class,
]);
```

### 4. 扩展DTO支持活跃数据

#### 4.1 扩展UrsUserTalentDto
**文件**: `app/Module/UrsPromotion/Dtos/UrsUserTalentDto.php`

```php
/**
 * @var int 活跃直推人数
 */
public int $activeDirectCount = 0;

/**
 * @var int 活跃团队总人数
 */
public int $activeTotalCount = 0;

// 修改fromModel方法签名，支持活跃数据参数
public static function fromModel(
    UrsUserTalent $model, 
    ?array $currentConfig = null, 
    ?array $nextConfig = null, 
    int $activeDirectCount = 0, 
    int $activeTotalCount = 0
): self
```

#### 4.2 修改服务层传递活跃数据
**文件**: `app/Module/UrsPromotion/Services/UrsTalentService.php`

```php
// 获取活跃直推成员统计（优化性能，只获取直推活跃数据）
$activeDirectStats = UrsActiveUserService::getActiveDirectMembers($ursUserId);

// 为了显示完整信息，也获取活跃团队总数
$activeTeamStats = UrsActiveUserService::getActiveTeamMembers($ursUserId);

// 在创建DTO时传递活跃数据
return UrsUserTalentDto::fromModel(
    $talent, 
    $currentConfig, 
    $nextConfigArray,
    $activeDirectStats['active_direct_count'],
    $activeTeamStats['active_total_count']
);
```

### 5. 优化命令输出显示

#### 5.1 重新设计输出格式
**文件**: `app/Module/UrsPromotion/Commands/UrsUpdateTalentLevelCommand.php`

新的输出包含：
1. **基础信息表格**: URS用户ID、达人等级、等级名称、最后更新时间
2. **团队统计表格**: 显示总数、活跃数、活跃率
3. **升级条件检查**: 显示下一等级的要求和当前状态

```php
// 团队统计表格
$this->table(['统计项', '总数', '活跃数', '活跃率'], [
    [
        '直推人数', 
        $talentDto->directCount, 
        $talentDto->activeDirectCount,
        $talentDto->directCount > 0 ? round($talentDto->activeDirectCount * 100 / $talentDto->directCount, 1) . '%' : '0%'
    ],
    // ... 其他统计项
]);

// 升级条件检查
$this->table(['条件', '要求', '当前', '状态'], [
    [
        '直推人数',
        $nextLevel['direct_count_required'],
        $talentDto->directCount,
        $directMet ? '✅ 已满足' : '❌ 未满足'
    ],
    [
        '活跃直推',
        $nextLevel['active_direct_required'] ?? 0,
        $talentDto->activeDirectCount,
        $activeDirectMet ? '✅ 已满足' : '❌ 未满足'
    ]
]);
```

## 执行结果

### 1. 活跃状态更新成功
```bash
php artisan urs:update-active-status --limit=50
# 成功更新50个用户，其中50个被标记为活跃
```

### 2. 用户39296成功升级
```bash
php artisan urs:update-talent-level 39296
```

**结果**:
- **等级**: 从0（青铜）升级到1（白银）
- **直推**: 521人（112人活跃，21.5%活跃率）
- **团队**: 691人（235人活跃，34%活跃率）
- **下一等级条件**:
  - 直推人数: 521/500 ✅ 已满足
  - 团队总人数: 691/3000 ❌ 未满足
  - 活跃直推: 112/500 ❌ 未满足

## 技术改进

### 1. 性能优化
- 新增`getActiveDirectMembers`方法，只查询直推活跃用户，避免查询整个团队
- 预加载用户信息关联，减少N+1查询问题

### 2. 代码质量
- 修复了活动时间字段访问错误
- 扩展DTO支持活跃数据传递
- 优化命令输出，信息更加详细和直观

### 3. 用户体验
- 清晰显示活跃率统计
- 详细的升级条件检查
- 直观的状态标识（✅❌）

## 后续建议

1. **定时任务**: 建议每日运行`urs:update-active-status`更新用户活跃状态
2. **监控**: 关注活跃用户比例，如果过低需要检查活动时间更新机制
3. **优化**: 可以考虑增加缓存机制，提高大批量用户等级更新的性能

## 相关文件

- `app/Module/UrsPromotion/Services/UrsActiveUserService.php`
- `app/Module/UrsPromotion/Services/UrsTalentService.php`
- `app/Module/UrsPromotion/Dtos/UrsUserTalentDto.php`
- `app/Module/UrsPromotion/Commands/UrsUpdateTalentLevelCommand.php`
- `app/Module/UrsPromotion/Models/UrsUserMapping.php`
- `app/Module/UrsPromotion/Providers/UrsPromotionServiceProvider.php`