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

import java.nio.file.Path;

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.DefaultDeleteDocumentHistoryUseCase}.
 * <p>
 * Löscht den Dokument-Stammsatz und alle zugehörigen Verarbeitungsversuche
 * vollständig und transaktional. Die Löschung ist destruktiv und nicht
 * rückgängig zu machen.
 * <p>
 * Die GUI muss vor dem Aufruf dieses Ports einen Bestätigungsdialog mit
 * explizitem Warnhinweis anzeigen.
 * <p>
 * <strong>Threading:</strong> Implementierungen müssen sicher von einem
 * Hintergrund-Worker-Thread aufgerufen werden können. Der Aufruf blockiert,
 * bis die Löschung abgeschlossen ist.
 */
@FunctionalInterface
public interface GuiDeleteDocumentHistoryPort {

    /**
     * Löscht den Stammsatz und alle Verarbeitungsversuche für den angegebenen Fingerprint.
     * <p>
     * Die Löschung erfolgt in der korrekten Reihenfolge innerhalb einer Transaktion:
     * zuerst alle {@code processing_attempt}-Einträge, dann der {@code document_record}-Stammsatz.
     * Ist kein Datensatz vorhanden, kehrt die Methode stillschweigend zurück.
     *
     * @param configFilePath Pfad zur aktuell geladenen {@code .properties}-Datei;
     *                       darf nicht {@code null} sein
     * @param fingerprint    der Dokumentbezeichner; darf nicht {@code null} sein
     * @throws de.gecheckt.pdf.umbenenner.application.port.out.DocumentPersistenceException
     *         bei technischen Datenbankfehlern
     */
    void deleteHistory(Path configFilePath, DocumentFingerprint fingerprint);
}
