package de.gecheckt.pdf.umbenenner.application.cost;

import java.math.BigDecimal;

/**
 * Interpretiertes Kosten-Ergebnis zu einer Tabellenzeile, einer Kopfzeile oder
 * einem einzelnen Versuch.
 *
 * <p>Der {@code CostCalculator} fuellt diese Struktur. Die GUI nutzt die
 * Boolean-Flags fuer das Anzeige-Mapping (Tabellenwert, Tooltip,
 * Banner-Beitrag) und formatiert {@link #amountUsd()} schließlich auf vier
 * Nachkommastellen.
 *
 * <p>Flag-Semantik:
 * <ul>
 *   <li>{@link #exact()} – alle Token-Werte und alle Preise vorhanden,
 *       Cache-Tokens spielten keine Rolle.</li>
 *   <li>{@link #partialTokens()} – mindestens ein Token-Wert fehlte
 *       (z.B. Input-Tokens null, Output-Tokens vorhanden); berechneter
 *       Wert ist eine Untergrenze.</li>
 *   <li>{@link #missingPriceSnapshot()} – mindestens ein Versuch ohne
 *       Preis-Snapshot floss ein.</li>
 *   <li>{@link #noTokens()} – keinerlei Token-Daten erfasst.</li>
 *   <li>{@link #cacheTokensIgnored()} – Cache-Tokens lagen vor, sind in
 *       V3.3 jedoch nicht in {@link #amountUsd()} enthalten.</li>
 *   <li>{@link #hasAnyCalculatedCost()} – mindestens ein berechneter
 *       Anteil floss in {@link #amountUsd()} ein. Wichtig zur Unter&shy;
 *       scheidung von &quot;keine Werte&quot; und &quot;Mikrobetrag&quot;.</li>
 * </ul>
 *
 * @param amountUsd            Gesamtbetrag in USD; {@code null} wenn nichts berechenbar war
 * @param exact                {@code true}, wenn alle Daten vollstaendig waren
 * @param partialTokens        {@code true}, wenn mindestens ein Token-Wert fehlte
 * @param missingPriceSnapshot {@code true}, wenn mindestens ein Preis-Snapshot fehlte
 * @param noTokens             {@code true}, wenn keinerlei Token-Daten vorlagen
 * @param cacheTokensIgnored   {@code true}, wenn Cache-Tokens vorkamen (in V3.3 nicht eingerechnet)
 * @param hasAnyCalculatedCost {@code true}, wenn ein berechneter Anteil enthalten ist
 */
public record CostResult(
        BigDecimal amountUsd,
        boolean exact,
        boolean partialTokens,
        boolean missingPriceSnapshot,
        boolean noTokens,
        boolean cacheTokensIgnored,
        boolean hasAnyCalculatedCost) {
}
