package de.gecheckt.pdf.umbenenner.application.validation.technicaltest;

/**
 * Outbound-Port für schreibende technische Korrekturhilfen.
 * <p>
 * Dieser Port ist <strong>schreibend</strong> und darf nur nach ausdrücklicher
 * Benutzerbestätigung eines {@link CorrectionPlan} aufgerufen werden. Es darf keine
 * stille Ausführung im Hintergrund geben.
 * <p>
 * <strong>Abgrenzung zu {@link PathCheckPort}:</strong> {@code PathCheckPort} ist
 * rein lesend; {@code ResourceCreationPort} ist rein schreibend. Beide Ports werden
 * niemals für dieselbe Aufgabe verwendet.
 * <p>
 * <strong>Pfad-Konvention:</strong> Alle Pfade werden als {@code String} übergeben,
 * analog zur Konvention der übrigen Outbound-Ports dieses Projekts. Der Adapter-Out
 * ist für die Konvertierung in plattformspezifische Pfadobjekte zuständig.
 * <p>
 * <strong>Fehlerbehandlung:</strong> Implementierungen werfen keine geprüften Ausnahmen.
 * Jede Methode gibt ein {@link CorrectionOutcome} zurück, das Erfolg, Scheitern oder
 * Nicht-Durchführbarkeit ausdrückt. Unerwartete technische Fehler werden als
 * {@link CorrectionOutcome.Failed} zurückgegeben.
 * <p>
 * <strong>Windows- und Netzlaufwerke:</strong> Implementierungen müssen gemappte
 * Laufwerksbuchstaben wie {@code S:\} oder {@code H:\} im Windows-Kontext unterstützen.
 */
public interface ResourceCreationPort {

    /**
     * Legt den angegebenen Ordner an, einschließlich aller fehlenden übergeordneten Ordner.
     * <p>
     * Falls der Ordner bereits existiert, wird {@link CorrectionOutcome.Applied} mit einem
     * entsprechenden Hinweis zurückgegeben (idempotente Ausführung).
     *
     * @param suggestion  der {@link CorrectionSuggestion.CreateDirectory}-Vorschlag; darf nicht {@code null} sein
     * @return Ergebnis der Ausführung; nie {@code null}
     */
    CorrectionOutcome createDirectory(CorrectionSuggestion.CreateDirectory suggestion);

    /**
     * Erzeugt eine neue Prompt-Datei mit einem deutschen Standardinhalt.
     * <p>
     * Der Standardinhalt wird von dieser Implementierung bereitgestellt. Die Datei wird
     * nur erzeugt, wenn sie noch nicht existiert und ihr übergeordneter Ordner beschreibbar ist.
     * Wenn der Pfad bereits eine Datei enthält, wird {@link CorrectionOutcome.NotAttempted}
     * zurückgegeben (kein stilless Überschreiben).
     *
     * @param suggestion  der {@link CorrectionSuggestion.CreatePromptFile}-Vorschlag; darf nicht {@code null} sein
     * @return Ergebnis der Ausführung; nie {@code null}
     */
    CorrectionOutcome createPromptFile(CorrectionSuggestion.CreatePromptFile suggestion);

    /**
     * Bereitet den übergeordneten Ordner einer SQLite-Datei vor, sofern dieser noch nicht
     * existiert.
     * <p>
     * Eine leere SQLite-Datei wird nicht manuell erzeugt; das übernimmt der JDBC-Layer
     * beim ersten Datenbankzugriff. Diese Methode stellt lediglich sicher, dass der
     * übergeordnete Ordner vorhanden und schreibbar ist.
     *
     * @param suggestion  der {@link CorrectionSuggestion.PrepareSqlitePath}-Vorschlag; darf nicht {@code null} sein
     * @return Ergebnis der Ausführung; nie {@code null}
     */
    CorrectionOutcome prepareSqlitePath(CorrectionSuggestion.PrepareSqlitePath suggestion);
}
