/**
 * CreateDto
 * ---------
 * Data Transfer Object used for creating a new Menu Group.
 *
 * Purpose:
 * - Defines the expected request payload structure
 * - Applies validation rules using class-validator
 * - Generates Swagger API documentation automatically
 *
 * Used in:
 * - MenuGroupsController.create()
 *
 * Validation Flow:
 * - Incoming request body is transformed & validated by ValidationPipe
 * - If validation fails, NestJS automatically returns a 400 Bad Request
 */
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import {
  IsString,
  IsNotEmpty,
  IsNumberString,
  IsOptional,
} from 'class-validator';

export class CreateDto {
  /**
   * Menu Group Name
   * ---------------
   * Human-readable name for the menu group.
   *
   * Validation:
   * - Must be present in request body
   * - Must be a non-empty string
   *
   * Swagger:
   * - Appears as required field in API docs
   *
   * Example:
   * "Administration"
   */
  @IsNotEmpty()
  @IsString()
  @ApiProperty({ example: 'Menu Group is required' })
  name: string;

  /**
   * Display Order
   * -------------
   * Determines the ordering of menu groups in UI navigation.
   *
   * Validation:
   * - Required field
   * - Accepts numeric strings (e.g., "1", "10")
   *
   * Why IsNumberString instead of IsNumber?
   * - HTTP request bodies often send numbers as strings
   * - Avoids transformation issues without enabling implicit conversion
   *
   * Swagger:
   * - Default value shown as 0
   */
  @IsNotEmpty()
  @IsNumberString({}, { message: 'Order must be a number or string' })
  @ApiProperty({ default: 0 })
  order_no: number | string;

  /**
   * Active Status
   * -------------
   * Indicates whether the menu group is active or inactive.
   *
   * Common Values:
   * - 1 => Active
   * - 0 => Inactive
   *
   * Validation:
   * - Required field
   * - Must be numeric or numeric string
   *
   * Design Note:
   * - Stored as number/string to support legacy DB schemas
   * - Converted to proper boolean/number in service layer if needed
   *
   * Swagger:
   * - Default value shown as "1"
   */
  @IsNotEmpty()
  @IsNumberString({}, { message: 'Status must be a number or string' })
  @ApiProperty({ default: '1' })
  active: number | string;

  /**
   * Action User ID (Optional)
   * -------------------------
   * Represents the user who initiated the create action.
   *
   * Usage:
   * - Mainly for system-level calls
   * - Usually overridden by session user ID in controller/service
   *
   * Validation:
   * - Optional field
   * - If provided, must be numeric or numeric string
   *
   * Security Note:
   * - Should NOT be trusted blindly from client
   * - Session user ID should always take precedence
   *
   * Swagger:
   * - Marked as optional field
   */
  @IsOptional()
  @IsNumberString({}, { message: 'User ID must be a number or string' })
  @ApiPropertyOptional({ example: 1 })
  by_user?: number | string;
}
