/**
 * UpdateDto
 * ---------
 * Data Transfer Object used to update an existing Menu Group.
 *
 * Purpose:
 * - Validates update payload
 * - Ensures required identifiers are present
 * - Enforces consistent numeric/string validation via custom decorators
 *
 * Used in:
 * - MenuGroupsController.update()
 *
 * Design Notes:
 * - Uses `IsNumberOrStringDto` to support legacy payload formats
 * - Audit fields should be derived from session whenever possible
 */
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import {
  IsString,
  IsNotEmpty,
  IsOptional,
  IsNumberString,
} from 'class-validator';
import { IsNumberOrStringDto } from 'src/utils/common/numberOrStringDto';

export class UpdateDto {
  /**
   * Menu Group Identifier
   * ---------------------
   * Unique identifier of the menu group to be updated.
   *
   * Validation:
   * - Required field
   * - Must be a number or numeric string
   * - Minimum value enforced via custom decorator
   *
   * Why custom IsNumberOrStringDto?
   * - Centralizes number/string validation logic
   * - Provides consistent error messaging across DTOs
   *
   * Example:
   * 1 or "1"
   */
  @IsNotEmpty()
  @IsNumberOrStringDto(1, 'Id')
  id: number | string;

  /**
   * Menu Group Name
   * ---------------
   * Updated display name for the menu group.
   *
   * Validation:
   * - Required field
   * - Must be a non-empty string
   *
   * Swagger:
   * - Shown as required field with example
   */
  @IsNotEmpty()
  @IsString()
  @ApiProperty({ example: 'Menu Group is required' })
  name: string;

  /**
   * Display Order
   * -------------
   * Updated ordering index for menu group display.
   *
   * Validation:
   * - Required field
   * - Must be numeric or numeric string
   *
   * Business Rule:
   * - Lower numbers appear first in UI
   */
  @IsNotEmpty()
  @IsNumberOrStringDto(1, 'Order No')
  order_no: number | string;

  /**
   * Active Status
   * -------------
   * Updated active/inactive state of the menu group.
   *
   * Validation:
   * - Required field
   * - Must be numeric or numeric string
   *
   * Common Values:
   * - 1 → Active
   * - 0 → Inactive
   */
  @IsNotEmpty()
  @IsNumberOrStringDto(1, 'Status')
  active: number | string;

  /**
   * Modified By User (Optional)
   * ---------------------------
   * Represents the user who performed the update.
   *
   * Usage:
   * - Mainly for internal/system calls
   * - Typically overridden by session user ID in controller/service
   *
   * Validation:
   * - Optional field
   * - Must be numeric or numeric string if provided
   *
   * Security Note:
   * - Should never be trusted directly from client input
   */
  @IsOptional()
  @IsNumberString({}, { message: 'User ID must be a number or string' })
  @ApiPropertyOptional({ example: 1 })
  modified_by_user?: number | string;
}
