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

import java.nio.file.Path;

import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;

/**
 * GUI-internes Bridge-Interface zwischen dem Historien-Tab und dem
 * {@link de.gecheckt.pdf.umbenenner.application.usecase.DefaultHistoryResetDocumentStatusUseCase}.
 * <p>
 * Führt einen feldgenauen Status-Reset durch: ausschließlich {@code overall_status},
 * {@code content_error_count}, {@code transient_error_count} und
 * {@code last_failure_instant} werden zurückgesetzt. Die Versuchshistorie bleibt
 * vollständig erhalten. Nach dem Reset gilt das Dokument beim nächsten
 * Verarbeitungslauf als verarbeitbar.
 * <p>
 * <strong>Abgrenzung zu {@link de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiResetDocumentStatusPort}:</strong>
 * Der bestehende Reset-Port im {@code batchrun}-Paket löscht alle Persistenzdaten
 * (Stammsatz und Versuchshistorie) vollständig. Dieser Port hier führt ausschließlich
 * einen feldgenauen Update durch und lässt die Versuchshistorie unangetastet.
 * <p>
 * <strong>Threading:</strong> Implementierungen müssen sicher von einem
 * Hintergrund-Worker-Thread aufgerufen werden können. Der Aufruf blockiert,
 * bis die Operation abgeschlossen ist.
 */
@FunctionalInterface
public interface GuiHistoryResetDocumentStatusPort {

    /**
     * Setzt den Status des Dokuments feldgenau zurück.
     * <p>
     * Folgende Felder werden aktualisiert:
     * <ul>
     *   <li>{@code overall_status} → {@code READY_FOR_AI}</li>
     *   <li>{@code content_error_count} → {@code 0}</li>
     *   <li>{@code transient_error_count} → {@code 0}</li>
     *   <li>{@code last_failure_instant} → {@code null}</li>
     * </ul>
     *
     * @param configFilePath Pfad zur aktuell geladenen {@code .properties}-Datei;
     *                       darf nicht {@code null} sein
     * @param fingerprint    der Dokumentbezeichner; darf nicht {@code null} sein
     * @throws de.gecheckt.pdf.umbenenner.application.port.out.DocumentPersistenceException
     *         bei technischen Datenbankfehlern
     */
    void resetStatus(Path configFilePath, DocumentFingerprint fingerprint);
}
