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

import java.nio.file.Path;

import de.gecheckt.pdf.umbenenner.application.port.in.ManualFileCopyRequest;
import de.gecheckt.pdf.umbenenner.application.port.in.ManualFileCopyResult;

/**
 * Inbound-Brücke für die manuelle Kopie der Quelldatei eines bislang nicht erfolgreich
 * verarbeiteten Dokuments aus der GUI.
 * <p>
 * Wird von Bootstrap per Methoden-Referenz befüllt und vom GUI-Code aufgerufen, wenn der
 * Benutzer für ein nicht erfolgreich verarbeitetes Dokument (Status {@code FAILED_*} oder
 * {@code SKIPPED_FINAL_FAILURE}) einen manuellen Zieldateinamen 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 Kopie 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 ManualFileCopyResult}
 * zurückgegeben werden.
 */
@FunctionalInterface
public interface GuiManualFileCopyPort {

    /**
     * Kopiert die Quelldatei eines Dokuments mit benutzerdefiniertem Zieldateinamen ins
     * Zielverzeichnis und aktualisiert den Dokument-Stammsatz auf {@code SUCCESS}.
     *
     * @param configFilePath Pfad zur {@code .properties}-Datei, die SQLite-Datenbank,
     *                       Quell- und Zielordner beschreibt; darf nicht {@code null} sein;
     *                       muss existieren und lesbar sein
     * @param request        die Kopieranfrage mit Fingerprint und gewünschtem
     *                       Basisdateinamen; darf nicht {@code null} sein
     * @return das Ergebnis der Kopieroperation; nie {@code null}
     */
    ManualFileCopyResult copy(Path configFilePath, ManualFileCopyRequest request);
}
