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

/**
 * Enumeration of all valid processing status values for a document.
 * <p>
 * Each status reflects the outcome or current state of a document in the
 * master record ({@code DocumentRecord}) or in a single attempt record
 * ({@code ProcessingAttempt}).
 * <p>
 * <strong>Overall-status semantics (master record):</strong>
 * <ul>
 *   <li>{@link #READY_FOR_AI} — document has passed all pre-checks and extracted text
 *       has been validated; it is ready for AI-based naming proposal. This is a non-terminal
 *       intermediate state; the document will be processed further in subsequent stages.</li>
 *   <li>{@link #PROPOSAL_READY} — a valid, persistent AI-based naming proposal has been
 *       generated and stored. The document is complete for the current stage but will be
 *       processed further in the next stage (target copy, final filename generation).
 *       This is a non-terminal intermediate state.</li>
 *   <li>{@link #SUCCESS} — document was fully processed end-to-end and written to the
 *       target location. Status is final and irreversible; skip in all future runs with
 *       {@link #SKIPPED_ALREADY_PROCESSED}.</li>
 *   <li>{@link #FAILED_RETRYABLE} — last attempt failed but is retryable; process again
 *       in the next run according to the applicable retry rule. This status is only
 *       valid as long as at least one further scheduler run is fachlich zulässig.</li>
 *   <li>{@link #FAILED_FINAL} — all allowed retries are exhausted; skip in all future
 *       runs with {@link #SKIPPED_FINAL_FAILURE}. This status is terminal and
 *       irreversible.</li>
 *   <li>{@link #PROCESSING} — document is currently being processed (transient, within a
 *       run); if found persisted after a crash, treat as {@link #FAILED_RETRYABLE}.</li>
 * </ul>
 * <p>
 * <strong>Attempt-status semantics (attempt history):</strong>
 * <ul>
 *   <li>{@link #READY_FOR_AI} — this attempt resulted in a document ready for AI processing.</li>
 *   <li>{@link #PROPOSAL_READY} — this attempt resulted in a valid AI-based naming proposal.</li>
 *   <li>{@link #SUCCESS} — this attempt completed successfully (end-to-end, including target copy).</li>
 *   <li>{@link #FAILED_RETRYABLE} — this attempt failed; a future attempt is allowed.</li>
 *   <li>{@link #FAILED_FINAL} — this attempt failed and no further attempts will be made.</li>
 *   <li>{@link #SKIPPED_ALREADY_PROCESSED} — this attempt was a skip because the
 *       document's overall status was already {@link #SUCCESS}.</li>
 *   <li>{@link #SKIPPED_FINAL_FAILURE} — this attempt was a skip because the document's
 *       overall status was already {@link #FAILED_FINAL}.</li>
 * </ul>
 * <p>
 * <strong>Terminal status rule:</strong>
 * {@link #SUCCESS} and {@link #FAILED_FINAL} are the only truly terminal statuses.
 * Documents with either of these statuses as their overall status are never reprocessed;
 * they receive a historised skip attempt instead. Documents with
 * {@link #FAILED_RETRYABLE}, {@link #READY_FOR_AI}, or {@link #PROPOSAL_READY} remain
 * verarbeitbar in future runs, subject to their applicable retry rule.
 * <p>
 * <strong>Transition to {@link #FAILED_FINAL} — retry exhaustion rules:</strong>
 * <ul>
 *   <li><em>Deterministic content errors</em>: The first historised deterministic content
 *       error leads to {@link #FAILED_RETRYABLE}. The second historised deterministic
 *       content error for the same fingerprint leads to {@link #FAILED_FINAL}. No further
 *       retry is possible after the second content error.</li>
 *   <li><em>Transient technical errors</em>: Each transient error increments the transient-error
 *       counter. When the counter reaches the configured {@code max.retries.transient} value
 *       (Integer &ge; 1), the attempt that reaches the limit transitions the document to
 *       {@link #FAILED_FINAL}. The value {@code 0} for {@code max.retries.transient} is
 *       invalid start configuration.</li>
 * </ul>
 * <p>
 * <strong>Immediate within-run target copy retry:</strong>
 * A single technical retry of the physical target-file copy step is permitted within the
 * same run. This mechanism is not a cross-run retry and does not increment the
 * transient-error counter. It does not change the document's overall status until the
 * outcome of the retry is known.
 * <p>
 * <strong>Counter rules:</strong>
 * <ul>
 *   <li>Only {@link #FAILED_RETRYABLE} and {@link #FAILED_FINAL} outcomes may increase
 *       a failure counter (content-error or transient-error counter).</li>
 *   <li>Skip outcomes ({@link #SKIPPED_ALREADY_PROCESSED}, {@link #SKIPPED_FINAL_FAILURE})
 *       never change any failure counter.</li>
 *   <li>A deterministic content error at first occurrence → {@link #FAILED_RETRYABLE},
 *       content-error counter +1.  At second occurrence → {@link #FAILED_FINAL},
 *       content-error counter +1 (cumulative total = 2).</li>
 *   <li>A transient technical error after a successful fingerprint → counter +1; status
 *       is {@link #FAILED_RETRYABLE} while counter &lt; {@code max.retries.transient},
 *       or {@link #FAILED_FINAL} when counter reaches {@code max.retries.transient}.</li>
 * </ul>
 * <p>
 * <strong>Document-level errors and batch exit code:</strong>
 * Document-level errors (content errors, transient errors, target copy failures) do not
 * escalate to exit-code&nbsp;1. The batch run continues with remaining documents and
 * exits with code&nbsp;0 as long as the run itself started cleanly. Exit-code&nbsp;1 is
 * reserved for hard start or bootstrap failures only.
 */
