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

import java.util.Optional;

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

/**
 * Inbound-Port zum Abfragen des historischen Verarbeitungskontexts eines Dokuments.
 * <p>
 * Wird im GUI-Verarbeitungslauf-Tab eingesetzt, um für übersprungene Dokumente
 * anzuzeigen, wann und mit welchem Ergebnis die Datei in einem früheren Lauf
 * verarbeitet wurde.
 * <p>
 * Für Dokumente mit früherem Erfolgsstatus enthält der zurückgegebene Kontext den
 * letzten Zieldateinamen und den Erfolgszeitpunkt. Für endgültig fehlgeschlagene
 * Dokumente ist der letzte Fehlzeitpunkt belegt.
 * <p>
 * <strong>Architekturgrenzen:</strong> Implementierungen dieses Ports dürfen keine
 * JDBC-, SQLite-, Dateisystem- oder HTTP-Typen nach außen exponieren. Alle
 * Infrastrukturdetails verbleiben in der Adapter-Schicht.
 */
public interface ResolveHistoricalDocumentContextUseCase {

    /**
     * Gibt den historischen Verarbeitungskontext für das durch den Fingerprint
     * identifizierte Dokument zurück.
     * <p>
     * Liefert einen gefüllten Kontext, wenn das Dokument einen früheren terminalen
     * Abschluss (Erfolg oder endgültiger Fehlschlag) hat. Gibt ein leeres
     * {@link Optional} zurück, wenn kein passender Stammsatz vorhanden ist oder
     * die Abfrage technisch fehlschlägt.
     * <p>
     * Wirft keine geprüften Ausnahmen: technische Abfragefehler werden intern
     * abgefangen und als leeres Ergebnis zurückgegeben.
     *
     * @param fingerprint inhaltsbasierte Dokumentenidentität; darf nicht {@code null} sein
     * @return historischer Kontext des Dokuments, oder leer wenn nicht verfügbar
     * @throws NullPointerException wenn {@code fingerprint} {@code null} ist
     */
    Optional<HistoricalDocumentContext> resolveHistoricalDocumentContext(
            DocumentFingerprint fingerprint);
}
