# Freigabedokument V3.1 – PDF-Umbenenner ## Geprüfter Stand - Git-Branch: `main` - Versionsnummer: `3.1.[BUILD]` - 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.