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

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

import de.gecheckt.pdf.umbenenner.application.usecase.DefaultHistoryDetailsUseCase.HistoryDetailsResult;
import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;

/**
 * GUI-internes Bridge-Interface zwischen dem Historien-Tab und dem
 * {@link de.gecheckt.pdf.umbenenner.application.usecase.DefaultHistoryDetailsUseCase}.
 * <p>
 * Dieses Interface ist <em>kein</em> hexagonaler Outbound-Port der Application-Schicht.
 * Es ist eine modul-interne Brücke, über die Bootstrap die Detaildaten
 * für einen ausgewählten Dokumenteintrag bereitstellt.
 * <p>
 * Der Parameter {@code configFilePath} wird benötigt, damit die Bootstrap-Implementierung
 * die SQLite-Datenbank aus der aktuell geladenen Konfigurationsdatei ableiten kann.
 * <p>
 * <strong>Threading:</strong> Implementierungen müssen sicher von einem
 * Hintergrund-Worker-Thread aufgerufen werden können. Der Aufruf blockiert,
 * bis das Ergebnis vollständig vorliegt.
 */
@FunctionalInterface
public interface GuiHistoryDetailsPort {

    /**
     * Lädt den Stammsatz und alle Verarbeitungsversuche für den angegebenen Fingerprint.
     *
     * @param configFilePath Pfad zur aktuell geladenen {@code .properties}-Datei;
     *                       darf nicht {@code null} sein
     * @param fingerprint    Dokumentbezeichner; darf nicht {@code null} sein
     * @return Optional mit den Detaildaten, oder leer wenn kein Eintrag gefunden wurde
     * @throws de.gecheckt.pdf.umbenenner.application.port.out.DocumentPersistenceException
     *         bei technischen Datenbankfehlern
     */
    Optional<HistoryDetailsResult> loadDetails(Path configFilePath, DocumentFingerprint fingerprint);
}
