pdf-umbenenner/docs/ap-a-token-tracking-zusammenfassung.md

# AP-A Token-Tracking Fundament – Zusammenfassung

Dieses Dokument fasst alle Klassen, Methoden und Dateien zusammen, die im Zuge
von AP-A (Token- und Kosten-Tracking-Fundament der V3.3-Spezifikation, #74)
neu erstellt oder substanziell erweitert wurden.

## Schema-Migration

- `pdf-umbenenner-adapter-out/src/main/resources/db/migration/V2__token_tracking.sql`
  - Sechs neue Spalten in `processing_attempt`:
    `input_tokens`, `output_tokens`,
    `cache_creation_input_tokens`, `cache_read_input_tokens`,
    `price_input_per_token_nano_usd`, `price_output_per_token_nano_usd`.
  - Neue Tabelle `model_price` mit Composite Primary Key
    `(provider, model_name)`, NOT-NULL-Preisen, Currency-CHECK auf `'USD'`,
    `updated_at`-Spalte.
  - Zwei zusätzliche Indizes auf `processing_attempt`:
    `idx_processing_attempt_started_at_provider_fp_model`,
    `idx_processing_attempt_run_id_provider_model`.
  - Default-Preise für gpt-4o-mini, gpt-4o, gpt-4.1*, gpt-5*, claude-haiku-4-5,
    claude-sonnet-4-6 und claude-opus-4-7 (`ON CONFLICT DO NOTHING`).

## Application-Modul

### DTOs (`application/dto`)
- `AiUsageMetadata` – Token-Verbrauchsmetadaten mit `empty()`,
  `hasAnyTokenData()`, `hasCacheTokens()`.
- `ModelPriceEntry` – Schreib-/Validierungs-DTO mit Wertgrenzen-Validierung im
  Konstruktor.
- `ModelPriceView` – Lese-/Anzeige-DTO mit nullable `updatedAt` und
  `invalidUpdatedAt`-Flag.
- `ModelPriceKey` – Composite-Key für Löschungen.
- `ModelPriceChangeSet` – atomarer Block aus Upserts und Deletions, defensive
  Listen-Kopie.

### Cost-Komponenten (`application/cost`)
- `CostResult` – interpretierte Kosten-Anzeige mit Status-Flags.
- `CostCalculator` – `formatRow(...)` und `calculateAttempt(...)` (echt
  implementiert), `formatTotal(...)` als Stub für AP-B.

### Ports (`application/port/out`)
- `ModelPriceRepository` – `findAll`, `findByProviderAndModelName`, `upsert`,
  `delete`, `saveAllChanges`.
- `AiInvocationSuccess` (erweitert) – neues Feld `usageMetadata`.

### Use Cases (`application/usecase`)
- `DefaultManageModelPricesUseCase` – CRUD-Fassade mit ChangeSet-Konflikt-
  validierung (vier Regeln) und Provider-Whitelist beim Upsert.
- `ModelPriceValidationException` – deutsche Validierungsfehler-Exception.

### Application-Service-Anpassungen
- `AiNamingService` (erweitert) – reicht `AiUsageMetadata` aus dem
  `AiInvocationSuccess` als Token-Felder in den `AiAttemptContext` weiter.
- `DocumentProcessingCoordinator` (erweitert) –
  - neuer optionaler Konstruktor mit `ModelPriceRepository` und
    `headlessMode`-Flag.
  - `loadPriceSnapshot(modelName)` lädt Snapshot-Preis pro Versuch; Lookup-
    Fehler liefern leeren Snapshot ohne Attempt-Verlust.
  - `buildAttempt(...)` befüllt jetzt Token- und Preis-Snapshot-Felder im
    `ProcessingAttempt`.

### Domain-Anpassungen
- `AiAttemptContext` (erweitert) – vier nullable Token-Felder
  (`inputTokens`, `outputTokens`, `cacheCreationInputTokens`,
  `cacheReadInputTokens`); Backward-compatible Convenience-Konstruktor.
- `ProcessingAttempt` (erweitert) – sechs nullable Token-/Preis-Snapshot-
  Felder; Convenience-Konstruktor und `withoutAiFields(...)` ohne Verhaltens-
  änderung.

## Adapter-Out-Modul

- `SqliteConnectionFactory` (neu) – zentrale Connection-Factory; setzt
  `PRAGMA journal_mode=WAL` und `PRAGMA busy_timeout=5000`.
  Foreign-Key-Pragma wird bewusst nicht implizit gesetzt (Verhalten der
  bisherigen `DriverManager.getConnection`-Stellen erhalten).
- `SqliteUnitOfWorkAdapter`, `SqliteProcessingAttemptRepositoryAdapter`,
  `SqliteHistoryQueryAdapter`, `SqliteDocumentRecordRepositoryAdapter`
  (jeweils geändert) – nutzen die neue Factory.
- `SqliteProcessingAttemptRepositoryAdapter.save()` (erweitert) –
  INSERT um sechs neue Spalten erweitert, neue Hilfsmethode
  `setNullableLong(...)`.
- `SqliteHistoryQueryAdapter.mapToProcessingAttempt(...)` (erweitert) –
  liest die sechs neuen Spalten via `readNullableLong(...)`.
- `SqliteSchemaInitializationAdapter` (geändert) – erwartete Spalten/Indizes
  bleiben am V1-Zielschema; Doc-Klarstellung, dass V2 additiv auf der Baseline
  arbeitet.
- `SqliteModelPriceRepositoryAdapter` (neu) – `findAll`,
  `findByProviderAndModelName`, `upsert`, `delete`, `saveAllChanges`
  (UPSERT via `ON CONFLICT(provider, model_name) DO UPDATE`, transaktionaler
  Batch). Lese-Mapping behandelt `DateTimeParseException` als
  `invalidUpdatedAt`.
- `ModelPriceRepositoryException` (neu) – technischer JDBC-Fehler.

### KI-Adapter
- `AnthropicClaudeHttpAdapter` (geändert) – neue Methode
  `extractTokenUsageFromResponse(JSONObject)` für `usage.input_tokens`,
  `usage.output_tokens`, `usage.cache_creation_input_tokens`,
  `usage.cache_read_input_tokens` mit Validierung (negativ, > 10 Mio.,
  nicht-numerisch → NULL + WARN).
- `OpenAiHttpAdapter` (geändert) – analoge Methode mit Mapping
  `prompt_tokens → input_tokens`, `completion_tokens → output_tokens`;
  Cache-Felder bleiben null.

## GUI-Modul

### Neuer Tab "Modell-Preise"
- `adapter-in-gui/modelprices/GuiModelPriceManagementPort` (neu) –
  Bridge-Port für GUI-Zugriff auf Modell-Preise.
- `adapter-in-gui/modelprices/GuiModelPricesTab` (neu) – TableView mit
  editierbaren Preisspalten (`In/1M USD`, `Out/1M USD`), Lösch-Button mit
  Bestätigungsdialog, Add-Dialog mit Provider-Auswahl, Speichern-Aktion über
  `ModelPriceChangeSet`. Konvertierung Nano-USD ↔ `$/1M Tokens` mit
  HALF-UP-Rundung; unbekannte Provider werden read-only mit Tooltip
  angezeigt; `updatedAt = null` als "ungueltig".

### Anbindung im Workspace
- `GuiConfigurationEditorWorkspace` (geändert) – sechster Tab "Modell-
  Preise" wird angelegt; neue Methode `warnIfActiveModelHasNoPriceEntry()`
  zeigt vor dem Speichern eine deutsche Warnung an, wenn das aktuell
  ausgewählte Modell keinen Preis-Eintrag besitzt.
- `GuiStartupContext` (geändert) – neues optionales Feld
  `modelPriceManagementPort` mit Backward-Kompatibilität.
- `BootstrapRunner` (geändert) – neue Methode
  `buildGuiModelPriceManagementPort()` und Helfer für die Verdrahtung;
  Coordinator wird mit `ModelPriceRepository` und `headlessMode`-Flag
  versorgt.

### History-Tab
- `GuiHistoryTab` (geändert) – drei zusätzliche Spalten in der
  Versuchstabelle: Input-Tokens, Output-Tokens, Kosten. Cache-only-Versuche
  zeigen "nur Cache-Tokens, keine Standardkosten"; fehlender Preis-Snapshot
  führt zu "Preis fehlt"; Mikrobeträge als "< $0.0001"; Cache-Beteiligung
  ergänzt Suffix "(ohne Cache-Anteil)".

### Summary-Banner
- `BatchRunSummaryBanner` (geändert) – aus einzeiliger HBox wurde eine
  vierzeilige VBox: Status-Zeile, Token-Zeile, Kosten-Zeile, optionale
  Cache-only-Zeile. Neue Record-Klasse `BatchRunTokenSummary` mit
  `empty()`-Default; bestehende `update(Map)`-Aufrufer bleiben funktionsfähig.

## Testanpassungen

- `pdf-umbenenner-application/.../service/AiNamingServiceTest` und
  `pdf-umbenenner-bootstrap/.../e2e/StubAiInvocationPort` – alte
  `AiInvocationSuccess`-Konstruktoraufrufe um `AiUsageMetadata.empty()`
  ergänzt.
- `SqliteSchemaInitializationAdapterTest.fall1_leereDb_processingAttemptHatAlleErwartetenSpalten`
  prüft jetzt zusätzlich die sechs Token-/Preis-Spalten.
- `GuiAdapterSmokeTest.editorWorkspace_startStateShowsEmptyHeaderDefaultsAndOneTab`
  erwartet jetzt sechs Tabs inkl. "Modell-Preise".

## Build und Verifizierung

- `mvn clean verify` läuft auf dem Reactor `pdf-umbenenner-parent` durch
  (Tests grün auf allen Modulen).
- Commit `08ec021` auf `main` gepusht.

## Bewusst ausgesparte Bereiche (für AP-B / AP-C)

- `CostCalculator.formatTotal(...)` ist ein Stub und wirft
  `UnsupportedOperationException`.
- `TokenStatisticsReadModelPort`, `QueryCostAnalysisFullUseCase`,
  `QueryCostAnalysisHeaderOnlyUseCase`, `QueryRunSummaryUseCase`,
  `SqliteTokenStatisticsReadModelAdapter` sind nicht enthalten.
- Summary-Banner zeigt aktuell `0/0` Tokens und `$0.0000` Kosten, da das
  Read-Model erst in AP-B verdrahtet wird.
- CLI-Befehle für Modell-Preise (#99) und Modell-Combobox-Filter (#98)
  sind AP-C.