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

/**
 * Inbound-Port für die manuelle Umbenennung einer bereits erfolgreich verarbeiteten
 * Zieldatei.
 * <p>
 * Ermöglicht dem Benutzer, den von der KI vorgeschlagenen Dateinamen nachträglich
 * zu korrigieren. Der Use-Case führt die Umbenennung als atomare Operation durch:
 * Dateisystem und Persistenz werden entweder beide aktualisiert oder beide bleiben
 * im vorherigen Zustand.
 * <p>
 * Eine Umbenennung ist nur für Dokumente mit Status
 * {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#SUCCESS} zulässig,
 * die einen bekannten letzten Zieldateinamen haben.
 * <p>
 * <strong>Konfliktsemantik:</strong> Existiert im Zielordner bereits eine Datei mit dem
 * gewünschten Namen, wird anhand des Inhalts-Fingerprints entschieden:
 * <ul>
 *   <li>Gleicher Fingerprint → keine Aktion ({@link ManualFileRenameNoOpIdenticalTarget})</li>
 *   <li>Verschiedener Fingerprint → automatische Suffix-Vergabe ({@code (1)}, {@code (2)}, …)</li>
 * </ul>
 */
public interface ManualFileRenameUseCase {

    /**
     * Benennt die Zieldatei eines erfolgreich verarbeiteten Dokuments manuell um.
     * <p>
     * Der Aufruf ist atomar: Entweder werden Dateisystem und Persistenz beide
     * aktualisiert, oder beide bleiben unverändert. Bei einem Persistenzfehler
     * nach erfolgreicher Dateisystem-Umbenennung wird die Umbenennung im Dateisystem
     * im Rahmen eines Best-Effort-Rollbacks rückgängig gemacht.
     *
     * @param request die Umbenennungsanfrage mit Fingerprint und gewünschtem Basisdateinamen;
     *                darf nicht null sein
     * @return das Ergebnis der Umbenennung; nie null
     * @throws NullPointerException wenn {@code request} null ist
     */
    ManualFileRenameResult rename(ManualFileRenameRequest request);
}
