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

/**
 * UpdateCommissionContractDto - Data Transfer Object for updating commission contract properties
 *
 * This DTO is used for partial updates to commission contract records.
 * It allows updating specific fields of a commission contract without requiring
 * all contract details. This is useful for simple updates like changing status,
 * renaming, or reordering contracts.
 *
 * Business Context: Commission Contract Management
 * - Used for simple updates to existing commission contracts
 * - Supports partial updates (PATCH semantics)
 * - Essential for contract lifecycle management
 * - Used in administrative interfaces for quick contract modifications
 *
 * Validation Features:
 * - All fields are optional (supports partial updates)
 * - Validates data types for each field
 * - Provides clear error messages for validation failures
 * - Includes Swagger documentation for API consumers
 *
 * Security Considerations:
 * - Should be used with proper authorization checks
 * - Typically requires admin or manager privileges
 * - May trigger audit logging for contract changes
 */
export class UpdateCommissionContractDto {
  /**
   * Contract Name
   *
   * The display name or title of the commission contract.
   * Used for identifying and referencing the contract in UI and reports.
   *
   * Business Significance:
   * - Human-readable identifier for the contract
   * - Used in dropdowns, reports, and administrative interfaces
   * - Should be descriptive but concise
   *
   * Naming Conventions:
   * - Typically includes institute/agent name and contract period
   * - May include commission type or tier information
   * - Should be unique for easy identification
   *
   * Example Values:
   * - "University of Melbourne - 2024 Commission Agreement"
   * - "ABC Agency - Tier 2 Commission Contract"
   * - "Q1 2024 Standard Commission Rates"
   *
   * Update Considerations:
   * - Changing name doesn't affect commission calculations
   * - Useful for correcting typos or improving clarity
   * - May require notification to affected parties
   *
   * @example "University of Melbourne - 2024 Commission Agreement"
   */
  @IsOptional()
  @IsString()
  @ApiPropertyOptional({
    description: 'Display name or title of the commission contract',
    example: 'University of Melbourne - 2024 Commission Agreement',
  })
  name?: string;

  /**
   * Display Order
   *
   * Numerical value used to control the display/sorting order of contracts.
   * Lower numbers typically appear first in lists and dropdowns.
   *
   * Business Significance:
   * - Controls UI presentation order
   * - Used for prioritizing frequently used contracts
   * - Important for user experience in selection interfaces
   *
   * Common Values:
   * - 0: Default/unspecified order
   * - 1: Highest priority (appears first)
   * - 10, 20, 30: Incremental ordering
   * - 999: Lowest priority (appears last)
   *
   * Use Cases:
   * - Reordering contracts in administrative interfaces
   * - Highlighting current/active contracts
   * - Grouping related contracts together
   *
   * Default Value:
   * - Typically defaults to 0 when not specified
   * - System may auto-increment for new contracts
   *
   * @example 1
   * @example 10
   */
  @IsOptional()
  @IsNumber({}, { message: 'order must be a number' })
  @ApiPropertyOptional({
    default: 0,
    description: 'Display/sorting order of the contract',
    example: 1,
  })
  order?: number;

  /**
   * Active Status
   *
   * Numeric flag indicating whether the contract is active/inactive.
   * Controls whether the contract can be used for new commission calculations.
   *
   * Business Significance:
   * - Active contracts can be used for new commission enquiries
   * - Inactive contracts are typically archived or expired
   * - Important for contract lifecycle management
   *
   * Common Status Codes:
   * - 0: Inactive/Archived (cannot be used for new calculations)
   * - 1: Active (available for new commission calculations)
   * - 2: Pending approval/Under review
   * - 3: Expired (automatically deactivated)
   *
   * Status Change Implications:
   * - Activating a contract makes it available for use
   * - Deactivating prevents new commissions but doesn't affect existing ones
   * - May trigger notifications to relevant stakeholders
   *
   * Default Value:
   * - Typically defaults to 0 (inactive) for safety
   * - Should be explicitly set to 1 for active contracts
   *
   * @example 1
   * @example 0
   */
  @IsOptional()
  @IsNumber({}, { message: 'active must be a number' })
  @ApiPropertyOptional({
    default: 0,
    description: 'Active status of the contract (0=inactive, 1=active)',
    example: 1,
    enum: [0, 1, 2, 3],
  })
  active?: number;
}
