// Import class-validator decorators for input validation
import { IsString, IsNotEmpty, IsOptional, IsNumber } from 'class-validator';

/**
 * MenuActionDto - Data Transfer Object for menu action/permission definitions
 *
 * This DTO defines the structure for individual actions associated with a menu item.
 * Menu actions typically represent operations/permissions that can be performed
 * on a menu's associated functionality (e.g., CRUD operations, special actions).
 *
 * Purpose:
 * - Defines permissions/operations available for a specific menu
 * - Used when creating or updating menu items with associated actions
 * - Enables granular permission control in the application
 *
 * Business Context:
 * - Each menu can have multiple actions (view, create, edit, delete, export, etc.)
 * - Actions can be role-based or permission-based
 * - Used for building dynamic permission systems and UI controls
 *
 * Example Usage:
 * - Menu "User Management" might have actions: ["view_users", "create_user", "edit_user", "delete_user"]
 * - These actions can be assigned to user roles for access control
 */
export class MenuActionDto {
  /**
   * active - Status flag for the menu action
   *
   * Validation Rules:
   * - @IsNumber(): Must be a numeric value
   *
   * Business Context:
   * - Controls whether this action is active/available
   * - Typically boolean (0 = inactive, 1 = active)
   * - Allows disabling actions without removing them
   *
   * Example Values:
   * - 1: Action is active and can be used/permissioned
   * - 0: Action is inactive and hidden from permission systems
   */
  @IsNumber()
  active: number;

  /**
   * title - Display name of the action
   *
   * Validation Rules:
   * - @IsString(): Must be a string value
   * - @IsNotEmpty(): Required field with custom error message
   *
   * Business Context:
   * - User-friendly name shown in permission management interfaces
   * - Should be descriptive and clear for administrators
   *
   * Example Values:
   * - "View Users", "Create Report", "Export Data", "Approve Request"
   */
  @IsString()
  @IsNotEmpty({ message: 'Title is required' })
  title: string;

  /**
   * action - Unique identifier/code for the action
   *
   * Validation Rules:
   * - @IsString(): Must be a string value
   * - @IsNotEmpty(): Required field with custom error message
   *
   * Business Context:
   * - Machine-readable identifier used in code/permission checks
   * - Should follow consistent naming conventions
   * - Used in backend permission validation
   *
   * Example Values:
   * - "view", "create", "edit", "delete", "export", "approve"
   * - Often prefixed with resource name: "user_view", "report_create"
   */
  @IsString()
  @IsNotEmpty({ message: 'Action is required' })
  action: string;

  /**
   * is_visible - Controls UI visibility of the action
   *
   * Validation Rules:
   * - @IsNumber(): Must be a numeric value
   *
   * Business Context:
   * - Determines if the action appears in UI permission controls
   * - Allows hiding actions from permission assignment interfaces
   * - Different from "active" - visible doesn't mean it's usable
   *
   * Example Values:
   * - 1: Action appears in permission management UI
   * - 0: Action is hidden from UI (but might still exist in system)
   */
  @IsNumber()
  is_visible: number;

  /**
   * order_no - Display order/sequence for action presentation
   *
   * Validation Rules:
   * - @IsNumber(): Must be a numeric value
   * - @IsOptional(): Optional field - not required
   *
   * Business Context:
   * - Determines sort order when displaying actions in lists
   * - Lower numbers typically appear first
   * - Useful for organizing actions in admin interfaces
   *
   * Default Behavior:
   * - If not provided, might use database default or natural order
   */
  @IsNumber()
  @IsOptional()
  order_no?: number;

  /**
   * platform - Platform/application context for the action
   *
   * Validation Rules:
   * - @IsNumber(): Must be a numeric value
   * - @IsOptional(): Optional field - not required
   *
   * Business Context:
   * - May indicate which platform/app the action belongs to
   * - Useful in multi-platform systems (web, mobile, admin, etc.)
   * - Could reference a platform ID from a platforms table
   *
   * Example Values:
   * - 1: Web platform
   * - 2: Mobile app
   * - 3: Admin panel
   * - 4: API access
   */
  @IsNumber()
  @IsOptional()
  platform?: number;
}
