// Import Swagger decorator for API documentation
import { ApiProperty } from '@nestjs/swagger';

// Import class-validator decorators for input validation
import { IsEnum, IsNotEmpty, IsArray } from 'class-validator';

// Import custom enum for type-safe status actions
import { StatusAction } from 'src/utils/enums/enum';

/**
 * UpdateStatusDto - Data Transfer Object for bulk status updates
 *
 * This DTO is used for activating or deactivating multiple records in bulk.
 * It provides a standardized way to handle status changes across the application.
 *
 * Purpose:
 * - Bulk activation/deactivation of records (menus, users, products, etc.)
 * - Consistent status management across different entities
 * - Transaction-safe batch operations
 *
 * Business Context:
 * - Used in admin interfaces for mass updates
 * - Provides undo/redo capability for status changes
 * - Tracks which user performed the bulk action
 * - Typically updates the 'active' field in database records
 *
 * Example Usage:
 * - POST /menus/update-status
 * - Body: { "action": "activate", "ids": [1, 2, 3, 4] }
 * - Result: Activates menus with IDs 1, 2, 3, and 4
 */
export class UpdateStatusDto {
  /**
   * action - Specifies whether to activate or deactivate the records
   *
   * Validation Rules:
   * - @IsNotEmpty(): Required field - must be provided
   * - @IsEnum(StatusAction): Must be one of the StatusAction enum values
   * - Custom error message for better UX
   *
   * Swagger Documentation:
   * - @ApiProperty({ enum: StatusAction }): Shows as dropdown in Swagger UI
   * - Documents available options clearly
   *
   * Type Safety:
   * - Uses StatusAction enum for compile-time validation
   * - Prevents invalid string values at runtime
   *
   * Business Context:
   * - "activate": Sets active status to true/1
   * - "deactivate": Sets active status to false/0
   * - Consistent across all entities using this DTO
   *
   * Likely Enum Definition:
   * enum StatusAction {
   *   ACTIVATE = 'activate',
   *   DEACTIVATE = 'deactivate'
   * }
   */
  @IsNotEmpty()
  @IsEnum(StatusAction, {
    message: 'action must be either activate or deactivate',
  })
  @ApiProperty({ enum: StatusAction })
  action: StatusAction;

  /**
   * ids - Array of record IDs to update
   *
   * Validation Rules:
   * - @IsNotEmpty(): Required field - cannot be empty array
   * - @IsArray(): Must be an array type
   *
   * Swagger Documentation:
   * - @ApiProperty({ type: [Number] }): Documents as number array
   *
   * Business Context:
   * - Supports bulk operations on multiple records
   * - Typically used with checkboxes or multi-select in UI
   * - IDs should be valid existing record IDs
   *
   * Implementation Considerations:
   * - Service should validate that all IDs exist
   * - Transaction should be used for data consistency
   * - Should handle large arrays efficiently
   *
   * Security Considerations:
   * - Should validate user has permission to update all IDs
   * - Should check for ownership/scope if applicable
   *
   * Performance Considerations:
   * - Large arrays may need chunking or batch processing
   * - Database should have proper indexes on ID fields
   */
  @IsNotEmpty()
  @IsArray()
  @ApiProperty({ type: [Number] })
  ids: number[];
}
