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

import java.nio.file.Path;

import de.gecheckt.pdf.umbenenner.application.port.out.history.HistoryQuery;
import de.gecheckt.pdf.umbenenner.application.usecase.DefaultHistoryOverviewUseCase.HistoryOverviewResult;

/**
 * GUI-internes Bridge-Interface zwischen dem Historien-Tab und dem
 * {@link de.gecheckt.pdf.umbenenner.application.usecase.DefaultHistoryOverviewUseCase}.
 * <p>
 * Dieses Interface ist <em>kein</em> hexagonaler Outbound-Port der Application-Schicht.
 * Es ist eine modul-interne Brücke, über die Bootstrap die Dokumentenliste
 * für den Historien-Tab bereitstellt, ohne dass der GUI-Adapter direkt auf
 * Repository-Implementierungen zugreift.
 * <p>
 * Der Parameter {@code configFilePath} wird benötigt, damit die Bootstrap-Implementierung
 * die SQLite-Datenbank aus der aktuell geladenen Konfigurationsdatei ableiten kann,
 * ohne den Pfad global zu speichern.
 * <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 GuiHistoryOverviewPort {

    /**
     * Lädt die gefilterte Dokumentenübersicht für den Historien-Tab.
     * <p>
     * Bei mehr als 500 Treffern enthält das Ergebnis genau 500 Zeilen und
     * {@link HistoryOverviewResult#hasMore()} liefert {@code true}.
     *
     * @param configFilePath Pfad zur aktuell geladenen {@code .properties}-Datei;
     *                       darf nicht {@code null} sein
     * @param query          Abfrageparameter mit Suchtext, Status-Filter und Limit;
     *                       darf nicht {@code null} sein
     * @return Ergebnisobjekt mit Trefferliste und {@code hasMore}-Flag; nie {@code null}
     * @throws de.gecheckt.pdf.umbenenner.application.port.out.DocumentPersistenceException
     *         bei technischen Datenbankfehlern
     */
    HistoryOverviewResult loadOverview(Path configFilePath, HistoryQuery query);
}
