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

/**
 * Update Menu Actions Data Transfer Object (DTO)
 *
 * This DTO is used for updating existing menu action entries in the application.
 * Menu actions represent individual operations or permissions that can be performed
 * within menu items (e.g., "create", "read", "update", "delete", "export").
 *
 * Unlike the CreateMenuActionsDto, this DTO has all fields as optional to support
 * partial updates (PATCH semantics). Clients can update only the fields they want
 * to change without having to provide all required fields.
 *
 * @example
 * // Update only the display order:
 * {
 *   "order": 2
 * }
 *
 * @example
 * // Update multiple fields:
 * {
 *   "name": "create_user_account",
 *   "order": 1,
 *   "is_visible": 1,
 *   "active": 1
 * }
 *
 * @example
 * // Hide a menu action:
 * {
 *   "is_visible": 0,
 *   "active": 0
 * }
 *
 * @note The field name inconsistency: 'order_no' in CreateDto vs 'order' in UpdateDto
 * This could cause mapping issues in the service layer.
 */
export class UpdateMenuActionsDto {
  /**
   * Updated unique identifier/name for the menu action.
   *
   * @type {string}
   * @optional
   * @example "create_user_account"
   * @example "export_commission_reports"
   *
   * @isString - Validation: Must be a string if provided
   *   Error message: "name must be a string"
   *
   * @isOptional - Validation: Field is not required for updates
   *
   * @note Consider adding pattern validation for consistency:
   *   @Matches(/^[a-z_]+$/, { message: 'Name must be lowercase with underscores' })
   */
  @ApiPropertyOptional({
    description:
      'Updated unique identifier/name for the menu action (snake_case)',
    example: 'create_user_account',
    type: String,
  })
  @IsOptional()
  @IsString({ message: 'Action name must be a string if provided' })
  name?: string;

  /**
   * Updated display order of the menu action within its parent menu.
   * Note: Field name is 'order' but CreateDto uses 'order_no' - potential inconsistency.
   *
   * @type {number}
   * @optional
   * @default 0
   * @example 1 (first position)
   * @example 5 (fifth position)
   *
   * @isNumber - Validation: Must be a number if provided
   *   Error message: "order must be a number"
   *
   * @isOptional - Validation: Field is not required for updates
   *
   * @bug Field name inconsistency: Should be 'order_no' to match CreateMenuActionsDto
   * @note Consider adding range validation:
   *   @Min(0, { message: 'Order cannot be negative' })
   *   @Max(999, { message: 'Order cannot exceed 999' })
   */
  @ApiPropertyOptional({
    description:
      'Updated display order within parent menu (lower numbers appear first)',
    example: 1,
    type: Number,
    default: 0,
    minimum: 0,
    maximum: 999,
  })
  @IsOptional()
  @IsNumber({}, { message: 'Display order must be a number if provided' })
  @Min(0, { message: 'Display order cannot be negative' })
  @Max(999, { message: 'Display order cannot exceed 999' })
  order?: number; // BUG: Should be 'order_no' to match CreateMenuActionsDto

  /**
   * Updated visibility flag for the menu action in the UI.
   *
   * @type {number}
   * @optional
   * @default 0
   * @example 1 (visible in UI)
   * @example 0 (hidden from UI)
   *
   * @isNumber - Validation: Must be a number if provided
   *   Error message: "Is Visible must be a number"
   *
   * @isOptional - Validation: Field is not required for updates
   *
   * @note Consider using boolean or enum for better semantics
   */
  @ApiPropertyOptional({
    description: 'Updated UI visibility flag (1 = visible, 0 = hidden)',
    example: 1,
    type: Number,
    default: 0,
    enum: [0, 1],
  })
  @IsOptional()
  @IsNumber({}, { message: 'Visibility flag must be a number if provided' })
  is_visible?: number;

  /**
   * Updated platform identifier for the menu action.
   *
   * @type {number}
   * @optional
   * @default 1
   * @example 1 (web platform)
   * @example 2 (mobile platform)
   * @example 3 (admin platform)
   *
   * @isNumber - Validation: Must be a number if provided
   *   Error message: "Platform must be a number"
   *
   * @isOptional - Validation: Field is not required for updates
   *
   * @note Consider using an enum for platform types
   */
  @ApiPropertyOptional({
    description: 'Updated platform identifier (1=web, 2=mobile, 3=admin, etc.)',
    example: 2,
    type: Number,
    default: 1,
  })
  @IsOptional()
  @IsNumber({}, { message: 'Platform identifier must be a number if provided' })
  platform?: number;

  /**
   * Updated activation status of the menu action.
   *
   * @type {number}
   * @optional
   * @default 0
   * @example 1 (active/available)
   * @example 0 (inactive/unavailable)
   *
   * @isNumber - Validation: Must be a number if provided
   *   Error message: "active must be a number"
   *
   * @isOptional - Validation: Field is not required for updates
   *
   * @note Consider using boolean or enum for better semantics
   */
  @ApiPropertyOptional({
    description: 'Updated activation status (1 = active, 0 = inactive)',
    example: 1,
    type: Number,
    default: 0,
    enum: [0, 1],
  })
  @IsOptional()
  @IsNumber({}, { message: 'Active status must be a number if provided' })
  active?: number;
}
