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

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

/**
 * Inbound port for batch processing execution.
 * <p>
 * This interface defines the contract for triggering batch operations.
 * It is the central use case entry point for the entire application.
 * <p>
 * Responsibilities:
 * <ul>
 *   <li>Orchestrate the batch run lifecycle (start, process, end)</li>
 *   <li>Interact with all outbound ports (lock, clock, configuration, persistence, etc.)</li>
 *   <li>Return a structured outcome ({@link BatchRunOutcome}) that describes the run result</li>
 * </ul>
 * <p>
 * The returned outcome is designed to be independent of individual document results,
 * representing only the batch operation itself. Individual document successes/failures
 * are tracked separately in persistence.
 * <p>
 * Implementation details:
 * <ul>
 *   <li>Port is defined with a structured return contract ({@link BatchRunOutcome})</li>
 *   <li>Return model allows Bootstrap/CLI to systematically derive exit codes</li>
 *   <li>execute() accepts a {@link BatchRunContext} containing the run ID and timing</li>
 *   <li>The context flows through the entire batch cycle for correlation and logging</li>
 * </ul>
 */
public interface BatchRunProcessingUseCase {

    /**
     * Executes the batch processing workflow.
     * <p>
     * The method orchestrates the entire batch cycle, from startup through completion.
     * It interacts with all necessary outbound ports and returns a structured outcome.
     * <p>
     * The outcome is not dependent on how many documents succeeded or failed within the run;
     * rather, it reflects the batch operation's overall health. Individual document results
     * are recorded separately in persistence.
     *
     * @param context the technical context for this batch run, containing run ID and timing
     * @return {@link BatchRunOutcome} indicating success or failure of the batch operation
     */
    BatchRunOutcome execute(BatchRunContext context);
}