whale-town-end/src/gateway/auth/dto/login_response.dto.ts

/**
 * 登录业务响应数据传输对象
 * 
 * 功能描述：
 * - 定义登录相关API的响应数据结构
 * - 提供Swagger文档生成支持
 * - 确保API响应的数据格式一致性
 * 
 * 职责分离：
 * - 专注于响应数据结构定义
 * - 提供完整的API文档支持
 * - 确保响应格式的统一性
 * 
 * 最近修改：
 * - 2026-01-07: 代码规范优化 - 文件夹扁平化，移除单文件文件夹结构
 * - 2026-01-07: 代码规范优化 - 更新注释规范，修正作者信息
 * 
 * @author moyin
 * @version 1.0.2
 * @since 2025-12-17
 * @lastModified 2026-01-07
 */

import { ApiProperty } from '@nestjs/swagger';

/**
 * 用户信息响应DTO
 */
export class UserInfoDto {
  @ApiProperty({
    description: '用户ID',
    example: '1'
  })
  id: string;

  @ApiProperty({
    description: '用户名',
    example: 'testuser'
  })
  username: string;

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

  @ApiProperty({
    description: '邮箱地址',
    example: 'test@example.com',
    required: false
  })
  email?: string;

  @ApiProperty({
    description: '手机号码',
    example: '+8613800138000',
    required: false
  })
  phone?: string;

  @ApiProperty({
    description: '头像URL',
    example: 'https://example.com/avatar.jpg',
    required: false
  })
  avatar_url?: string;

  @ApiProperty({
    description: '用户角色',
    example: 1
  })
  role: number;

  @ApiProperty({
    description: '创建时间',
    example: '2025-12-17T10:00:00.000Z'
  })
  created_at: Date;
}

/**
 * 登录响应数据DTO
 */
export class LoginResponseDataDto {
  @ApiProperty({
    description: '用户信息',
    type: UserInfoDto
  })
  user: UserInfoDto;

  @ApiProperty({
    description: 'JWT访问令牌',
    example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  })
  access_token: string;

  @ApiProperty({
    description: 'JWT刷新令牌',
    example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  })
  refresh_token: string;

  @ApiProperty({
    description: '访问令牌过期时间（秒）',
    example: 604800
  })
  expires_in: number;

  @ApiProperty({
    description: '令牌类型',
    example: 'Bearer'
  })
  token_type: string;

  @ApiProperty({
    description: '是否为新用户',
    example: false,
    required: false
  })
  is_new_user?: boolean;

  @ApiProperty({
    description: '响应消息',
    example: '登录成功'
  })
  message: string;
}

/**
 * 登录响应DTO
 */
export class LoginResponseDto {
  @ApiProperty({
    description: '请求是否成功',
    example: true
  })
  success: boolean;

  @ApiProperty({
    description: '响应数据',
    type: LoginResponseDataDto,
    required: false
  })
  data?: LoginResponseDataDto;

  @ApiProperty({
    description: '响应消息',
    example: '登录成功'
  })
  message: string;

  @ApiProperty({
    description: '错误代码',
    example: 'LOGIN_FAILED',
    required: false
  })
  error_code?: string;
}

/**
 * 注册响应DTO
 */
export class RegisterResponseDto {
  @ApiProperty({
    description: '请求是否成功',
    example: true
  })
  success: boolean;

  @ApiProperty({
    description: '响应数据',
    type: LoginResponseDataDto,
    required: false
  })
  data?: LoginResponseDataDto;

  @ApiProperty({
    description: '响应消息',
    example: '注册成功'
  })
  message: string;

  @ApiProperty({
    description: '错误代码',
    example: 'REGISTER_FAILED',
    required: false
  })
  error_code?: string;
}

/**
 * GitHub OAuth响应DTO
 */
export class GitHubOAuthResponseDto {
  @ApiProperty({
    description: '请求是否成功',
    example: true
  })
  success: boolean;

  @ApiProperty({
    description: '响应数据',
    type: LoginResponseDataDto,
    required: false
  })
  data?: LoginResponseDataDto;

  @ApiProperty({
    description: '响应消息',
    example: 'GitHub登录成功'
  })
  message: string;

  @ApiProperty({
    description: '错误代码',
    example: 'GITHUB_OAUTH_FAILED',
    required: false
  })
  error_code?: string;
}

/**
 * 忘记密码响应数据DTO
 */
export class ForgotPasswordResponseDataDto {
  @ApiProperty({
    description: '验证码（仅用于演示，实际应用中不应返回）',
    example: '123456',
    required: false
  })
  verification_code?: string;

