Abschluss-Dokumentation V3.1: betrieb.md, Bedienanleitung, Freigabedokument
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,166 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user