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

import java.util.Objects;

/**
 * Represents a document that failed a pre-check.
 * <p>
 * This result encapsulates:
 * <ul>
 *   <li>The original document candidate metadata (for correlation)</li>
 *   <li>A reason why the pre-check failed</li>
 * </ul>
 * Reasons include:
 * <ul>
 *   <li>{@link PreCheckFailureReason#NO_USABLE_TEXT} – The extracted text contains no meaningful content after normalization.</li>
 *   <li>{@link PreCheckFailureReason#PAGE_LIMIT_EXCEEDED} – The document's page count exceeds the configured limit.</li>
 *   <li>{@link PreCheckFailureReason#CONTENT_NOT_EXTRACTABLE} – The PDF content cannot be extracted due to structural issues.</li>
 * </ul>
 * A document with this decision will not proceed further in the current batch run.
 *
 * @param candidate the source document metadata
 * @param failureReason the reason for the pre-check failure, must be non-null
 */
public record PreCheckFailed(
    SourceDocumentCandidate candidate,
    PreCheckFailureReason failureReason
) implements ProcessingDecision, DocumentProcessingOutcome {
    /**
     * Constructor with validation.
     *
     * @param candidate must be non-null
     * @param failureReason must be non-null
     * @throws NullPointerException if either parameter is null
     */
    public PreCheckFailed {
        Objects.requireNonNull(candidate, "candidate must not be null");
        Objects.requireNonNull(failureReason, "failureReason must not be null");
    }
    
    /**
     * Returns a human-readable description of the failure reason.
     * 
     * @return the description of the failure reason
     */
    public String failureReasonDescription() {
        return failureReason.getDescription();
    }
}