import { IsIn, IsInt, IsNotEmpty } from 'class-validator';
import { Type } from 'class-transformer';
import { AssociationType } from 'src/utils/enums/enum';
import { ApiProperty } from '@nestjs/swagger';

/**
 * FetchByAssociationTypesDto - Data Transfer Object for filtering by association type
 *
 * This DTO is used for filtering commission-related data (enquiries, contracts, payments)
 * based on the type of association. It ensures that only valid association types
 * are accepted and provides proper API documentation.
 *
 * Business Context: Commission Data Filtering
 * - Used across multiple endpoints for filtering commission data
 * - Ensures data security by validating association types
 * - Provides consistent filtering mechanism across the commission module
 * - Essential for multi-association type systems
 *
 * Validation Features:
 * - Validates that the type is a valid AssociationType enum value
 * - Ensures the type is a number (not string representation)
 * - Prevents invalid or malicious association type values
 * - Provides clear API documentation with Swagger
 */
export class FetchByAssociationTypesDto {
  /**
   * Association Type
   *
   * The type of association/relationship for which data should be filtered.
   * This determines which commission workflow path to follow:
   * - Institute-based commissions (direct with educational institutions)
   * - Master Agent-based commissions (through partner agents)
   * - Sub-Agent-based commissions (through sub-agents under master agents)
   *
   * Business Significance:
   * - Determines which commission contracts apply
   * - Affects commission calculation logic
   * - Influences which entities are joined in queries
   * - Impacts which service methods are called
   *
   * Enum Values (from AssociationType):
   * - 1: INSTITUTE - Direct commission with educational institutions
   * - 2: MASTER_AGENT - Commission through master/primary agents
   * - 3: SUB_AGENT - Commission through sub-agents (under master agents)
   *
   * Example Usage:
   * - type: 1 → Filter institute commission enquiries
   * - type: 2 → Filter master agent commission enquiries
   * - type: 3 → Filter sub-agent commission details
   *
   * @example AssociationType.INSTITUTE (1)
   * @example AssociationType.MASTER_AGENT (2)
   */
  @ApiProperty({
    enum: AssociationType,
    example: AssociationType.INSTITUTE,
    description: 'Type of association for filtering commission data',
    enumName: 'AssociationType',
    examples: {
      Institute: AssociationType.INSTITUTE,
      'Master Agent': AssociationType.MASTER_AGENT,
      'Sub Agent': AssociationType.SUB_AGENT,
    },
  })
  @IsNotEmpty({ message: 'Association type is required' })
  @Type(() => Number) // Transform to number if received as string
  @IsInt({ message: 'Association type must be an integer' })
  @IsIn(Object.values(AssociationType).filter((v) => typeof v === 'number'), {
    message: 'Association type must be a valid enum value',
  })
  type: AssociationType;
}
