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

import java.util.Objects;

/**
 * Represents failure to parse an AI response or extract required fields.
 * <p>
 * The response body was received, but either:
 * <ul>
 *   <li>The JSON could not be parsed (malformed JSON, invalid structure)</li>
 *   <li>Required fields (title, reasoning) are missing or not present as expected</li>
 * </ul>
 * <p>
 * This is a technical parsing error, distinct from semantic validation failures.
 * A response with valid JSON but semantically invalid field values (e.g., overly long title)
 * is NOT a parsing failure; it is a parsing success with a functional validation error.
 * <p>
 * <strong>Field semantics:</strong>
 * <ul>
 *   <li>{@link #failureReason()} — a classification of the parsing failure
 *       (e.g., "INVALID_JSON", "MISSING_TITLE", "MISSING_REASONING")</li>
 *   <li>{@link #failureMessage()} — a human-readable description, suitable for
 *       logging and debugging</li>
 * </ul>
 * <p>
 * <strong>Retry semantics:</strong> Parsing failures are technical and retryable.
 * The document should be retried in a later batch run up to the configured maximum
 * for transient errors.
 *
 * @param failureReason  classification of the parsing failure (non-null, may be empty)
 * @param failureMessage human-readable error description (non-null, may be empty)
 */
public record AiResponseParsingFailure(
        String failureReason,
        String failureMessage) implements AiResponseParsingResult {

    /**
     * Compact constructor validating mandatory fields.
     *
     * @throws NullPointerException if any field is null
     */
    public AiResponseParsingFailure {
        Objects.requireNonNull(failureReason, "failureReason must not be null");
        Objects.requireNonNull(failureMessage, "failureMessage must not be null");
    }
}
