8.7 KiB
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:
- UX-Polishing – sichtbare Schwächen aus dem V3.0-Produkttest behoben (#77, #80, #81, #83, #84, #88, #91)
- Verlauf-Tab reifen lassen – Suche, Mehrfachauswahl, DB-Neuanlage (#82, #86, #87)
- 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
promptTextfü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:
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.