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

import java.nio.file.Path;

import de.gecheckt.pdf.umbenenner.application.port.in.ManualFileRenameRequest;
import de.gecheckt.pdf.umbenenner.application.port.in.ManualFileRenameResult;

/**
 * Inbound-Brücke für die manuelle Dateiumbenennung aus der GUI.
 * <p>
 * Wird von Bootstrap per Methoden-Referenz befüllt und vom GUI-Code aufgerufen,
 * wenn der Benutzer einen geänderten Dateinamen bestätigt. Der Port kapselt
 * das vollständige Wiring (Konfigurationsauflösung, Use-Case-Konstruktion und
 * Ausführung), sodass der GUI-Adapter keine Kenntnis von infrastrukturellen
 * Implementierungsdetails benötigt.
 *
 * <h2>Threadingmodell</h2>
 * <p>
 * Der Port darf auf einem beliebigen Thread aufgerufen werden. Die Implementierung
 * ist synchron und blockierend: Sie kehrt erst zurück, wenn die Umbenennung
 * abgeschlossen oder fehlgeschlagen ist. Aufrufer aus dem GUI-Layer müssen den
 * Aufruf daher auf einem Hintergrund-Worker-Thread ausführen und das Ergebnis
 * anschließend per {@code Platform.runLater} auf den JavaFX-Application-Thread
 * zurückführen.
 *
 * <h2>Exception-Vertrag</h2>
 * <p>
 * Implementierungen dürfen keine geprüften Ausnahmen propagieren. Unerwartete
 * Laufzeitausnahmen sollen abgefangen und als passendes {@link ManualFileRenameResult}
 * zurückgegeben werden.
 */
@FunctionalInterface
public interface GuiManualFileRenamePort {

    /**
     * Benennt die Zieldatei eines erfolgreich verarbeiteten Dokuments manuell um.
     *
     * @param configFilePath Pfad zur {@code .properties}-Datei, die die SQLite-Datenbank
     *                       und den Zielordner beschreibt; darf nicht {@code null} sein;
     *                       muss existieren und lesbar sein
     * @param request        die Umbenennungsanfrage mit Fingerprint und gewünschtem
     *                       Basisdateinamen; darf nicht {@code null} sein
     * @return das Ergebnis der Umbenennung; nie {@code null}
     */
    ManualFileRenameResult rename(Path configFilePath, ManualFileRenameRequest request);
}
