import { ApiPropertyOptional } from '@nestjs/swagger';
import { IsArray, IsOptional, IsString } from 'class-validator';

/**
 * AddAttachmentDto - Data Transfer Object for adding attachments to commission records
 *
 * This DTO is used for adding file attachments (payment proofs, receipts, bank statements)
 * to various commission-related records in the system. It supports adding attachments
 * to different types of commission entities.
 *
 * Business Context: Commission Document Management
 * - Used for uploading payment proofs and supporting documents
 * - Supports multiple file uploads in a single request
 * - Flexible design to work with different commission entity types
 * - Essential for audit trails and payment verification
 *
 * Validation: Uses class-validator decorators for request validation
 * Documentation: Uses Swagger decorators for API documentation
 */
export class AddAttachmentDto {
  /**
   * Target Record ID
   *
   * The ID of the commission record to which attachments should be added.
   * This could be:
   * - Commission Contract ID
   * - Commission Enquiry ID
   * - Commission Received ID
   * - Commission Invoice ID
   *
   * @example "12345"
   * @example "CRM-2024-001"
   */
  @IsString()
  id: string;

  /**
   * Entity Type
   *
   * Specifies the type of commission entity to which attachments are being added.
   * This determines which repository/service method will handle the attachment.
   *
   * Common values:
   * - 'contract': Commission contract attachments
   * - 'enquiry': Commission enquiry attachments
   * - 'received': Commission received/payment attachments
   * - 'invoice': Commission invoice attachments
   * - 'set': Commission contract set attachments
   *
   * @example "contract"
   * @example "received"
   */
  @IsString()
  type: string;

  /**
   * Attachment Files
   *
   * Array of file names to be attached to the commission record.
   * These are typically filenames generated by the file upload interceptor
   * and stored in the server's file system or cloud storage.
   *
   * File types typically include:
   * - PDF documents (contracts, invoices)
   * - Image files (receipts, bank statements)
   * - Text files (supporting documentation)
   * - Spreadsheets (financial calculations)
   *
   * @example ["payment-proof-12345.jpg", "bank-statement-67890.pdf"]
   * @example ["contract-agreement.pdf", "signature-page.png"]
   */
  @ApiPropertyOptional({
    type: [String],
    description: 'Array of file names to attach',
    example: ['payment-proof-12345.jpg', 'bank-statement-67890.pdf'],
  })
  @IsOptional() // Optional because files might be empty
  @IsArray() // Must be an array
  @IsString({ each: true }) // Each element must be a string
  attachment_file?: string[]; // Optional array of attachment file names
}
