package de.gecheckt.pdf.umbenenner.application.port.out.history;

/**
 * Abfrageparameter für den Historien-Tab.
 * <p>
 * Kapselt Freitextsuche, optionalen Status-Filter und das Limit der zurückzugebenden
 * Zeilen. Das Limit ist bewusst auf 501 gesetzt, damit die aufrufende Schicht erkennen
 * kann, ob mehr als 500 Treffer vorhanden sind.
 *
 * @param searchText   optionaler Suchbegriff (Teilstring, case-insensitiv); {@code null}
 *                     oder leer bedeutet keine Texteinschränkung
 * @param statusFilter optionaler Status-Filter als Enum-Name; {@code null} bedeutet alle
 *                     Status werden angezeigt
 * @param limit        maximale Anzahl zurückzugebender Zeilen; muss &gt;= 1 sein
 */
public record HistoryQuery(
        String searchText,
        String statusFilter,
        int limit) {

    /**
     * Standard-Limit: 501 Zeilen abfragen, um bei Bedarf „mehr vorhanden" erkennen zu können.
     */
    public static final int DEFAULT_LIMIT = 501;

    /**
     * Kompakter Konstruktor mit Pflichtfeldprüfung.
     *
     * @throws IllegalArgumentException wenn {@code limit} kleiner als 1 ist
     */
    public HistoryQuery {
        if (limit < 1) {
            throw new IllegalArgumentException("limit muss mindestens 1 sein, war: " + limit);
        }
    }

    /**
     * Erzeugt eine Abfrage ohne Filter mit Standard-Limit.
     *
     * @return neue Abfrage ohne Einschränkungen
     */
    public static HistoryQuery unfiltered() {
        return new HistoryQuery(null, null, DEFAULT_LIMIT);
    }

    /**
     * Erzeugt eine Abfrage mit Freitextsuche und Standard-Limit.
     *
     * @param searchText Suchbegriff; {@code null} oder leer bedeutet kein Filter
     * @return neue Abfrage mit Textfilter
     */
    public static HistoryQuery withSearchText(String searchText) {
        return new HistoryQuery(searchText, null, DEFAULT_LIMIT);
    }

    /**
     * Erzeugt eine Abfrage mit Status-Filter und Standard-Limit.
     *
     * @param statusFilter Enum-Name des gewünschten Status; {@code null} bedeutet kein Filter
     * @return neue Abfrage mit Status-Filter
     */
    public static HistoryQuery withStatus(String statusFilter) {
        return new HistoryQuery(null, statusFilter, DEFAULT_LIMIT);
    }
}
