/**
 * 管理员数据库管理 DTO
 * 
 * 功能描述：
 * - 定义管理员数据库管理相关的请求和响应数据结构
 * - 提供完整的数据验证规则
 * - 支持Swagger文档自动生成
 * 
 * 职责分离：
 * - 请求数据结构定义和验证
 * - 响应数据结构定义
 * - API文档生成支持
 * - 类型安全保障
 * 
 * DTO分类：
 * - Query DTOs: 查询参数验证
 * - Create DTOs: 创建操作数据验证
 * - Update DTOs: 更新操作数据验证
 * - Response DTOs: 响应数据结构定义
 * 
 * 最近修改：
 * - 2026-01-08: 注释规范优化 - 修正@author字段，更新版本号和修改记录 (修改者: moyin)
 * - 2026-01-08: 注释规范优化 - 为所有DTO类添加类注释，完善文档说明 (修改者: moyin)
 * - 2026-01-08: 文件夹扁平化 - 从dto/子文件夹移动到上级目录 (修改者: moyin)
 * - 2026-01-08: 功能新增 - 创建管理员数据库管理DTO (修改者: assistant)
 * 
 * @author moyin
 * @version 1.0.3
 * @since 2026-01-08
 * @lastModified 2026-01-08
 */

import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { IsOptional, IsString, IsInt, Min, Max, IsEnum, IsEmail, IsArray, IsBoolean, IsNumber } from 'class-validator';
import { Transform } from 'class-transformer';
import { UserStatus } from '../../core/db/users/user_status.enum';

// ==================== 通用查询 DTOs ====================

/**
 * 管理员分页查询DTO
 * 
 * 功能描述：
 * 定义分页查询的通用参数结构
 * 
 * 使用场景：
 * - 作为其他查询DTO的基类
 * - 提供统一的分页参数验证
 */
export class AdminPaginationDto {
  @ApiPropertyOptional({ description: '返回数量（默认20，最大100）', example: 20, minimum: 1, maximum: 100 })
  @IsOptional()
  @IsInt()
  @Min(1)
  @Max(100)
  @Transform(({ value }) => parseInt(value))
  limit?: number = 20;

  @ApiPropertyOptional({ description: '偏移量（默认0）', example: 0, minimum: 0 })
  @IsOptional()
  @IsInt()
  @Min(0)
  @Transform(({ value }) => parseInt(value))
  offset?: number = 0;
}

// ==================== 用户管理 DTOs ====================

/**
 * 管理员查询用户DTO
 * 
 * 功能描述：
 * 定义用户查询接口的请求参数结构
 * 
 * 使用场景：
 * - GET /admin/database/users 接口的查询参数
 * - 支持关键词搜索和分页查询
 */
export class AdminQueryUsersDto extends AdminPaginationDto {
  @ApiPropertyOptional({ description: '搜索关键词（用户名、邮箱、昵称）', example: 'admin' })
  @IsOptional()
  @IsString()
  search?: string;

  @ApiPropertyOptional({ description: '用户状态过滤', enum: UserStatus, example: UserStatus.ACTIVE })
  @IsOptional()
  @IsEnum(UserStatus)
  status?: UserStatus;

  @ApiPropertyOptional({ description: '角色过滤', example: 1 })
  @IsOptional()
  @IsInt()
  @Min(0)
  @Max(9)
  role?: number;
}

/**
 * 管理员创建用户DTO
 * 
 * 功能描述：
 * 定义创建用户接口的请求数据结构和验证规则
 * 
 * 使用场景：
 * - POST /admin/database/users 接口的请求体
 * - 包含用户创建所需的所有必要信息
 */
export class AdminCreateUserDto {
  @ApiProperty({ description: '用户名', example: 'newuser' })
  @IsString()
  username: string;

  @ApiPropertyOptional({ description: '邮箱', example: 'user@example.com' })
  @IsOptional()
  @IsEmail()
  email?: string;

  @ApiPropertyOptional({ description: '手机号', example: '13800138000' })
  @IsOptional()
  @IsString()
  phone?: string;

  @ApiProperty({ description: '昵称', example: '新用户' })
  @IsString()
  nickname: string;

  @ApiPropertyOptional({ description: '密码哈希', example: 'hashed_password' })
  @IsOptional()
  @IsString()
  password_hash?: string;

  @ApiPropertyOptional({ description: 'GitHub ID', example: 'github123' })
  @IsOptional()
  @IsString()
  github_id?: string;

  @ApiPropertyOptional({ description: '头像URL', example: 'https://example.com/avatar.jpg' })
  @IsOptional()
  @IsString()
  avatar_url?: string;

