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

/**
 * Enumeration of pre-check failure reasons.
 * <p>
 * These are the deterministic content errors that can occur during pre-check evaluation.
 * They distinguish between failures in the document content versus technical extraction failures.
 * <p>
 * Deterministic content errors:
 * <ul>
 *   <li>{@link #NO_USABLE_TEXT}: The extracted text contains no meaningful content after normalization.</li>
 *   <li>{@link #PAGE_LIMIT_EXCEEDED}: The document exceeds the configured page limit.</li>
 *   <li>{@link #CONTENT_NOT_EXTRACTABLE}: The PDF content cannot be extracted due to structural issues.</li>
 * </ul>
 * <p>
 * Note: Technical extraction failures (I/O errors, PDFBox failures) are not pre-check reasons;
 * they are represented as {@link PdfExtractionTechnicalError} in the extraction result.
 */
public enum PreCheckFailureReason {
    /**
     * The extracted PDF text, after normalization, contains no letters or digits.
     * <p>
     * This is a deterministic content error: reprocessing the same file in a later run
     * will have the same outcome unless the source file is changed (e.g. by adding OCR).
     * <p>
     * Retry logic: no retry — the document is immediately finalised to
     * {@link ProcessingStatus#FAILED_FINAL}.
     */
    NO_USABLE_TEXT("No usable text in extracted PDF content"),

    /**
     * The document's page count exceeds the configured limit.
     * <p>
     * This is a deterministic content error: the page count will not change unless the source file is modified.
     * <p>
     * Retry logic: exactly 1 retry in a later batch run.
     */
    PAGE_LIMIT_EXCEEDED("Document page count exceeds configured limit"),

    /**
     * The PDF content cannot be extracted due to structural issues in the document.
     * <p>
     * This is a deterministic content error: reprocessing the same file in a later run
     * will have the same outcome unless the source file is changed.
     * <p>
     * Examples: Password-protected PDFs, corrupted internal structure, unsupported encryption.
     * <p>
     * Retry logic: exactly 1 retry in a later batch run.
     */
    CONTENT_NOT_EXTRACTABLE("PDF content not extractable");

    private final String description;

    PreCheckFailureReason(String description) {
        this.description = description;
    }

    /**
     * Returns a human-readable description of this failure reason.
     *
     * @return the description
     */
    public String getDescription() {
        return description;
    }
}