package de.gecheckt.pdf.umbenenner.domain.model;

/**
 * Classification of AI-related errors into technical vs. functional categories.
 * <p>
 * This enumeration distinguishes between two fundamental error types that occur
 * during AI-based naming proposal generation:
 * <ul>
 *   <li><strong>Technical errors</strong>: Infrastructure or communication failures
 *       (e.g., API unreachable, timeout, unparseable response). These are typically
 *       transient and retryable.</li>
 *   <li><strong>Functional errors</strong>: Problems with the AI response content itself
 *       (e.g., invalid title, unparseable date, generic placeholder title).
 *       These are deterministic and typically not resolved by retry alone.</li>
 * </ul>
 * <p>
 * The classification determines retry behavior: technical errors may be retried in
 * a later run, while functional errors are subject to the deterministic failure rule
 * (first occurrence retryable, second occurrence final).
 *
 */
public enum AiErrorClassification {

    /**
     * A technical infrastructure or communication failure occurred.
     * <p>
     * Examples: API endpoint not reachable, HTTP timeout, malformed response structure,
     * missing mandatory fields in otherwise-parseable JSON, network error.
     * <p>
     * These errors are typically transient and may be resolved by retry in a later
     * batch run. The failure is recorded against the transient-error counter.
     */
    TECHNICAL,

    /**
     * A functional or content validation error occurred.
     * <p>
     * Examples: invalid or generic title (e.g., "Dokument"), unparseable date string,
     * AI response violates documented rules (e.g., title contains prohibited characters).
     * <p>
     * These errors are deterministic and reflect issues with the AI-generated content
     * itself or the document's content quality. The failure is recorded against the
     * content-error counter, subject to the deterministic retry rule.
     */
    FUNCTIONAL
}
