package de.gecheckt.pdf.umbenenner.application.port.in;

/**
 * Aggregated status classification reported to
 * {@link BatchRunProgressObserver#onDocumentCompleted(DocumentCompletionEvent)}
 * for one processed candidate.
 * <p>
 * This enum collapses the finer-grained internal processing status into five
 * buckets that an observer (e.g. a GUI progress view) needs to distinguish:
 * successful completion, retryable failure, permanent failure, and two explicit
 * skip variants.
 * <p>
 * This classification is purely an observability concern — persistence,
 * retry decisions, and all other processing rules continue to work against the
 * detailed internal status.
 */
public enum DocumentCompletionStatus {

    /**
     * The candidate was successfully renamed; the target copy is in place and the
     * persistence is consistent.
     */
    SUCCESS,

    /**
     * The candidate failed in the current run but will be retried in a later run
     * (transient technical error, not yet at the retry limit, or a first deterministic
     * content error).
     */
    FAILED_RETRYABLE,

    /**
     * The candidate failed permanently and will not be retried in later runs
     * (content error recorded twice, or transient retry budget exhausted).
     */
    FAILED_PERMANENT,

    /**
     * Der Kandidat wurde übersprungen, weil er in einem früheren Lauf bereits
     * erfolgreich verarbeitet wurde. Der Gesamtstatus im Stammsatz lautet
     * {@code SUCCESS}.
     */
    SKIPPED_ALREADY_PROCESSED,

    /**
     * Der Kandidat wurde übersprungen, weil er in einem früheren Lauf bereits
     * endgültig fehlgeschlagen ist. Der Gesamtstatus im Stammsatz lautet
     * {@code FAILED_FINAL}.
     */
    SKIPPED_FINAL_FAILURE
}