public enum ProcessingStatus {

    /**
     * Document has passed all pre-checks and extracted PDF text has been validated.
     * <p>
     * This is a non-terminal intermediate state. The document is ready to be processed
     * by AI-based naming in the next stage. A document with this status may be reprocessed
     * in later runs, and will be updated to a subsequent status (e.g., {@link #PROPOSAL_READY}
     * or failure) based on the outcome of the AI naming step.
     * <p>
     * The document may transition from this state to {@link #PROPOSAL_READY} on successful
     * AI-based naming, or to a failure status if the AI step fails.
     */
    READY_FOR_AI,

    /**
     * A valid, persistent AI-based naming proposal has been generated and stored.
     * <p>
     * This is a non-terminal intermediate state. The document is complete for its current
     * processing stage, but will be processed further in the next stage (target copy,
     * final filename generation with duplicate-suffix handling, and final success).
     * <p>
     * A document with this status will not be reprocessed by the AI step in future runs
     * (idempotency rule), but may still be processed further by subsequent stages.
     * The latest processing attempt with this status holds the authoritative naming proposal
     * (resolved date, title, reasoning) for subsequent stages.
     */
    PROPOSAL_READY,

    /**
     * Document was successfully processed and written to the target location.
     * <p>
     * This status is reserved for the true end-to-end success after the target copy
     * stage is complete. A document with this status will be skipped in all future batch runs.
     * Status is final and irreversible.
     */
    SUCCESS,

    /**
     * Processing failed with a transient error (temporary infrastructure problem).
     * <p>
     * Examples: API timeout, temporary file lock, momentary network issue.
     * <p>
     * A document with this status may be retried in a later batch run, up to the
     * configured maximum retry count. Retry count is tracked separately.
     */
    FAILED_RETRYABLE,

    /**
     * Processing has failed finally and irrecoverably — no further retries will be attempted.
     * <p>
     * This status is reached after all allowed retries for a document are exhausted.
     * For deterministic content errors (no usable text, page limit exceeded) this means
     * the second occurrence of the error. For other error types, it means the configured
     * maximum retry count has been reached.
     * <p>
     * A document with this overall status is skipped in all future batch runs and
     * a {@link #SKIPPED_FINAL_FAILURE} attempt is historised.
     */
    FAILED_FINAL,

    /**
     * Document was skipped because it has already been successfully processed.
     * <p>
     * This is a final skip state. The document will remain skipped in all future runs.
     * Document fingerprint matching ensures that identical content is never reprocessed.
     */
    SKIPPED_ALREADY_PROCESSED,

    /**
     * Document was skipped because it has already failed finally.
     * <p>
     * This is a final skip state. The document will remain skipped in all future runs.
     * No further processing attempts will be made.
     */
    SKIPPED_FINAL_FAILURE,

    /**
     * Technical transient status: Document is currently being processed.
     * <p>
     * This status is used internally during a batch run to mark documents
     * that are actively being worked on. If a batch run is interrupted,
     * documents in this state will be re-attempted in the next run.
     * <p>
     * This status should not persist across batch runs in normal operation.
     */
    PROCESSING
}
