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

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

import de.gecheckt.pdf.umbenenner.application.port.in.HistoricalDocumentContext;
import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;

/**
 * GUI-interner Port zum Abfragen des historischen Verarbeitungskontexts einer Quelldatei.
 * <p>
 * Wird im Verarbeitungslauf-Tab genutzt, um für übersprungene Dokumente
 * ({@link de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus#SKIPPED_ALREADY_PROCESSED}
 * und
 * {@link de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus#SKIPPED_FINAL_FAILURE})
 * den historischen Kontext nachzuschlagen. Der Kontext wird im Detailbereich des
 * Verarbeitungslauf-Tabs angezeigt.
 * <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 werden intern
 * abgefangen 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 GuiHistoricalDocumentContextPort {

    /**
     * Gibt den historischen Verarbeitungskontext für das durch {@code fingerprint}
     * identifizierte Dokument zurück, oder ein leeres {@link Optional}, wenn kein
     * Kontext 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 historischer Kontext des Dokuments, oder leer wenn nicht verfügbar
     */
    Optional<HistoricalDocumentContext> resolveHistoricalDocumentContext(
            Path configFilePath, DocumentFingerprint fingerprint);
}