  @ApiProperty({
    description: '是否为测试模式',
    example: true,
    required: false
  })
  is_test_mode?: boolean;
}

/**
 * 忘记密码响应DTO
 */
export class ForgotPasswordResponseDto {
  @ApiProperty({
    description: '请求是否成功',
    example: false,
    examples: {
      success: {
        summary: '真实发送成功',
        value: true
      },
      testMode: {
        summary: '测试模式',
        value: false
      }
    }
  })
  success: boolean;

  @ApiProperty({
    description: '响应数据',
    type: ForgotPasswordResponseDataDto,
    required: false,
    examples: {
      success: {
        summary: '真实发送成功',
        value: {
          verification_code: '123456',
          is_test_mode: false
        }
      },
      testMode: {
        summary: '测试模式',
        value: {
          verification_code: '059174',
          is_test_mode: true
        }
      }
    }
  })
  data?: ForgotPasswordResponseDataDto;

  @ApiProperty({
    description: '响应消息',
    example: '⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。',
    examples: {
      success: {
        summary: '真实发送成功',
        value: '验证码已发送，请查收'
      },
      testMode: {
        summary: '测试模式',
        value: '⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。'
      }
    }
  })
  message: string;

  @ApiProperty({
    description: '错误代码',
    example: 'TEST_MODE_ONLY',
    examples: {
      success: {
        summary: '真实发送成功',
        value: null
      },
      testMode: {
        summary: '测试模式',
        value: 'TEST_MODE_ONLY'
      },
      failed: {
        summary: '发送失败',
        value: 'SEND_CODE_FAILED'
      }
    },
    required: false
  })
  error_code?: string;
}

/**
 * 通用响应DTO（用于重置密码、修改密码等）
 */
export class CommonResponseDto {
  @ApiProperty({
    description: '请求是否成功',
    example: true
  })
  success: boolean;

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

  @ApiProperty({
    description: '错误代码',
    example: 'OPERATION_FAILED',
    required: false
  })
  error_code?: string;
}

/**
 * 测试模式邮件验证码响应DTO
 * 
 * 最近修改：
 * - 2025-12-17: 功能新增 - 添加测试模式响应DTO (修改者: angjustinl)
 */
export class TestModeEmailVerificationResponseDto {
  @ApiProperty({
    description: '请求是否成功（测试模式下为false）',
    example: false
  })
  success: boolean;

  @ApiProperty({
    description: '响应数据',
    example: {
      verification_code: '059174',
      is_test_mode: true
    }
  })
  data: {
    verification_code: string;
    is_test_mode: boolean;
  };

  @ApiProperty({
    description: '响应消息',
    example: '⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。'
  })
  message: string;

  @ApiProperty({
    description: '错误代码',
    example: 'TEST_MODE_ONLY'
  })
  error_code: string;
}

/**
 * 成功发送邮件验证码响应DTO
 */
export class SuccessEmailVerificationResponseDto {
  @ApiProperty({
    description: '请求是否成功',
    example: true
  })
  success: boolean;

  @ApiProperty({
    description: '响应数据',
    example: {
      verification_code: '123456',
      is_test_mode: false
    }
  })
  data: {
    verification_code: string;
    is_test_mode: boolean;
  };

  @ApiProperty({
    description: '响应消息',
    example: '验证码已发送，请查收'
  })
  message: string;

  @ApiProperty({
    description: '错误代码',
    example: null,
    required: false
  })
  error_code?: string;
}

/**
 * 令牌刷新响应数据DTO
 */
export class RefreshTokenResponseDataDto {
  @ApiProperty({
    description: 'JWT访问令牌',
    example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  })
  access_token: string;

  @ApiProperty({
    description: 'JWT刷新令牌',
    example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  })
  refresh_token: string;

  @ApiProperty({
    description: '访问令牌过期时间（秒）',
    example: 604800
  })
  expires_in: number;

  @ApiProperty({
    description: '令牌类型',
    example: 'Bearer'
  })
  token_type: string;
}

/**
 * 令牌刷新响应DTO
 */
export class RefreshTokenResponseDto {
  @ApiProperty({
    description: '请求是否成功',
    example: true
  })
  success: boolean;

  @ApiProperty({
    description: '响应数据',
    type: RefreshTokenResponseDataDto,
    required: false
  })
  data?: RefreshTokenResponseDataDto;

  @ApiProperty({
    description: '响应消息',
    example: '令牌刷新成功'
  })
  message: string;

  @ApiProperty({
    description: '错误代码',
    example: 'TOKEN_REFRESH_FAILED',
    required: false
  })
  error_code?: string;
}