  @ApiPropertyOptional({ description: '角色', example: 1, minimum: 0, maximum: 9 })
  @IsOptional()
  @IsInt()
  @Min(0)
  @Max(9)
  role?: number;

  @ApiPropertyOptional({ description: '邮箱是否已验证', example: false })
  @IsOptional()
  @IsBoolean()
  email_verified?: boolean;

  @ApiPropertyOptional({ description: '用户状态', enum: UserStatus, example: UserStatus.ACTIVE })
  @IsOptional()
  @IsEnum(UserStatus)
  status?: UserStatus;
}

/**
 * 管理员更新用户DTO
 * 
 * 功能描述：
 * 定义更新用户接口的请求数据结构和验证规则
 * 
 * 使用场景：
 * - PUT /admin/database/users/:id 接口的请求体
 * - 支持部分字段更新，所有字段都是可选的
 */
export class AdminUpdateUserDto {
  @ApiPropertyOptional({ description: '用户名', example: 'updateduser' })
  @IsOptional()
  @IsString()
  username?: string;

  @ApiPropertyOptional({ description: '邮箱', example: 'updated@example.com' })
  @IsOptional()
  @IsEmail()
  email?: string;

  @ApiPropertyOptional({ description: '手机号', example: '13900139000' })
  @IsOptional()
  @IsString()
  phone?: string;

  @ApiPropertyOptional({ description: '昵称', example: '更新用户' })
  @IsOptional()
  @IsString()
  nickname?: string;

  @ApiPropertyOptional({ description: '头像URL', example: 'https://example.com/new-avatar.jpg' })
  @IsOptional()
  @IsString()
  avatar_url?: string;

  @ApiPropertyOptional({ description: '角色', example: 2, minimum: 0, maximum: 9 })
  @IsOptional()
  @IsInt()
  @Min(0)
  @Max(9)
  role?: number;

  @ApiPropertyOptional({ description: '邮箱是否已验证', example: true })
  @IsOptional()
  @IsBoolean()
  email_verified?: boolean;

  @ApiPropertyOptional({ description: '用户状态', enum: UserStatus, example: UserStatus.INACTIVE })
  @IsOptional()
  @IsEnum(UserStatus)
  status?: UserStatus;
}

// ==================== 用户档案管理 DTOs ====================

/**
 * 管理员查询用户档案DTO
 * 
 * 功能描述：
 * 定义用户档案查询接口的请求参数结构
 * 
 * 使用场景：
 * - GET /admin/database/user-profiles 接口的查询参数
 * - 支持地图过滤和分页查询
 */
export class AdminQueryUserProfileDto extends AdminPaginationDto {
  @ApiPropertyOptional({ description: '当前地图过滤', example: 'plaza' })
  @IsOptional()
  @IsString()
  current_map?: string;

  @ApiPropertyOptional({ description: '状态过滤', example: 1 })
  @IsOptional()
  @IsInt()
  status?: number;

  @ApiPropertyOptional({ description: '用户ID过滤', example: '1' })
  @IsOptional()
  @IsString()
  user_id?: string;
}

/**
 * 管理员创建用户档案DTO
 * 
 * 功能描述：
 * 定义创建用户档案接口的请求数据结构和验证规则
 * 
 * 使用场景：
 * - POST /admin/database/user-profiles 接口的请求体
 * - 包含用户档案创建所需的所有信息
 */
export class AdminCreateUserProfileDto {
  @ApiProperty({ description: '用户ID', example: '1' })
  @IsString()
  user_id: string;

  @ApiPropertyOptional({ description: '个人简介', example: '这是我的个人简介' })
  @IsOptional()
  @IsString()
  bio?: string;

  @ApiPropertyOptional({ description: '简历内容', example: '工作经历和技能' })
  @IsOptional()
  @IsString()
  resume_content?: string;

  @ApiPropertyOptional({ description: '标签', example: '["开发者", "游戏爱好者"]' })
  @IsOptional()
  @IsString()
  tags?: string;

  @ApiPropertyOptional({ description: '社交链接', example: '{"github": "https://github.com/user"}' })
  @IsOptional()
  @IsString()
  social_links?: string;

  @ApiPropertyOptional({ description: '皮肤ID', example: 'skin_001' })
  @IsOptional()
  @IsString()
  skin_id?: string;

  @ApiPropertyOptional({ description: '当前地图', example: 'plaza' })
  @IsOptional()
  @IsString()
  current_map?: string;

