/**
 * 用户状态管理控制器
 * 
 * 功能描述：
 * - 管理员管理用户账户状态
 * - 支持批量状态操作
 * - 提供状态变更审计日志
 * 
 * 职责分离：
 * - HTTP请求处理和参数验证
 * - API文档生成和接口规范定义
 * - 业务服务调用和响应格式化
 * 
 * API端点：
 * - PUT /admin/users/:id/status - 修改用户状态
 * - POST /admin/users/batch-status - 批量修改用户状态
 * - GET /admin/users/status-stats - 获取用户状态统计
 * 
 * 最近修改：
 * - 2026-01-07: 代码规范优化 - 修正文件命名规范，完善注释规范，更新作者信息 (修改者: moyin)
 * 
 * @author moyin
 * @version 1.0.1
 * @since 2025-12-24
 * @lastModified 2026-01-07
 */

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/admin.guard';
import { UserManagementService } from './user_management.service';
import { Throttle, ThrottlePresets } from '../../core/security_core/throttle.decorator';
import { Timeout, TimeoutPresets } from '../../core/security_core/timeout.decorator';
import { UserStatusDto, BatchUserStatusDto } from './user_status.dto';
import { UserStatusResponseDto, BatchUserStatusResponseDto, UserStatusStatsResponseDto } from './user_status_response.dto';
import { BATCH_OPERATION, UTILS } from './user_mgmt.constants';

/**
 * 用户状态管理控制器
 * 
 * 职责：
 * - 处理用户状态管理相关的HTTP请求
 * - 提供RESTful API接口和Swagger文档
 * - 执行请求参数验证和权限控制
 * 
 * 主要方法：
 * - updateUserStatus() - 修改单个用户状态
 * - batchUpdateUserStatus() - 批量修改用户状态
 * - getUserStatusStats() - 获取用户状态统计
 * 
 * 使用场景：
 * - 管理员通过API管理用户状态
 * - 系统集成和自动化用户管理
 * - 用户状态监控和统计分析
 */
@ApiTags('user_management')
@Controller('admin/users')
export class UserStatusController {
  private readonly logger = new Logger(UserStatusController.name);

  constructor(private readonly userManagementService: UserManagementService) {}

  /**
   * 修改用户状态
   * 
   * 业务逻辑：
   * 1. 验证管理员权限和操作频率限制
   * 2. 验证用户ID格式和状态参数有效性
   * 3. 记录状态修改操作的审计日志
   * 4. 调用业务服务执行状态变更
   * 5. 返回操作结果和用户最新状态
   * 
   * @param id 用户ID
   * @param userStatusDto 状态修改数据
   * @returns 修改结果
   * @throws ForbiddenException 管理员权限不足时
   * @throws NotFoundException 用户不存在时
   * @throws TooManyRequestsException 操作过于频繁时
   * 
   * @example
   * ```typescript
   * const result = await controller.updateUserStatus('123', {
   *   status: UserStatus.LOCKED,
   *   reason: '用户违反社区规定'
   * });
   * ```
   */
  @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: UTILS.getCurrentTimestamp()
    });

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

  /**
   * 批量修改用户状态
   * 
   * 业务逻辑：
   * 1. 验证管理员权限和批量操作频率限制
   * 2. 验证用户ID列表和状态参数有效性
   * 3. 检查批量操作数量限制（最多${BATCH_OPERATION.MAX_USER_COUNT}个用户）
   * 4. 记录批量操作的审计日志
   * 5. 调用业务服务执行批量状态变更
   * 6. 返回批量操作结果统计
   * 
   * @param batchUserStatusDto 批量状态修改数据
   * @returns 批量修改结果
   * @throws ForbiddenException 管理员权限不足时
   * @throws BadRequestException 批量操作数量超限时
   * @throws TooManyRequestsException 操作过于频繁时
   * 
   * @example
   * ```typescript
   * const result = await controller.batchUpdateUserStatus({
   *   userIds: ['123', '456', '789'],
   *   status: UserStatus.LOCKED,
   *   reason: '批量处理违规用户'
   * });
   * ```
   */
  @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.userIds.length,
      newStatus: batchUserStatusDto.status,
      reason: batchUserStatusDto.reason,
      timestamp: UTILS.getCurrentTimestamp()
    });

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

  /**
   * 获取用户状态统计
   * 
   * 业务逻辑：
   * 1. 验证管理员权限
   * 2. 调用业务服务获取状态统计数据
   * 3. 记录统计查询的审计日志
   * 4. 返回各种状态的用户数量统计
   * 5. 提供状态分布分析数据
   * 
   * @returns 状态统计信息
   * @throws ForbiddenException 管理员权限不足时
   * @throws InternalServerErrorException 统计数据获取失败时
   * 
   * @example
   * ```typescript
   * const stats = await controller.getUserStatusStats();
   * // 返回: { active: 1250, inactive: 45, locked: 12, ... }
   * ```
   */
  @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: UTILS.getCurrentTimestamp()
    });

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