Exception Handling

/**
 * Business exception handler for domain-specific application logic failures.
 * Complements GlobalExceptionHandler by focusing on Smart Supply Pro business rules.
 */
@Order(Ordered.HIGHEST_PRECEDENCE)  // Runs BEFORE GlobalExceptionHandler
@RestControllerAdvice
public class BusinessExceptionHandler {

    /**
     * Handles custom validation failures with field-level details.
     * Example: Quantity validation, price validation, format validation
     */
    @ExceptionHandler(InvalidRequestException.class)
    public ResponseEntity<ErrorResponse> handleInvalidRequest(InvalidRequestException ex) {
        String message = ex.hasFieldErrors()
            ? "Validation failed: " + ex.getFieldErrors().size() + " field error(s)"
            : (ex.getMessage() != null ? ex.getMessage() : "Invalid request");
        
        return ErrorResponse.builder()
                .status(HttpStatus.BAD_REQUEST)
                .message(message)
                .build();
    }

    /**
     * Handles uniqueness constraint violations.
     * Example: Duplicate supplier name, duplicate item (name + price)
     */
    @ExceptionHandler(DuplicateResourceException.class)
    public ResponseEntity<ErrorResponse> handleDuplicateResource(DuplicateResourceException ex) {
        String message = ex.hasDetailedContext()
            ? ex.getClientMessage()
            : (ex.getMessage() != null ? ex.getMessage() : "Duplicate resource");
        
        return ErrorResponse.builder()
                .status(HttpStatus.CONFLICT)
                .message(message)
                .build();
    }

    /**
     * Handles business state violations.
     * Example: Cannot delete supplier with linked items
     */
    @ExceptionHandler(IllegalStateException.class)
    public ResponseEntity<ErrorResponse> handleBusinessStateConflict(IllegalStateException ex) {
        String message = (ex.getMessage() != null && !ex.getMessage().isBlank())
            ? ex.getMessage()
            : "Business rule conflict";
        
        return ErrorResponse.builder()
                .status(HttpStatus.CONFLICT)
                .message(message)
                .build();
    }
}

@Order(Ordered.HIGHEST_PRECEDENCE + 1)  // Runs AFTER BusinessExceptionHandler as catch-all
@RestControllerAdvice
public class GlobalExceptionHandler {

    // 1. JSR-380 VALIDATION FAILURES
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
        // Extracts first @Valid error for client feedback
        String message = ex.getBindingResult().getFieldErrors().stream()
                .findFirst()
                .map(fe -> fe.getField() + " " + fe.getDefaultMessage())
                .orElse("Validation failed");
        
        return ErrorResponse.builder()
                .status(HttpStatus.BAD_REQUEST)
                .message(sanitize(message))
                .build();
    }

    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<ErrorResponse> handleConstraint(ConstraintViolationException ex) {
        // Extracts JSR-380 constraint violation (@NotNull, @NotBlank, etc.)
        String message = ex.getConstraintViolations().stream()
                .findFirst()
                .map(v -> v.getPropertyPath() + " " + v.getMessage())
                .orElse("Constraint violation");
        
        return ErrorResponse.builder()
                .status(HttpStatus.BAD_REQUEST)
                .message(sanitize(message))
                .build();
    }

    // 2. SECURITY EXCEPTIONS
    
    @ExceptionHandler(AuthenticationException.class)
    public ResponseEntity<ErrorResponse> handleAuthentication(AuthenticationException ex) {
        // Generic message prevents user enumeration attacks
        return ErrorResponse.builder()
                .status(HttpStatus.UNAUTHORIZED)
                .message("Authentication required")
                .build();
    }

    @ExceptionHandler(AccessDeniedException.class)
    public ResponseEntity<ErrorResponse> handleAuthorization(AccessDeniedException ex) {
        // Generic message prevents unauthorized access hints
        return ErrorResponse.builder()
                .status(HttpStatus.FORBIDDEN)
                .message("Access denied")
                .build();
    }

    // 3. SAFETY NET - Sanitizes error messages to prevent information disclosure
    
    private String sanitize(String message) {
        if (message == null) return "Unknown error";
        
        return message
            .replaceAll("\\b[A-Za-z]:\\\\[\\w\\\\.-]+", "[PATH]")           // Windows paths
            .replaceAll("/[\\w/.-]+\\.(java|class)", "[INTERNAL]")         // Unix paths
            .replaceAll("\\bcom\\.smartsupplypro\\.[\\w.]+", "[INTERNAL]") // Package names
            .replaceAll("(?i)\\bSQL.*", "Database operation failed")       // SQL fragments
            .replaceAll("(?i)\\bPassword.*", "Authentication failed")      // Credentials
            .replaceAll("(?i)\\bToken.*", "Authentication failed")         // Tokens
            .trim();
    }
}

