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

/**
 * Value object representing the outcome of a batch processing run.
 * <p>
 * This enum encodes the high-level result of executing a complete batch cycle,
 * allowing Bootstrap and CLI layers to map outcomes to exit codes and log messages
 * in a controlled and consistent manner.
 * <p>
 * The outcome is independent of individual document processing results;
 * it represents the batch operation itself (lock acquired, no critical startup failure, etc.).
 * <p>
 * Design Note: This contract enables exit code handling to derive exit codes systematically
 * without requiring additional knowledge about the batch run. Each outcome maps cleanly
 * to an exit code semantic.
 * <p>
 * Three distinct outcomes are defined to make the difference between a technically successful run,
 * a controlled early termination due to start protection, and a hard bootstrap failure
 * explicit in both code and logs.
 */
public enum BatchRunOutcome {

    /**
     * Batch processing completed successfully.
     * <p>
     * The run acquired the lock, started cleanly, and completed the full processing cycle.
     * Individual documents within the run may have succeeded or failed, but that is
     * transparent to this outcome. The run itself executed as intended.
     * <p>
     * Maps to exit code 0.
     */
    SUCCESS("Batch processing completed successfully"),

    /**
     * Batch run aborted because another instance is already running.
     * <p>
     * The run lock could not be acquired because a concurrent instance holds it.
     * This is a controlled, expected termination (start protection), not a hard failure.
     * The new instance terminates immediately without performing any processing.
     * <p>
     * Maps to exit code 1.
     *
     */
    LOCK_UNAVAILABLE("Another instance is already running; this run terminates immediately"),

    /**
     * Batch processing failed due to an unexpected error.
     * <p>
     * The run encountered a critical error that prevented normal batch completion,
     * such as an unrecoverable I/O error or infrastructure failure.
     * <p>
     * Maps to exit code 1.
     */
    FAILURE("Batch processing failed");

    private final String message;

    BatchRunOutcome(String message) {
        this.message = message;
    }

    /**
     * Returns a human-readable message for this outcome.
     *
     * @return descriptive message suitable for logging
     */
    public String message() {
        return message;
    }

    /**
     * Returns true if this outcome represents successful completion.
     *
     * @return true if outcome is {@link #SUCCESS}, false otherwise
     */
    public boolean isSuccess() {
        return this == SUCCESS;
    }

    /**
     * Returns true if this outcome represents any non-successful result.
     * <p>
     * Both {@link #FAILURE} and {@link #LOCK_UNAVAILABLE} are considered failures
     * for the purpose of exit code derivation (both map to exit code 1).
     * Use {@link #isLockUnavailable()} to distinguish the start-protection case.
     *
     * @return true if outcome is {@link #FAILURE} or {@link #LOCK_UNAVAILABLE}, false otherwise
     */
    public boolean isFailure() {
        return this == FAILURE || this == LOCK_UNAVAILABLE;
    }

    /**
     * Returns true if this outcome represents a controlled early termination due to
     * the run lock being held by another instance.
     *
     * @return true if outcome is {@link #LOCK_UNAVAILABLE}, false otherwise
     */
    public boolean isLockUnavailable() {
        return this == LOCK_UNAVAILABLE;
    }
}
