import {
  IsEmail,
  IsIn,
  IsNotEmpty,
  IsNumber,
  IsString,
  Max,
  Min,
  MinLength,
} from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

/**
 * SignUpRequestDto - Data Transfer Object for user registration requests
 *
 * This DTO handles new user registration with comprehensive validation for
 * creating user accounts. It includes personal information, authentication
 * details, role assignment, and registration metadata.
 *
 * The DTO ensures that new accounts meet security requirements and business
 * rules before being created in the system.
 *
 * @example
 * // Valid registration request
 * {
 *   "name": "John Doe",
 *   "flag": "dm",
 *   "email": "john.doe@example.com",
 *   "password": "SecurePass123!",
 *   "role": 2,
 *   "mobile": "+12345678901"
 * }
 *
 * @example
 * // Usage in controller
 * @Post('signup')
 * signUp(@Body() signUpDto: SignUpRequestDto) {
 *   return this.authService.registerUser(signUpDto);
 * }
 */
export class SignUpRequestDto {
  /**
   * User's full name
   *
   * The display name or full name of the user for identification.
   * This is typically used in UI displays, emails, and reports.
   *
   * Validation rules:
   * - Must be a non-empty string
   * - Consider adding length limits: @MaxLength(100)
   * - Consider sanitizing to prevent injection attacks
   *
   * @example "John Doe"
   * @example "Alice Smith"
   */
  @IsString()
  @IsNotEmpty()
  @ApiProperty({
    description: 'Full name of the user',
    example: 'John Doe',
    required: true,
  })
  name: string;

  /**
   * Registration method flag
   *
   * Indicates the registration system or method being used.
   * Allows supporting multiple registration flows (web, mobile, partner, etc.)
   *
   * Common values:
   * - 'dm': Direct registration (standard web/mobile form)
   * - 'guglu': Alternative registration (partner integration, SSO, etc.)
   *
   * Can affect:
   * - Validation rules
   * - Default role assignment
   * - Welcome email templates
   * - Analytics tracking
   *
   * Validation rules:
   * - Must be a non-empty string
   * - Must be one of: 'dm' or 'guglu'
   *
   * @note Consider using an enum: RegistrationFlag { DM = 'dm', GUGLU = 'guglu' }
   *
   * @example "dm"
   * @example "guglu"
   */
  @IsString()
  @IsNotEmpty()
  @IsIn(['dm', 'guglu'])
  @ApiProperty({
    description: 'Registration method/system flag',
    enum: ['dm', 'guglu'],
    examples: ['dm', 'guglu'],
    required: true,
  })
  flag: string;

  /**
   * User's email address
   *
   * Primary contact and authentication identifier.
   * Must be unique across the system (enforced at service/database level).
   *
   * Security considerations:
   * - Validate email format
   * - Check for disposable/temporary email addresses
   * - Verify email ownership (send confirmation email)
   * - Enforce uniqueness in database
   * - Consider case-insensitive storage
   *
   * Validation rules:
   * - Must be valid email format
   * - Must be non-empty
   *
   * @example "john.doe@example.com"
   * @example "alice.smith@company.org"
   */
  @IsEmail()
  @IsNotEmpty()
  @ApiProperty({
    description: 'User email address (must be unique)',
    example: 'john.doe@example.com',
    format: 'email',
    required: true,
  })
  email: string;

  /**
   * Account password
   *
   * Authentication credential for the new account.
   * Should meet minimum security requirements.
   *
   * Security best practices:
   * - Minimum 8 characters (consider 12+)
   * - Add complexity requirements
   * - Check against breached password databases
   * - Hash with strong algorithm (bcrypt, Argon2) before storage
   * - Never store in plain text
   *
   * Validation rules:
   * - Must be a string
   * - Minimum 8 characters
   * - Must be non-empty
   *
   * @warning Consider adding complexity validation:
   *   @Matches(/(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/)
   *
   * @example "SecurePass123!"
   * @example "VeryStrongPassword456@"
   */
  @IsString()
  @MinLength(8)
  @IsNotEmpty()
  @ApiProperty({
    description: 'Account password (minimum 8 characters)',
    example: 'SecurePass123!',
    minLength: 8,
    required: true,
  })
  password: string;

  /**
   * User role identifier
   *
   * Numeric identifier for the user's role/permissions level.
   * Determines what features and data the user can access.
   *
   * Common role values (example):
   * - 2: Standard user
   * - 3: Premium user
   * - 10: Administrator
   * - 14: Super administrator
   *
   * Security considerations:
   * - Validate that user has permission to assign the requested role
   * - Consider defaulting to lowest privilege role
   * - Document role hierarchy and permissions
   *
   * Validation rules:
   * - Must be a number
   * - Must be non-empty
   * - Minimum value: 2
   * - Maximum value: 14
   *
   * @example 2
   * @example 10
   */
  @IsNumber()
  @IsNotEmpty()
  @Min(2)
  @Max(14)
  @ApiProperty({
    description: 'User role identifier (2-14)',
    example: 2,
    minimum: 2,
    maximum: 14,
    required: true,
  })
  role: number;

  /**
   * Mobile phone number
   *
   * User's mobile phone number for SMS notifications, 2FA, and recovery.
   * Should follow international format with country code.
   *
   * Validation considerations:
   * - Minimum 10 characters (includes country code)
   * - Consider validating with libphonenumber-js
   * - Consider requiring country code prefix (+)
   * - Normalize to E.164 format for storage
   *
   * Validation rules:
   * - Must be a string
   * - Must be non-empty
   * - Minimum 10 characters
   *
   * @note 10 characters may not be sufficient for all international numbers
   *
   * @example "+12345678901"
   * @example "+441234567890"
   */
  @IsString()
  @IsNotEmpty()
  @MinLength(10)
  @ApiProperty({
    description: 'Mobile phone number (minimum 10 characters)',
    example: '+12345678901',
    minLength: 10,
    required: true,
  })
  mobile: string;

  /**
   * Last login URL (optional tracking field)
   *
   * Field for tracking where the user registered from.
   * Typically populated automatically by the client/application.
   *
   * Usage:
   * - Marketing attribution
   * - Analytics
   * - User journey tracking
   *
   * @note Not validated or documented in Swagger as it's typically set automatically
   * @example "https://app.example.com/signup"
   * @example "mobile://signup"
   */
  last_login_url: string;
}
