import { ApiProperty } from '@nestjs/swagger';
import { IsNotEmpty, IsNumber } from 'class-validator';

/**
 * CreateDto - Base Data Transfer Object for creating commission enquiries
 *
 * This DTO serves as the foundational structure for creating commission enquiries.
 * It defines the core geographic, institutional, and temporal parameters required
 * to identify which commission contract should be applied and for which cases.
 *
 * Business Context: Commission Enquiry Creation
 * - Used as a base class for both institute and master agent commission enquiries
 * - Defines the minimum required parameters for commission calculation
 * - Ensures data integrity through strict validation rules
 * - Provides Swagger documentation for API consumers
 *
 * Validation Rules:
 * - All fields are required and cannot be empty
 * - All fields must be numeric IDs
 * - Comprehensive validation prevents malformed requests
 *
 * Use Cases:
 * - Creating new commission enquiries for institutes
 * - Creating new commission enquiries for master agents
 * - Validating commission enquiry parameters before processing
 */
export class CreateDto {
  /**
   * Visa Service Country ID
   *
   * The country where the visa service is being provided/processed.
   * This identifies the destination country for the visa applications.
   *
   * Business Logic:
   * - Determines which country's commission rates apply
   * - Used in conjunction with visa service type (product_id)
   * - Essential for multi-country commission structures
   *
   * Example Values:
   * - 1: United States
   * - 2: United Kingdom
   * - 3: Australia
   * - 4: Canada
   *
   * @example 3 (Australia)
   */
  @ApiProperty({
    description: 'ID of the country where visa service is provided',
    example: 3,
    required: true,
  })
  @IsNumber()
  @IsNotEmpty()
  visa_service_country_id: number;

  /**
   * Institute ID
   *
   * The educational institution/college/university for which the commission
   * is being calculated. This identifies the payee for institute commissions.
   *
   * Business Logic:
   * - Identifies the institute receiving students
   * - Determines institute-specific commission rates
   * - Used for institute-based commission calculations
   *
   * Example Values:
   * - 101: University of Melbourne
   * - 102: University of Toronto
   * - 103: University of Oxford
   *
   * @example 101
   */
  @ApiProperty({
    description: 'ID of the educational institute/college',
    example: 101,
    required: true,
  })
  @IsNumber()
  @IsNotEmpty()
  institute_id: number;

  /**
   * Client From Country ID
   *
   * The country of origin/nationality of the students/clients.
   * This identifies the source market for the commission calculation.
   *
   * Business Logic:
   * - Determines client nationality-based commission rates
   * - Used for country-specific commission structures
   * - Important for international student commission calculations
   *
   * Example Values:
   * - 1: India
   * - 2: China
   * - 3: Nigeria
   * - 4: Brazil
   *
   * @example 1 (India)
   */
  @ApiProperty({
    description: 'ID of the client/student country of origin',
    example: 1,
    required: true,
  })
  @IsNumber()
  @IsNotEmpty()
  client_from_country_id: number;

  /**
   * Intake ID
   *
   * The academic intake period for which the commission is being calculated.
   * This identifies the specific intake year and month.
   *
   * Business Logic:
   * - Identifies the academic intake period
   * - Used for intake-specific commission rates
   * - Important for seasonal commission calculations
   *
   * Format:
   * - Typically represents an academic year and month combination
   * - May be linked to CourseMasterIntakeYearsEntity
   *
   * Example Values:
   * - 202401: January 2024 intake
   * - 202407: July 2024 intake
   *
   * @example 202401
   */
  @ApiProperty({
    description: 'ID of the academic intake period',
    example: 202401,
    required: true,
  })
  @IsNumber()
  @IsNotEmpty()
  intake_id: number;

  /**
   * Commission Instance
   *
   * The specific commission contract instance/tier to be applied.
   * This identifies the exact commission rate structure from the contract.
   *
   * Business Logic:
   * - Identifies the commission tier/instance from the contract
   * - Determines commission rates (percentage or fixed amount)
   * - Used for tiered commission calculations
   *
   * Relationship:
   * - Links to VcmCommissionContractInstancesEntity
   * - Contains commission_type, commission_amount, commission_percentage
   *
   * Example Values:
   * - 1: First commission tier (e.g., 10% commission)
   * - 2: Second commission tier (e.g., 15% commission)
   * - 3: Special commission instance (e.g., fixed $500 per student)
   *
   * @example 1
   */
  @ApiProperty({
    description: 'ID of the commission contract instance/tier',
    example: 1,
    required: true,
  })
  @IsNumber()
  @IsNotEmpty()
  commission_instance: number;
}
