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

/**
 * Aggregierte Zähler über alle abgeschlossenen Ticks der laufenden bzw. zuletzt
 * gelaufenen Scheduler-Sitzung.
 * <p>
 * Eine Sitzung beginnt mit dem nächsten erfolgreichen
 * {@link SchedulerControlUseCase#start()} und endet mit dem zugehörigen
 * {@link SchedulerControlUseCase#stop()}. Beim Start einer neuen Sitzung
 * werden die Zähler auf null zurückgesetzt; nach dem Stopp bleiben sie
 * eingefroren sichtbar, bis der Scheduler erneut gestartet wird.
 * <p>
 * Übersprungene Dokumente werden in dieser Sitzungsstatistik bewusst nicht
 * gezählt, da sie für den Bediener keine neue Verarbeitungsleistung darstellen.
 *
 * @param successCount Summe aller erfolgreich verarbeiteten Dokumente seit
 *                     Sitzungsstart; nie negativ
 * @param failedCount  Summe aller fehlgeschlagenen Dokumente seit Sitzungsstart
 *                     (retryable und final zusammengefasst); nie negativ
 */
public record SchedulerSessionTotals(int successCount, int failedCount) {

    /**
     * Validiert, dass beide Zähler nicht negativ sind.
     *
     * @throws IllegalArgumentException wenn einer der Zähler kleiner als null ist
     */
    public SchedulerSessionTotals {
        if (successCount < 0 || failedCount < 0) {
            throw new IllegalArgumentException(
                    "SchedulerSessionTotals counts must not be negative; was: "
                            + successCount + "/" + failedCount);
        }
    }

    /**
     * Liefert ein neutrales Ausgangsobjekt mit beiden Zählern auf null.
     *
     * @return Sitzungstotal mit allen Zählern auf null; nie {@code null}
     */
    public static SchedulerSessionTotals zero() {
        return new SchedulerSessionTotals(0, 0);
    }

    /**
     * Liefert ein neues Sitzungstotal, in dem die übergebenen Werte additiv
     * aufgenommen wurden. Das aktuelle Objekt bleibt unverändert.
     *
     * @param additionalSuccess hinzuzurechnende Erfolgreich-Zahl; muss &ge; 0 sein
     * @param additionalFailed  hinzuzurechnende Fehler-Zahl; muss &ge; 0 sein
     * @return aufaddiertes Sitzungstotal; nie {@code null}
     */
    public SchedulerSessionTotals plus(int additionalSuccess, int additionalFailed) {
        return new SchedulerSessionTotals(
                successCount + additionalSuccess,
                failedCount + additionalFailed);
    }
}
