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

import java.util.Optional;

import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;

/**
 * Inbound port for resolving the historical target filename for a previously processed document.
 * <p>
 * Used to populate the "Neuer Dateiname" column in the GUI result table for documents that
 * were skipped in the current run because they were already in a terminal state from a
 * previous run. For documents that previously reached
 * {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#SUCCESS}, the last
 * successfully written target filename is returned. For all other terminal states
 * (e.g. {@code FAILED_FINAL}) that were never copied to the target folder, an empty
 * {@link Optional} is returned.
 * <p>
 * <strong>Architecture boundary:</strong> Implementations of this port must not expose
 * JDBC, SQLite, filesystem or HTTP types through this interface. All infrastructure details
 * remain in the adapter layer.
 */
public interface ResolveHistoricalFileNameUseCase {

    /**
     * Returns the last successfully written target filename for the document identified
     * by the given fingerprint, or an empty {@link Optional} if no such filename exists.
     * <p>
     * The method never throws: technical failures during the repository lookup are caught
     * and result in an empty return value.
     *
     * @param fingerprint content-based document identity; must not be {@code null}
     * @return the last target filename written for this document, or empty if the document
     *         never reached a successful terminal state or the lookup failed
     * @throws NullPointerException if {@code fingerprint} is {@code null}
     */
    Optional<String> resolveHistoricalFileName(DocumentFingerprint fingerprint);
}
