package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;

import java.nio.file.Path;
import java.util.Optional;

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

/**
 * GUI-interner Port zum Abfragen des historischen KI-Dateinamens einer Quelldatei.
 * <p>
 * Wird im Verarbeitungslauf-Tab genutzt, um für übersprungene Dokumente
 * ({@link de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus#SKIPPED})
 * den aus einem früheren Lauf bekannten Zieldateinamen nachzuschlagen und in der Spalte
 * „Neuer Dateiname" der Ergebnistabelle anzuzeigen.
 * <p>
 * Die Bootstrap-Schicht liefert die konkrete Implementierung. Sie lädt die Konfiguration
 * aus {@code configFilePath}, baut den zugehörigen Use-Case auf und gibt das Ergebnis
 * zurück. Technische Fehler beim Laden oder Abfragen dürfen nicht als Exception propagiert
 * werden; sie werden intern behandelt und als leeres {@link Optional} zurückgegeben.
 * <p>
 * Die Implementierung läuft auf dem Worker-Thread des {@link GuiBatchRunCoordinator}
 * und darf blockieren.
 */
@FunctionalInterface
public interface GuiHistoricalFileNamePort {

    /**
     * Gibt den letzten erfolgreich geschriebenen Zieldateinamen für das durch
     * {@code fingerprint} identifizierte Dokument zurück, oder ein leeres
     * {@link Optional}, wenn kein solcher Name verfügbar ist.
     *
     * @param configFilePath Pfad zur aktiven {@code .properties}-Konfigurationsdatei;
     *                       darf nicht {@code null} sein
     * @param fingerprint    inhaltsbasierte Dokumentenidentität; darf nicht {@code null} sein
     * @return der historische Zieldateiname, oder leer wenn nicht vorhanden
     */
    Optional<String> resolveHistoricalFileName(Path configFilePath, DocumentFingerprint fingerprint);
}
