package de.gecheckt.pdf.umbenenner.application.port.out.history;

import java.util.List;
import java.util.Optional;

import de.gecheckt.pdf.umbenenner.application.port.out.DocumentRecord;
import de.gecheckt.pdf.umbenenner.application.port.out.ProcessingAttempt;
import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;

/**
 * Outbound-Port für lesende Historien-Abfragen aus dem Historien-Tab.
 * <p>
 * Kapselt alle Datenbanklese-Operationen, die der Historien-Tab benötigt.
 * Die Implementierung liegt ausschließlich in {@code pdf-umbenenner-adapter-out}.
 * Die Application-Schicht kennt nur diesen Port-Vertrag – keine JDBC-Typen.
 *
 * <h2>Architektur</h2>
 * <p>
 * Dieser Port ist bewusst von {@link de.gecheckt.pdf.umbenenner.application.port.out.DocumentRecordRepository}
 * und {@link de.gecheckt.pdf.umbenenner.application.port.out.ProcessingAttemptRepository}
 * getrennt, damit die bestehenden Repositories nicht mit GUI-spezifischen Methoden
 * aufgebläht werden.
 */
public interface HistoryQueryPort {

    /**
     * Lädt eine gefilterte und sortierte Übersicht aller Dokumenteneinträge.
     * <p>
     * Sortierung: {@code updated_at DESC, fingerprint ASC} (stabiler Tie-Breaker).
     * Das in {@link HistoryQuery#limit()} angegebene Limit wird direkt als SQL-{@code LIMIT}
     * angewendet. Wenn das Limit 501 beträgt und 501 Zeilen zurückgegeben werden, gibt es
     * mehr als 500 Treffer.
     *
     * @param query Abfrageparameter mit Suchtext, Status-Filter und Limit; darf nicht {@code null} sein
     * @return unveränderliche Liste der Trefferzeilen; nie {@code null}; kann leer sein
     * @throws de.gecheckt.pdf.umbenenner.application.port.out.DocumentPersistenceException bei
     *         technischen Datenbankfehlern
     */
    List<DocumentHistoryRow> loadOverview(HistoryQuery query);

    /**
     * Lädt den vollständigen Dokumenten-Stammsatz für den angegebenen Fingerprint.
     *
     * @param fingerprint Dokumentbezeichner; darf nicht {@code null} sein
     * @return Optional mit dem Stammsatz, oder leer wenn nicht vorhanden
     * @throws de.gecheckt.pdf.umbenenner.application.port.out.DocumentPersistenceException bei
     *         technischen Datenbankfehlern
     */
    Optional<DocumentRecord> findRecordByFingerprint(DocumentFingerprint fingerprint);

    /**
     * Lädt alle historisierten Verarbeitungsversuche für den angegebenen Fingerprint,
     * aufsteigend sortiert nach {@code attempt_number}.
     *
     * @param fingerprint Dokumentbezeichner; darf nicht {@code null} sein
     * @return unveränderliche Liste der Versuche; nie {@code null}; kann leer sein
     * @throws de.gecheckt.pdf.umbenenner.application.port.out.DocumentPersistenceException bei
     *         technischen Datenbankfehlern
     */
    List<ProcessingAttempt> findAttemptsByFingerprint(DocumentFingerprint fingerprint);
}
