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

import de.gecheckt.pdf.umbenenner.application.port.out.PromptLoadingResult;
import de.gecheckt.pdf.umbenenner.application.port.out.PromptSaveResult;
import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionOutcome;
import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionSuggestion;

/**
 * GUI-internes Bridge-Interface zwischen dem Prompt-Editor-Tab und dem zugehörigen
 * Use-Case in der Application-Schicht.
 * <p>
 * Dieses Interface ist <em>kein</em> hexagonaler Outbound-Port der Application-Schicht.
 * Es ist eine modul-interne Brücke, über die Bootstrap die vom Use-Case bereitgestellte
 * Funktionalität in den GUI-Adapter einschleust, ohne dass der GUI-Adapter direkt auf
 * {@link de.gecheckt.pdf.umbenenner.application.port.out.PromptPort} oder das Dateisystem
 * zugreift.
 * <p>
 * <strong>Verantwortung:</strong>
 * <ul>
 *   <li>Prompt-Inhalt für die Anzeige im Editor laden.</li>
 *   <li>Bearbeiteten Inhalt atomar speichern.</li>
 *   <li>Standard-Prompt-Datei anlegen, wenn noch keine vorhanden ist.</li>
 * </ul>
 * <p>
 * Alle Implementierungen dieses Interfaces liegen in {@code pdf-umbenenner-bootstrap}.
 * Das GUI-Modul kennt ausschließlich den Interface-Typ.
 */
public interface GuiPromptEditorPort {

    /**
     * Lädt den aktuellen Prompt-Inhalt aus der konfigurierten Quelle.
     * <p>
     * Muss auf einem Worker-Thread aufgerufen werden; das Ergebnis wird via
     * {@code Platform.runLater} in den JavaFX Application Thread übergeben.
     *
     * @return {@link PromptLoadingResult} mit Inhalt und Identifikator bei Erfolg,
     *         oder einem klassifizierten Fehler; nie {@code null}
     */
    PromptLoadingResult loadCurrentPrompt();

    /**
     * Speichert den übergebenen Inhalt atomar in die konfigurierte Prompt-Datei.
     * <p>
     * Muss auf einem Worker-Thread aufgerufen werden; das Ergebnis wird via
     * {@code Platform.runLater} in den JavaFX Application Thread übergeben.
     *
     * @param content der zu speichernde Inhalt; darf nicht {@code null} sein
     * @return {@link PromptSaveResult} mit Erfolg oder klassifiziertem Fehler; nie {@code null}
     * @throws NullPointerException wenn {@code content} null ist
     */
    PromptSaveResult save(String content);

    /**
     * Legt eine Standard-Prompt-Datei an, falls noch keine vorhanden ist.
     * <p>
     * Muss auf einem Worker-Thread aufgerufen werden; das Ergebnis wird via
     * {@code Platform.runLater} in den JavaFX Application Thread übergeben.
     *
     * @param suggestion Korrekturvorschlag mit dem Zielpfad; darf nicht {@code null} sein
     * @return {@link CorrectionOutcome} mit dem Ergebnis der Aktion; nie {@code null}
     * @throws NullPointerException wenn {@code suggestion} null ist
     */
    CorrectionOutcome createDefaultPromptIfMissing(CorrectionSuggestion.CreatePromptFile suggestion);
}
