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

/**
 * ReceivedInfoDto - Data Transfer Object for retrieving commission received details
 *
 * This DTO is used to fetch detailed information about specific commission payments
 * that have been received. It identifies which commission received record to retrieve
 * and ensures the correct association type is specified.
 *
 * Business Context: Commission Payment Detail Retrieval
 * - Used to get comprehensive details of received commission payments
 * - Essential for payment verification and reconciliation
 * - Supports both institute and master agent payment details
 * - Provides audit trail for financial transactions
 *
 * Validation Features:
 * - Both fields accept numbers or numeric strings for flexibility
 * - Validates that values are numeric strings (e.g., "123", 123)
 * - Ensures required fields are provided
 * - Provides clear API documentation
 */
export class ReceivedInfoDto {
  /**
   * Commission Received Record ID
   *
   * The unique identifier of the commission received/payment record.
   * This identifies which specific payment record to retrieve detailed information for.
   *
   * Business Significance:
   * - Primary key for VcmCommissionReceivedEntity
   * - Used to fetch payment details and line items
   * - Essential for payment reconciliation and verification
   *
   * Data Type Flexibility:
   * - Accepts both numbers (123) and numeric strings ("123")
   * - Useful when IDs come from different sources (URL params, form data)
   * - Ensures compatibility with various client implementations
   *
   * Example Values:
   * - 12345 (numeric)
   * - "12345" (string)
   * - CRM-2024-001 (if using alphanumeric IDs, though not validated here)
   *
   * @example 12345
   * @example "12345"
   */
  @ApiProperty({
    description: 'ID of the commission received/payment record',
    example: 12345,
    required: true,
  })
  @IsNotEmpty({ message: 'Commission received ID is required' })
  @IsNumberString(
    {},
    {
      message: 'Commission received ID must be a numeric string',
    },
  )
  id: number | string;

  /**
   * Association Type
   *
   * The type of association/relationship for the commission payment.
   * This determines which commission workflow path the payment belongs to
   * and affects how the data is retrieved and displayed.
   *
   * Business Significance:
   * - Determines which entity relationships to query
   * - Affects which service methods are called
   * - Ensures correct data retrieval for different commission types
   * - Important for multi-association type systems
   *
   * Common Values:
   * - "1" or 1: Institute commission payments
   * - "2" or 2: Master agent commission payments
   *
   * Data Type Flexibility:
   * - Accepts both numbers (1) and numeric strings ("1")
   * - Consistent with other DTOs in the commission module
   * - Supports flexible client implementations
   *
   * @example 1
   * @example "1"
   * @example 2
   * @example "2"
   */
  @ApiProperty({
    description: 'Association type of the commission payment',
    example: 1,
    required: true,
    enum: [1, 2, '1', '2'],
    examples: {
      Institute: 1,
      'Master Agent': 2,
    },
  })
  @IsNotEmpty({ message: 'Association type is required' })
  @IsNumberString(
    {},
    {
      message: 'Association type must be a numeric string',
    },
  )
  association_type: number | string;
}
