whale-town-end/src/business/user-mgmt/controllers/user-status.controller.ts

/**
 * 用户状态管理控制器
 * 
 * 功能描述：
 * - 管理员管理用户账户状态
 * - 支持批量状态操作
 * - 提供状态变更审计日志
 * 
 * API端点：
 * - PUT /admin/users/:id/status - 修改用户状态
 * - POST /admin/users/batch-status - 批量修改用户状态
 * - GET /admin/users/status-stats - 获取用户状态统计
 * 
 * @author kiro-ai
 * @version 1.0.0
 * @since 2025-12-24
 */

import { Body, Controller, Get, HttpCode, HttpStatus, Param, Put, Post, UseGuards, ValidationPipe, UsePipes, Logger } from '@nestjs/common';
import { ApiBearerAuth, ApiBody, ApiOperation, ApiParam, ApiResponse, ApiTags } from '@nestjs/swagger';
import { AdminGuard } from '../../admin/guards/admin.guard';
import { UserManagementService } from '../services/user-management.service';
import { Throttle, ThrottlePresets } from '../../../core/security_core/decorators/throttle.decorator';
import { Timeout, TimeoutPresets } from '../../../core/security_core/decorators/timeout.decorator';
import { UserStatusDto, BatchUserStatusDto } from '../dto/user-status.dto';
import { UserStatusResponseDto, BatchUserStatusResponseDto, UserStatusStatsResponseDto } from '../dto/user-status-response.dto';

@ApiTags('user-management')
@Controller('admin/users')
export class UserStatusController {
  private readonly logger = new Logger(UserStatusController.name);

  constructor(private readonly userManagementService: UserManagementService) {}

  /**
   * 修改用户状态
   * 
   * @param id 用户ID
   * @param userStatusDto 状态修改数据
   * @returns 修改结果
   */
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ 
    summary: '修改用户状态', 
    description: '管理员修改指定用户的账户状态，支持激活、锁定、禁用等操作' 
  })
  @ApiParam({ name: 'id', description: '用户ID' })
  @ApiBody({ type: UserStatusDto })
  @ApiResponse({ 
    status: 200, 
    description: '状态修改成功', 
    type: UserStatusResponseDto 
  })
  @ApiResponse({ 
    status: 403, 
    description: '权限不足' 
  })
  @ApiResponse({ 
    status: 404, 
    description: '用户不存在' 
  })
  @ApiResponse({ 
    status: 429, 
    description: '操作过于频繁' 
  })
  @UseGuards(AdminGuard)
  @Throttle(ThrottlePresets.ADMIN_OPERATION)
  @Timeout(TimeoutPresets.NORMAL)
  @Put(':id/status')
  @HttpCode(HttpStatus.OK)
  @UsePipes(new ValidationPipe({ transform: true }))
  async updateUserStatus(
    @Param('id') id: string, 
    @Body() userStatusDto: UserStatusDto
  ): Promise<UserStatusResponseDto> {
    this.logger.log('管理员修改用户状态', {
      operation: 'update_user_status',
      userId: id,
      newStatus: userStatusDto.status,
      reason: userStatusDto.reason,
      timestamp: new Date().toISOString()
    });

    return await this.userManagementService.updateUserStatus(BigInt(id), userStatusDto);
  }

  /**
   * 批量修改用户状态
   * 
   * @param batchUserStatusDto 批量状态修改数据
   * @returns 批量修改结果
   */
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ 
    summary: '批量修改用户状态', 
    description: '管理员批量修改多个用户的账户状态' 
  })
  @ApiBody({ type: BatchUserStatusDto })
  @ApiResponse({ 
    status: 200, 
    description: '批量修改成功', 
    type: BatchUserStatusResponseDto 
  })
  @ApiResponse({ 
    status: 403, 
    description: '权限不足' 
  })
  @ApiResponse({ 
    status: 429, 
    description: '操作过于频繁' 
  })
  @UseGuards(AdminGuard)
  @Throttle(ThrottlePresets.ADMIN_OPERATION)
  @Timeout(TimeoutPresets.SLOW)
  @Post('batch-status')
  @HttpCode(HttpStatus.OK)
  @UsePipes(new ValidationPipe({ transform: true }))
  async batchUpdateUserStatus(
    @Body() batchUserStatusDto: BatchUserStatusDto
  ): Promise<BatchUserStatusResponseDto> {
    this.logger.log('管理员批量修改用户状态', {
      operation: 'batch_update_user_status',
      userCount: batchUserStatusDto.user_ids.length,
      newStatus: batchUserStatusDto.status,
      reason: batchUserStatusDto.reason,
      timestamp: new Date().toISOString()
    });

    return await this.userManagementService.batchUpdateUserStatus(batchUserStatusDto);
  }

  /**
   * 获取用户状态统计
   * 
   * @returns 状态统计信息
   */
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ 
    summary: '获取用户状态统计', 
    description: '获取各种用户状态的数量统计信息' 
  })
  @ApiResponse({ 
    status: 200, 
    description: '获取成功', 
    type: UserStatusStatsResponseDto 
  })
  @ApiResponse({ 
    status: 403, 
    description: '权限不足' 
  })
  @UseGuards(AdminGuard)
  @Timeout(TimeoutPresets.DATABASE_QUERY)
  @Get('status-stats')
  async getUserStatusStats(): Promise<UserStatusStatsResponseDto> {
    this.logger.log('管理员获取用户状态统计', {
      operation: 'get_user_status_stats',
      timestamp: new Date().toISOString()
    });

    return await this.userManagementService.getUserStatusStats();
  }
}