import { IsNumber, IsString } from 'class-validator';

/**
 * RemoveAttachmentDto - Data Transfer Object for removing attachments from commission records
 *
 * This DTO is used for removing file attachments (payment proofs, receipts, contracts)
 * from various commission-related records in the system. It provides all necessary
 * information to identify and remove a specific attachment.
 *
 * Business Context: Commission Document Management
 * - Used for removing outdated or incorrect payment proofs
 * - Essential for maintaining clean and accurate document records
 * - Supports audit trail management
 * - Provides comprehensive file identification for safe removal
 *
 * Security Considerations:
 * - Validates all parameters to prevent unauthorized removal
 * - Ensures file removal only from authorized records
 * - Provides file URL for verification before deletion
 *
 * Workflow:
 * 1. Client identifies attachment to remove
 * 2. Sends remove request with this DTO
 * 3. System validates request and permissions
 * 4. Removes file reference from database
 * 5. Physically deletes file from storage (optional)
 */
export class RemoveAttachmentDto {
  /**
   * Attachment ID (Context Identifier)
   *
   * A unique identifier for the attachment context or type.
   * This helps identify which entity/table the attachment belongs to.
   *
   * Business Significance:
   * - May represent the type of commission record
   * - Could be used to route to the correct service method
   * - Provides context for the attachment removal
   *
   * Example Values:
   * - "contract_attachment_123"
   * - "payment_proof_456"
   * - "commission_receipt_789"
   *
   * Note: The exact usage may vary based on implementation
   *
   * @example "contract_attachment_123"
   */
  @IsString()
  id: string;

  /**
   * Database Row ID
   *
   * The primary key ID of the commission record in the database.
   * This identifies which specific record to update by removing the attachment.
   *
   * Business Significance:
   * - Primary key for the commission entity (contract, enquiry, received, etc.)
   * - Essential for database update operations
   * - Ensures precise targeting of the correct record
   *
   * Example Values:
   * - 12345 (commission contract ID)
   * - 67890 (commission enquiry ID)
   * - 54321 (commission received ID)
   *
   * @example 12345
   */
  @IsNumber()
  row_id: number;

  /**
   * File Name
   *
   * The name of the file to be removed from the attachment list.
   * This is the filename as stored in the database and file system.
   *
   * Business Significance:
   * - Used to identify which specific file to remove from the attachment array
   * - Must match exactly with the stored filename
   * - Used for both database update and physical file deletion
   *
   * Typical File Names:
   * - "payment-proof-12345.jpg"
   * - "bank-statement-67890.pdf"
   * - "contract-agreement-54321.docx"
   * - "receipt-98765.png"
   *
   * @example "payment-proof-12345.jpg"
   */
  @IsString()
  file_name: string;

  /**
   * File URL
   *
   * The URL or path where the file is stored.
   * This may be used for verification, logging, or physical file deletion.
   *
   * Business Significance:
   * - Provides complete file location information
   * - Used for verification before deletion
   * - May be used for audit logging
   * - Could be used for physical file removal from storage
   *
   * Format Examples:
   * - "/uploads/commissions/payment-proof-12345.jpg"
   * - "https://storage.cloud.com/commissions/bank-statement-67890.pdf"
   * - "s3://bucket-name/contracts/agreement-54321.pdf"
   *
   * Security Note:
   * - Should be validated to ensure it's within authorized directories
   * - May be used to prevent directory traversal attacks
   *
   * @example "/uploads/commissions/payment-proof-12345.jpg"
   */
  @IsString()
  file_url: string;
}
