package de.gecheckt.pdf.umbenenner.application.port.out;

/**
 * Outbound-Port für das Umbenennen einer bereits existierenden Datei im Zielordner.
 * <p>
 * Dieser Port kapselt die reine Dateisystem-Operation des Umbenennens. Er ist
 * provider-neutral und kennt ausschließlich opake Dateinamen-Strings – keine
 * {@code Path}-, {@code File}- oder NIO-Typen. Die Übersetzung in tatsächliche
 * Dateisystemoperationen obliegt ausschließlich der Adapter-Implementierung.
 * <p>
 * <strong>Zuständigkeit:</strong> Dieser Port ist nicht für die Suffix-Logik bei
 * Namenskollisionen zuständig. Die Auflösung eines eindeutigen Zieldateinamens
 * (inkl. Suffix-Vergabe) erfolgt über
 * {@link TargetFolderPort#resolveUniqueFilename(String, de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint)}.
 * <p>
 * <strong>Architekturgrenze:</strong> Keine {@code Path}-, {@code File}-, NIO- oder
 * JDBC-Typen erscheinen in diesem Interface oder in Typen, die es referenziert.
 */
public interface TargetFileRenamePort {

    /**
     * Benennt eine existierende Datei im Zielordner von {@code oldFileName} zu
     * {@code newFileName} um.
     * <p>
     * Die Methode erwartet, dass {@code oldFileName} im Zielordner vorhanden ist.
     * Ist {@code newFileName} bereits vorhanden und nicht identisch mit {@code oldFileName},
     * wird {@link TargetFileRenameFailureTargetExists} zurückgegeben. Die eigentliche
     * Konfliktvermeidung (Suffix-Vergabe) liegt im Verantwortungsbereich des Aufrufers.
     *
     * @param oldFileName der aktuell im Zielordner vorhandene Dateiname (ohne Pfad);
     *                    darf nicht null oder leer sein
     * @param newFileName der gewünschte neue Dateiname (ohne Pfad);
     *                    darf nicht null oder leer sein
     * @return {@link TargetFileRenameSuccess} bei Erfolg,
     *         {@link TargetFileRenameFailureFileNotFound} wenn {@code oldFileName} nicht existiert,
     *         {@link TargetFileRenameFailureTargetExists} wenn {@code newFileName} bereits durch
     *         eine andere Datei belegt ist,
     *         {@link TargetFileRenameTechnicalFailure} bei einem sonstigen technischen Fehler
     */
    TargetFileRenameResult rename(String oldFileName, String newFileName);
}