/**
 * Enterprise exception for validation failures.
 * Supports field-level errors and severity classification.
 */
public class InvalidRequestException extends RuntimeException {
    
    private final ValidationSeverity severity;
    private final String validationCode;
    private final Map<String, String> fieldErrors;
    private final List<String> generalErrors;

    // Constructors
    public InvalidRequestException(String message) { }
    
    public InvalidRequestException(String message, ValidationSeverity severity, 
                                   String validationCode) { }
    
    public InvalidRequestException(String message, Map<String, String> fieldErrors) { }

    // Accessors
    public ValidationSeverity getSeverity() { }
    public String getValidationCode() { }
    public Map<String, String> getFieldErrors() { }
}

// Severity levels
public enum ValidationSeverity {
    LOW,      // Informational - doesn't block operation
    MEDIUM,   // Standard validation failure - operation blocked
    HIGH      // Critical - security or integrity concern
}

/**
 * Enterprise exception for uniqueness constraint violations.
 * Provides detailed conflict context for client error handling.
 */
public class DuplicateResourceException extends RuntimeException {
    
    private final String conflictField;
    private final String existingResourceId;
    private final Map<String, String> conflictDetails;

    public DuplicateResourceException(String message) { }
    
    public DuplicateResourceException(String message, String conflictField, 
                                      String existingResourceId) { }
    
    // Accessors for conflict resolution
    public String getConflictField() { }
    public String getExistingResourceId() { }
}

{
  "status": "BAD_REQUEST",
  "statusCode": 400,
  "message": "Validation failed: name cannot be empty",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "path": "/api/inventory/items"
}

POST /api/inventory/items
{
  "name": "",
  "quantity": 100,
  "price": 25.50,
  "supplierId": "SUPP-001"
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "status": "BAD_REQUEST",
  "statusCode": 400,
  "message": "name cannot be empty",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "path": "/api/inventory/items"
}

PUT /api/inventory/items/ITEM-123
{
  "name": "Widget A",
  "quantity": 100,
  "price": 25.50,
  "supplierId": "SUPP-001"
}

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "status": "CONFLICT",
  "statusCode": 409,
  "message": "Another inventory item with this name and price already exists",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "path": "/api/inventory/items/ITEM-123"
}

POST /api/inventory/items/ITEM-123/adjust
{
  "delta": -150
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "status": "UNPROCESSABLE_ENTITY",
  "statusCode": 422,
  "message": "Resulting stock cannot be negative",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "path": "/api/inventory/items/ITEM-123/adjust"
}

PUT /api/inventory/items/ITEM-123
{
  "name": "Widget A",
  "quantity": 150,
  "price": 99.99,  ← USER cannot modify price
  "supplierId": "SUPP-001"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "status": "FORBIDDEN",
  "statusCode": 403,
  "message": "Access denied",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "path": "/api/inventory/items/ITEM-123"
}

// ✅ Good: Specific exception for business context
throw new DuplicateResourceException("Supplier already exists");
throw new InvalidRequestException("Quantity must be non-negative");
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Item not found");

// ❌ Avoid: Generic exceptions
throw new RuntimeException("Error");
throw new Exception("Something failed");

// ✅ Good: Sanitized messages prevent information disclosure
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Item not found");

// ❌ Avoid: Exposing internal details
throw new ResponseStatusException(HttpStatus.NOT_FOUND, 
    "Item not found in inventory_items table on sspdb database");

// GlobalExceptionHandler automatically removes:
// - File paths: C:\Users\... → [PATH]
// - Class names: com.smartsupplypro.* → [INTERNAL]
// - SQL fragments: SQL syntax error → Database operation failed
// - Credentials: password, token fields → Authentication failed

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleUnexpected(Exception ex) {
    String correlationId = MDC.get("correlationId");  // From request context
    
    logger.error("Unexpected error [{}]", correlationId, ex);
    
    return ErrorResponse.builder()
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .message("Unexpected server error")
            .build();
}