  @ApiPropertyOptional({ description: 'X坐标', example: 100.5 })
  @IsOptional()
  @IsNumber()
  pos_x?: number;

  @ApiPropertyOptional({ description: 'Y坐标', example: 200.3 })
  @IsOptional()
  @IsNumber()
  pos_y?: number;

  @ApiPropertyOptional({ description: '状态', example: 1 })
  @IsOptional()
  @IsInt()
  status?: number;
}

/**
 * 管理员更新用户档案DTO
 * 
 * 功能描述：
 * 定义更新用户档案接口的请求数据结构和验证规则
 * 
 * 使用场景：
 * - PUT /admin/database/user-profiles/:id 接口的请求体
 * - 支持部分字段更新，所有字段都是可选的
 */
export class AdminUpdateUserProfileDto {
  @ApiPropertyOptional({ description: '个人简介', example: '更新后的个人简介' })
  @IsOptional()
  @IsString()
  bio?: string;

  @ApiPropertyOptional({ description: '简历内容', example: '更新后的简历内容' })
  @IsOptional()
  @IsString()
  resume_content?: string;

  @ApiPropertyOptional({ description: '标签', example: '["高级开发者", "技术专家"]' })
  @IsOptional()
  @IsString()
  tags?: string;

  @ApiPropertyOptional({ description: '社交链接', example: '{"linkedin": "https://linkedin.com/in/user"}' })
  @IsOptional()
  @IsString()
  social_links?: string;

  @ApiPropertyOptional({ description: '皮肤ID', example: 'skin_002' })
  @IsOptional()
  @IsString()
  skin_id?: string;

  @ApiPropertyOptional({ description: '当前地图', example: 'forest' })
  @IsOptional()
  @IsString()
  current_map?: string;

  @ApiPropertyOptional({ description: 'X坐标', example: 150.7 })
  @IsOptional()
  @IsNumber()
  pos_x?: number;

  @ApiPropertyOptional({ description: 'Y坐标', example: 250.9 })
  @IsOptional()
  @IsNumber()
  pos_y?: number;

  @ApiPropertyOptional({ description: '状态', example: 0 })
  @IsOptional()
  @IsInt()
  status?: number;
}

// ==================== Zulip账号关联管理 DTOs ====================

/**
 * 管理员查询Zulip账号DTO
 * 
 * 功能描述：
 * 定义Zulip账号关联查询接口的请求参数结构
 * 
 * 使用场景：
 * - GET /admin/database/zulip-accounts 接口的查询参数
 * - 支持用户ID过滤和分页查询
 */
export class AdminQueryZulipAccountDto extends AdminPaginationDto {
  @ApiPropertyOptional({ description: '游戏用户ID过滤', example: '1' })
  @IsOptional()
  @IsString()
  gameUserId?: string;

  @ApiPropertyOptional({ description: 'Zulip用户ID过滤', example: 12345 })
  @IsOptional()
  @IsInt()
  zulipUserId?: number;

  @ApiPropertyOptional({ description: 'Zulip邮箱过滤', example: 'user@zulip.com' })
  @IsOptional()
  @IsEmail()
  zulipEmail?: string;

  @ApiPropertyOptional({ description: '状态过滤', example: 'active', enum: ['active', 'inactive', 'suspended', 'error'] })
  @IsOptional()
  @IsEnum(['active', 'inactive', 'suspended', 'error'])
  status?: 'active' | 'inactive' | 'suspended' | 'error';
}

/**
 * 管理员创建Zulip账号DTO
 * 
 * 功能描述：
 * 定义创建Zulip账号关联接口的请求数据结构和验证规则
 * 
 * 使用场景：
 * - POST /admin/database/zulip-accounts 接口的请求体
 * - 包含Zulip账号关联创建所需的所有信息
 */
export class AdminCreateZulipAccountDto {
  @ApiProperty({ description: '游戏用户ID', example: '1' })
  @IsString()
  gameUserId: string;

  @ApiProperty({ description: 'Zulip用户ID', example: 12345 })
  @IsInt()
  zulipUserId: number;

  @ApiProperty({ description: 'Zulip邮箱', example: 'user@zulip.com' })
  @IsEmail()
  zulipEmail: string;

  @ApiProperty({ description: 'Zulip全名', example: '张三' })
  @IsString()
  zulipFullName: string;

  @ApiProperty({ description: 'Zulip API密钥（加密）', example: 'encrypted_api_key' })
  @IsString()
  zulipApiKeyEncrypted: string;

