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

import java.nio.file.Path;
import java.util.Set;

import de.gecheckt.pdf.umbenenner.application.port.in.ResetDocumentStatusResult;
import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;

/**
 * Inbound bridge implemented by Bootstrap to let the GUI reset the processing status
 * of one or more documents without triggering an immediate reprocessing run.
 * <p>
 * A reset deletes all persistence data (attempt history and document master record)
 * for the specified fingerprints, making them eligible for reprocessing in the next
 * regular or targeted batch run as if they had never been processed.
 * <p>
 * The operation follows best-effort semantics: each fingerprint is attempted
 * independently. Technical failures for individual fingerprints are recorded in the
 * result and do not abort the remaining resets.
 *
 * <h2>Threading</h2>
 * <p>
 * Implementations must be safe to call from a non-UI worker thread. The call blocks
 * until all reset operations have completed or failed.
 *
 * <h2>Exception contract</h2>
 * <p>
 * Implementations must not propagate checked exceptions. Unexpected runtime exceptions
 * should be caught and represented as failures in the result map.
 */
@FunctionalInterface
public interface GuiResetDocumentStatusPort {

    /**
     * Resets the processing status for the supplied set of document fingerprints.
     *
     * @param configFilePath path of the {@code .properties} file that identifies the
     *                       SQLite database to operate on; must not be {@code null};
     *                       must exist and be readable
     * @param fingerprints   the set of document fingerprints to reset; must not be
     *                       {@code null}; may be empty
     * @return a {@link ResetDocumentStatusResult} describing the full outcome; never null
     */
    ResetDocumentStatusResult reset(Path configFilePath, Set<DocumentFingerprint> fingerprints);
}
