# Freigabedokument V3.1 – PDF-Umbenenner

## Geprüfter Stand

- Git-Branch: `main`
- Versionsnummer: `3.1.267`
- Freigabedatum: 2026-05-06
- **Status:** freigegeben

---

## Zielsetzung von V3.1

V3.1 ist der konsequente Nachschlag zu V3.0: Was der Produkttest aufgedeckt hat,
wird bereinigt. Kein großes Architektur-Feature, kein neues Maven-Modul –
gezielter UX-Schliff und Robustheit in drei Schwerpunkten:

1. **UX-Polishing** – sichtbare Schwächen aus dem V3.0-Produkttest behoben
   (#77, #80, #81, #83, #84, #88, #91)
2. **Verlauf-Tab reifen lassen** – Suche, Mehrfachauswahl, DB-Neuanlage
   (#82, #86, #87)
3. **Quick Win** – Mausrad-Zoom im PDF-Viewer als wertvoller Gebrauchskomfort
   (#32)

Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt vollständig unverändert.
Hexagonale Architektur, Modulstruktur, headless-Betrieb, `.properties`-
Konfigurationswahrheit und Flyway-DB-Evolution bleiben unangetastet.

---

## Umgesetzte Issues

| # | Kategorie | Beschreibung |
|---|---|---|
| #32 | GUI | Strg+Mausrad-Zoom in der PDF-Vorschau: Delta-Akkumulation für Trackpad-Kompatibilität, ScrollEvent bei Strg immer konsumiert, Zoom 10–500 %, Viewport-Mitte bleibt beim Zoom stabil, Fit-to-Width-Modus nach manuellem Zoom verlassen; Grab & Pan mit Handcursor im vergrößerten Zustand |
| #77 | UX | Vollständige Bestandsaufnahme aller interaktiven Elemente auf allen Tabs; fehlende Tooltips auf allen vier Tabs ergänzt; neue Konstanten ausschließlich in `GuiTooltipTexts`; TableColumn-Header über Column-Graphic-Pattern mit Label und Tooltip (kein Skin-/Lookup-Hack) |
| #80 | UX | Dirty-Indikator für den Konfigurations-Tab: Asterisk im Tab-Titel bei echter Nutzeränderung gegenüber Baseline-Snapshot; `loadingInProgress`-Flag verhindert unechte Dirty-State-Auslösung durch programmgesteuertes Laden; Bestätigungsdialog beim Verlassen mit ungespeicherten Änderungen; Kopplung mit DB-Pfad-Wechsel aus #87 |
| #81 | UX | Status-ComboBox und Versuche-Tabelle zeigen lesbare deutsche Anzeigetexte statt Enum-Rohnamen; alle acht Statuswerte über `ProcessingStatusPresentation` abgebildet; Status-ComboBox mit „Alle Status" als GUI-internem Null-Filter; DB-Queries intern weiterhin mit Enum-Namen |
| #82 | GUI | Live-Filter im Verlauf-Tab: 300 ms Debounce-Timer, Generation-Counter für Race-Condition-Schutz, veraltete Worker-Ergebnisse werden verworfen; Such-Button und Enter starten Suche sofort; Auswahl nach jeder neuen Suche vollständig geleert |
| #83 | UX | Leere KI-Begründung im Detailbereich zeigt `promptText`-Platzhalter statt leerem Feld; kein Vermischen von Nutzdaten und UI-Platzhaltertext; TextArea bleibt sichtbar |
| #84 | Bug | Aktionsbuttons im Verlauf-Tab werden nach Laufende ereignisgetrieben reaktiviert – unabhängig vom Terminierungsgrund (Erfolg, Fehlerabbruch, Nutzerabbruch, Leerlauf); kein manueller Workaround notwendig |
| #86 | GUI | Mehrfachauswahl im Verlauf-Tab: `SelectionMode.MULTIPLE`, Strg+A nur bei Tabellenfokus (kein Konflikt mit Suchfeld), Schlüssel-Snapshot vor Worker-Thread-Start, Bulk-Reset und Bulk-Delete mit Bestätigungsdialog und Partial-Success-Zusammenfassung; Detailbereich zeigt Platzhalter bei Mehrfachauswahl |
| #87 | GUI | Neuer Menüpunkt „Datenbank → Neue Datenbank anlegen...": atomarer Ablauf via Temp-Datei, Flyway auf neuesten Schema-Stand, Verbindungstest, atomarer Move mit `ATOMIC_MOVE + REPLACE_EXISTING`; normalisierter case-insensitiver Pfadvergleich; DB-Busy-Sperre; Konfig-Tab wechselt in Dirty-State; Hinweismeldung nach Wechsel |
| #88 | UX | Fehlerursache für `FAILED_FINAL`, `FAILED_RETRYABLE` und `SKIPPED_FINAL_FAILURE` im Verlauf-Tab sichtbar; Flyway-Migration ergänzt Spalte `failure_details` in `processing_attempt`; Begrenzung auf 1000 Zeichen mit „…"-Kürzung vor Persistierung; keine rohen Provider-Meldungen oder API-Schlüssel persistiert; NULL-Einträge zeigen `promptText`-Platzhalter |
| #91 | Robustheit | Lock-File-Pfadauflösung: absoluter Pfad direkt ohne Fallback (Abbruch bei Fehler); relativer oder unkonfigurierter Pfad zweistufig (JAR-Verzeichnis → `user.home` → Abbruch); fehlende Parent-Verzeichnisse automatisch angelegt; tatsächlich verwendeter absoluter Pfad beim Start auf INFO-Level geloggt; gilt für GUI- und headless Start |

### Nachbesserung aus dem Produkttest

| # | Beschreibung |
|---|---|
| #93 | Produkttest-Nachbesserung: Korrekturen und Feinabstimmungen nach abgeschlossenem manuellem GUI-Produkttest gegen echte KI-Provider und echte PDFs |

---

## Architektur-Bilanz

| Neu | Anzahl | Bemerkung |
|---|---|---|
| Inbound-Port-Interfaces | 1 | `CreateNewDatabaseUseCase` |
| Application-Use-Cases | 1 | `DefaultCreateNewDatabaseUseCase` |
| Outbound-Ports | 2 | `DatabaseCreationPort`, `ActiveDatabaseContextPort` |
| Outbound-Adapter | 2 | `SqliteDatabaseCreationAdapter`, `SqliteActiveDatabaseContextAdapter` |
| GUI-Bridge-Interfaces | 1 | `GuiCreateNewDatabasePort` |
| Flyway-Migration | 1 | `failure_details TEXT` in `processing_attempt` (nächste freie Versionsnummer) |

Geänderte Komponenten (ausschließlich `adapter-in-gui`):
`GuiHistoryTab`, `GuiConfigTab`, `GuiTooltipTexts`, Verlauf-Detailbereich,
Status-ComboBox, PDF-Vorschau-Komponente, Lauf-Abschluss-Signalkette.

Nicht geändert: `pdf-umbenenner-domain` (außer ggf. minimaler Erweiterung für #88),
`pdf-umbenenner-adapter-in-cli`, headless-Verarbeitungslogik, fachliche Kernverarbeitung.

---

## Verbindlich verifizierte Spec-Punkte

- Kein Enum-Rohname in der GUI sichtbar – alle acht Statuswerte tragen Displaytext
- `promptText` für leere Felder: kein Vermischen von Nutzdaten und Platzhaltertext
- Dirty-State Konfig-Tab: programmgesteuertes Laden löst kein Dirty-Flag aus
- Live-Filter: 300 ms Debounce, Generation-Counter, Auswahl nach Suche geleert
- Strg+A im Verlauf-Tab: nur bei Tabellenfokus (kein Konflikt mit Suchfeld)
- Schlüssel-Snapshot vor Bulk-Worker-Thread-Start
- DB-Anlage: normalisierter Pfadvergleich (case-insensitive, `toRealPath`/Parent-Normalisierung)
- DB-Anlage: `ATOMIC_MOVE + REPLACE_EXISTING`; kein halb-atomarer Fallback
- DB-Anlage: aktive DB bleibt bei Fehler vollständig unverändert
- Lock-File: absoluter Pfad direkt; relativer Pfad zweistufig; Pfad geloggt (INFO)
- Strg+Mausrad: ScrollEvent immer konsumiert; Delta-Akkumulation; 10–500 %
- `failure_details`: max. 1000 Zeichen vor Persistierung; keine rohen Provider-Meldungen
- Aktionsbuttons nach Laufende ereignisgetrieben reaktiviert (alle Terminierungsgründe)
- Flyway ist die einzige Schema-Evolutionsquelle – kein manuelles DDL im Code
- Code-Kommentare auf Deutsch; Logging auf Deutsch
- JavaDoc auf allen neuen öffentlichen Ports, Use-Cases und Adapter-Methoden

---

## Headless-Kompatibilität

Der bestehende Batch-Betrieb über `--headless` bleibt vollständig erhalten.
Die `.properties`-Datei bleibt die einzige Konfigurationswahrheit. GUI-Code
initialisiert den headless Pfad nicht. Keine stillen Änderungen an Retry-Semantik,
Status-Persistenz oder fachlicher Verarbeitungslogik.

Von V3.1-Änderungen betroffener headless-Pfad: Lock-File-Pfadauflösung (#91)
und Flyway-Schemamigration für `failure_details` (#88) – beide wirken beim
Programmstart unabhängig von GUI oder CLI.

---

## Datenbank-Migration

Flyway ergänzt die Tabelle `processing_attempt` um die Spalte `failure_details`:

```sql
ALTER TABLE processing_attempt ADD COLUMN failure_details TEXT;
```

- Bestehende Zeilen erhalten automatisch `NULL` – kein Datenverlust.
- Ältere Einträge ohne Fehlerdetails zeigen in der GUI einen `promptText`-Platzhalter.
- Kein SQL-`CHECK`-Constraint (um Importdaten nicht zu blockieren).
- Begrenzung auf 1000 Zeichen wird ausschließlich vor Persistierung im Adapter erzwungen.

---

## Produkttest

**Produkttest: bestanden**

Manueller GUI-Produkttest gegen echte KI-Provider mit echten PDFs abgeschlossen.
Alle elf Issues und die Nachbesserung #93 wurden end-to-end verifiziert.

---

## Bekannte Einschränkungen

Keine.

---

## Nicht in V3.1

- Automatischer Scheduler / Quellordner-Überwachung (#22) → V3.x
- PDF-Viewer Render-DPI (#23) → V3.2
- F1-Hilfe (#69) → V3.2
- Dark Mode (#70) → V3.x
- Log-Viewer in der GUI (#72) → V3.2
- Token- und Kosten-Tracking (#74) → V3.2
- Excel-Export (#75) → V3.2
- Automatische Update-Prüfung (#76) → V3.2
- Neue Maven-Module, neue KI-Provider, Architekturbrüche
- Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners

---

## Nächste Version

**V3.2** – geplante Schwerpunkte: PDF-Viewer Render-DPI, F1-Hilfe, Log-Viewer,
Token- und Kosten-Tracking, Excel-Export, automatische Update-Prüfung.

---

## Freigabeaussage

V3.1 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der hexagonalen
Architektur sind eingehalten. Die fachliche Kernverarbeitung des PDF-Umbenenners
bleibt unverändert gegenüber V3.0. Manueller Produkttest bestanden.
Keine Release-Blocker.
