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

import java.util.Set;

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

/**
 * Inbound port for resetting the processing status of one or more documents.
 * <p>
 * A reset removes all persistence data (attempt history and document master record)
 * for the specified fingerprints, making those documents eligible for reprocessing in
 * the next regular or targeted batch run as if they had never been processed.
 * <p>
 * The operation follows a best-effort semantics: each fingerprint is processed
 * independently. A technical failure for one fingerprint does not prevent the reset
 * from being attempted for the remaining fingerprints. The result carries the full
 * accounting of successes and failures.
 */
public interface ResetDocumentStatusUseCase {

    /**
     * Resets the processing status for the supplied set of document fingerprints.
     * <p>
     * For each fingerprint the implementation deletes the document master record and
     * all associated attempt history within a single atomic transaction. If the
     * transaction fails for a given fingerprint, that fingerprint's error is recorded
     * in the result's {@link ResetDocumentStatusResult#failures() failures} map and
     * processing continues with the remaining fingerprints.
     *
     * @param fingerprints the set of document fingerprints to reset; must not be null;
     *                     may be empty (results in a completed result with zero requests)
     * @return a {@link ResetDocumentStatusResult} describing the outcome; never null
     */
    ResetDocumentStatusResult reset(Set<DocumentFingerprint> fingerprints);
}