  @ApiPropertyOptional({ description: '状态', example: 'active', enum: ['active', 'inactive', 'suspended', 'error'] })
  @IsOptional()
  @IsEnum(['active', 'inactive', 'suspended', 'error'])
  status?: 'active' | 'inactive' | 'suspended' | 'error';
}

/**
 * 管理员更新Zulip账号DTO
 * 
 * 功能描述：
 * 定义更新Zulip账号关联接口的请求数据结构和验证规则
 * 
 * 使用场景：
 * - PUT /admin/database/zulip-accounts/:id 接口的请求体
 * - 支持部分字段更新，所有字段都是可选的
 */
export class AdminUpdateZulipAccountDto {
  @ApiPropertyOptional({ description: 'Zulip全名', example: '李四' })
  @IsOptional()
  @IsString()
  zulipFullName?: string;

  @ApiPropertyOptional({ description: 'Zulip API密钥（加密）', example: 'new_encrypted_api_key' })
  @IsOptional()
  @IsString()
  zulipApiKeyEncrypted?: string;

  @ApiPropertyOptional({ description: '状态', example: 'suspended', enum: ['active', 'inactive', 'suspended', 'error'] })
  @IsOptional()
  @IsEnum(['active', 'inactive', 'suspended', 'error'])
  status?: 'active' | 'inactive' | 'suspended' | 'error';

  @ApiPropertyOptional({ description: '错误信息', example: '连接超时' })
  @IsOptional()
  @IsString()
  errorMessage?: string;

  @ApiPropertyOptional({ description: '重试次数', example: 3 })
  @IsOptional()
  @IsInt()
  @Min(0)
  retryCount?: number;
}

/**
 * 管理员批量更新状态DTO
 * 
 * 功能描述：
 * 定义批量更新状态接口的请求数据结构和验证规则
 * 
 * 使用场景：
 * - POST /admin/database/zulip-accounts/batch-update-status 接口的请求体
 * - 支持批量更新多个记录的状态
 */
export class AdminBatchUpdateStatusDto {
  @ApiProperty({ description: 'ID列表', example: ['1', '2', '3'] })
  @IsArray()
  @IsString({ each: true })
  ids: string[];

  @ApiProperty({ description: '目标状态', example: 'active', enum: ['active', 'inactive', 'suspended', 'error'] })
  @IsEnum(['active', 'inactive', 'suspended', 'error'])
  status: 'active' | 'inactive' | 'suspended' | 'error';

  @ApiPropertyOptional({ description: '操作原因', example: '批量激活账号' })
  @IsOptional()
  @IsString()
  reason?: string;
}

// ==================== 响应 DTOs ====================

/**
 * 管理员数据库响应DTO
 * 
 * 功能描述：
 * 定义管理员数据库操作的通用响应数据结构
 * 
 * 使用场景：
 * - 各种数据库管理接口的响应体基类
 * - 包含操作状态、数据和消息信息
 */
export class AdminDatabaseResponseDto {
  @ApiProperty({ description: '是否成功', example: true })
  success: boolean;

  @ApiProperty({ description: '消息', example: '操作成功' })
  message: string;

  @ApiPropertyOptional({ description: '数据' })
  data?: any;

  @ApiPropertyOptional({ description: '错误码', example: 'RESOURCE_NOT_FOUND' })
  error_code?: string;

  @ApiProperty({ description: '时间戳', example: '2026-01-08T10:30:00.000Z' })
  timestamp: string;

  @ApiProperty({ description: '请求ID', example: 'req_1641636600000_abc123' })
  request_id: string;
}

/**
 * 管理员数据库列表响应DTO
 * 
 * 功能描述：
 * 定义管理员数据库列表查询的响应数据结构
 * 
 * 使用场景：
 * - 各种列表查询接口的响应体
 * - 包含列表数据和分页信息
 */
export class AdminDatabaseListResponseDto extends AdminDatabaseResponseDto {
  @ApiProperty({ description: '列表数据' })
  data: {
    items: any[];
    total: number;
    limit: number;
    offset: number;
    has_more: boolean;
  };
}

/**
 * 管理员健康检查响应DTO
 * 
 * 功能描述：
 * 定义系统健康检查接口的响应数据结构
 * 
 * 使用场景：
 * - GET /admin/database/health 接口的响应体
 * - 包含系统健康状态信息
 */
export class AdminHealthCheckResponseDto extends AdminDatabaseResponseDto {
  @ApiProperty({ description: '健康检查数据' })
  data: {
    status: string;
    timestamp: string;
    services: {
      users: string;
      user_profiles: string;
      zulip_accounts: string;
    };
  };
}