// ABOUTME: Custom exception class for validation errors with detailed error information
// ABOUTME: Provides structured validation error handling with recovery suggestions and error categorization

import '../services/validation_service.dart';

/// Custom exception for validation errors
class ValidationException implements Exception {
  final String message;
  final String? details;
  final String? field;
  final List<String> errors;
  final List<String> warnings;
  final String? suggestedAction;
  final ValidationErrorType type;

  const ValidationException({
    required this.message,
    this.details,
    this.field,
    this.errors = const [],
    this.warnings = const [],
    this.suggestedAction,
    this.type = ValidationErrorType.fieldValidation,
  });

  /// Create from validation result
  factory ValidationException.fromValidationResult(
    String field,
    ValidationResult result, {
    ValidationErrorType? type,
  }) {
    return ValidationException(
      message: result.errors.isNotEmpty 
          ? result.errors.first 
          : 'Validation failed for $field',
      details: result.errors.length > 1 
          ? result.errors.skip(1).join('\n') 
          : null,
      field: field,
      errors: result.errors,
      warnings: result.warnings,
      suggestedAction: 'Please correct the $field value and try again',
      type: type ?? ValidationErrorType.fieldValidation,
    );
  }

  /// Create for duplicate entry
  factory ValidationException.duplicate({
    required String message,
    String? field,
    String? details,
  }) {
    return ValidationException(
      message: message,
      details: details,
      field: field,
      type: ValidationErrorType.duplicate,
      suggestedAction: 'Please verify this is not a duplicate entry',
    );
  }

  /// Create for range validation
  factory ValidationException.range({
    required String field,
    required String message,
    String? details,
  }) {
    return ValidationException(
      message: message,
      details: details,
      field: field,
      type: ValidationErrorType.range,
      suggestedAction: 'Please enter a value within the valid range',
    );
  }

  /// Create for required field validation
  factory ValidationException.required({
    required String field,
  }) {
    return ValidationException(
      message: '$field is required',
      field: field,
      type: ValidationErrorType.required,
      suggestedAction: 'Please enter a value for $field',
    );
  }

  /// Create for business rule validation
  factory ValidationException.businessRule({
    required String message,
    String? details,
    String? suggestedAction,
  }) {
    return ValidationException(
      message: message,
      details: details,
      type: ValidationErrorType.businessRule,
      suggestedAction: suggestedAction ?? 'Please check the business rules',
    );
  }

  @override
  String toString() {
    return 'ValidationException: $message${field != null ? ' (Field: $field)' : ''}';
  }

  /// Get user-friendly error message
  String getUserFriendlyMessage() {
    switch (type) {
      case ValidationErrorType.required:
        return 'Required field is missing: ${field ?? 'unknown field'}';
      case ValidationErrorType.range:
        return 'Value is outside valid range: $message';
      case ValidationErrorType.duplicate:
        return 'Duplicate entry detected: $message';
      case ValidationErrorType.businessRule:
        return 'Business rule violation: $message';
      case ValidationErrorType.fieldValidation:
      default:
        return message;
    }
  }
}

/// Types of validation errors
enum ValidationErrorType {
  /// Field-level validation error
  fieldValidation,
  
  /// Required field error
  required,
  
  /// Value range error
  range,
  
  /// Duplicate entry error
  duplicate,
  
  /// Business rule violation
  businessRule,
}

