/**
 * 用户状态管理 DTO
 * 
 * 功能描述：
 * - 定义用户状态管理相关的请求数据结构
 * - 提供数据验证规则和错误提示
 * - 确保状态管理操作的数据格式一致性
 * 
 * 职责分离：
 * - 请求数据结构定义和类型约束
 * - 数据验证规则配置和错误消息定义
 * - Swagger API文档生成支持
 * 
 * 最近修改：
 * - 2026-01-07: 代码规范优化 - 修正文件命名规范，完善注释规范，更新作者信息 (修改者: moyin)
 * 
 * @author moyin
 * @version 1.0.1
 * @since 2025-12-24
 * @lastModified 2026-01-07
 */

import { IsString, IsNotEmpty, IsEnum, IsOptional, IsArray, ArrayMinSize, ArrayMaxSize } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';
import { UserStatus } from './user_status.enum';
import { BATCH_OPERATION, VALIDATION } from './user_mgmt.constants';

/**
 * 用户状态修改请求DTO
 * 
 * 职责：
 * - 定义单个用户状态修改的请求数据格式
 * - 提供状态值和修改原因的验证规则
 * - 支持Swagger文档自动生成
 * 
 * 主要字段：
 * - status - 新的用户状态（必填）
 * - reason - 状态修改原因（可选）
 * 
 * 使用场景：
 * - 管理员修改单个用户状态的API请求
 * - 用户状态变更操作的数据传输
 */
export class UserStatusDto {
  /**
   * 新的用户状态
   */
  @ApiProperty({
    description: '用户状态',
    enum: UserStatus,
    example: UserStatus.ACTIVE,
    enumName: 'UserStatus'
  })
  @IsEnum(UserStatus, { message: '用户状态必须是有效的枚举值' })
  @IsNotEmpty({ message: '用户状态不能为空' })
  status: UserStatus;

  /**
   * 状态修改原因
   */
  @ApiProperty({
    description: '状态修改原因（可选）',
    example: '用户违反社区规定',
    required: false,
    maxLength: VALIDATION.REASON_MAX_LENGTH
  })
  @IsOptional()
  @IsString({ message: '修改原因必须是字符串' })
  reason?: string;
}

/**
 * 批量用户状态修改请求DTO
 * 
 * 职责：
 * - 定义批量用户状态修改的请求数据格式
 * - 提供用户ID列表和状态值的验证规则
 * - 限制批量操作的数量范围（${BATCH_OPERATION.MIN_USER_COUNT}-${BATCH_OPERATION.MAX_USER_COUNT}个用户）
 * 
 * 主要字段：
 * - userIds - 用户ID列表（必填，${BATCH_OPERATION.MIN_USER_COUNT}-${BATCH_OPERATION.MAX_USER_COUNT}个）
 * - status - 新的用户状态（必填）
 * - reason - 批量修改原因（可选）
 * 
 * 使用场景：
 * - 管理员批量修改用户状态的API请求
 * - 系统自动化批量用户管理操作
 */
export class BatchUserStatusDto {
  /**
   * 用户ID列表
   */
  @ApiProperty({
    description: '用户ID列表',
    example: ['1', '2', '3'],
    type: [String],
    minItems: BATCH_OPERATION.MIN_USER_COUNT,
    maxItems: BATCH_OPERATION.MAX_USER_COUNT
  })
  @IsArray({ message: '用户ID列表必须是数组' })
  @ArrayMinSize(BATCH_OPERATION.MIN_USER_COUNT, { message: '至少需要选择一个用户' })
  @ArrayMaxSize(BATCH_OPERATION.MAX_USER_COUNT, { message: `一次最多只能操作${BATCH_OPERATION.MAX_USER_COUNT}个用户` })
  @IsString({ each: true, message: '用户ID必须是字符串' })
  @IsNotEmpty({ each: true, message: '用户ID不能为空' })
  userIds: string[];

  /**
   * 新的用户状态
   */
  @ApiProperty({
    description: '用户状态',
    enum: UserStatus,
    example: UserStatus.LOCKED,
    enumName: 'UserStatus'
  })
  @IsEnum(UserStatus, { message: '用户状态必须是有效的枚举值' })
  @IsNotEmpty({ message: '用户状态不能为空' })
  status: UserStatus;

  /**
   * 状态修改原因
   */
  @ApiProperty({
    description: '批量修改原因（可选）',
    example: '批量处理违规用户',
    required: false,
    maxLength: VALIDATION.REASON_MAX_LENGTH
  })
  @IsOptional()
  @IsString({ message: '修改原因必须是字符串' })
  reason?: string;
}