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

import java.util.Objects;

/**
 * Represents a discovered PDF candidate from the source folder.
 * <p>
 * This record encapsulates the minimal, infrastructure-agnostic metadata
 * needed to identify, correlate, and later extract a document during processing.
 * <p>
 * It deliberately does NOT expose filesystem paths or file handles directly.
 * The hexagonal boundary is maintained: adapters map filesystem objects to this
 * representation. The physical document location is carried opaquely via
 * {@link SourceDocumentLocator}, which only adapters interpret.
 * <p>
 * Fields:
 * <ul>
 *   <li>{@code uniqueIdentifier} — human-readable name for logging and correlation (e.g. filename)</li>
 *   <li>{@code fileSizeBytes} — file size for metadata and tracing; may be zero for empty files (content evaluation happens during processing)</li>
 *   <li>{@code locator} — opaque reference passed through unchanged to the extraction adapter;
 *       Domain and Application never interpret its value</li>
 * </ul>
 * <p>
 * No java.io.File or java.nio.file.Path references appear in this record.
 *
 */
public record SourceDocumentCandidate(
    String uniqueIdentifier,
    long fileSizeBytes,
    SourceDocumentLocator locator
) {
    /**
     * Compact constructor with validation.
     * <p>
     * Ensures all parameters are non-null and meaningful:
     * <ul>
     *   <li>{@code uniqueIdentifier} must be non-null and non-empty</li>
     *   <li>{@code fileSizeBytes} must be non-negative (may be zero for empty files; content evaluation happens during processing)</li>
     *   <li>{@code locator} must be non-null</li>
     * </ul>
     *
     * @param uniqueIdentifier non-null, non-empty identifier for logging and correlation
     * @param fileSizeBytes must be &gt;= 0 (may be 0; content evaluation happens during processing)
     * @param locator non-null opaque locator; only adapters interpret its value
     * @throws NullPointerException if uniqueIdentifier or locator is null
     * @throws IllegalArgumentException if uniqueIdentifier is empty or fileSizeBytes &lt; 0
     */
    public SourceDocumentCandidate {
        Objects.requireNonNull(uniqueIdentifier, "uniqueIdentifier must not be null");
        if (uniqueIdentifier.isEmpty()) {
            throw new IllegalArgumentException("uniqueIdentifier must not be empty");
        }
        if (fileSizeBytes < 0) {
            throw new IllegalArgumentException("fileSizeBytes must not be negative");
        }
        Objects.requireNonNull(locator, "locator must not be null");
    }
}
