From 014b11abd21774a663fc2fef6103667cd81fcefd Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Tue, 28 Apr 2026 15:04:56 +0200 Subject: [PATCH] Doku: R4 Dokumentations-Review umgesetzt Co-Authored-By: Claude Sonnet 4.6 --- docs/befundliste.md | 11 +++- docs/betrieb.md | 2 +- docs/freigabe-v2_9.md | 112 ++++++++++++++++++++++++++++++++++++ docs/gui-bedienanleitung.md | 98 +++++++++++++++++++++++++------ 4 files changed, 203 insertions(+), 20 deletions(-) create mode 100644 docs/freigabe-v2_9.md diff --git a/docs/befundliste.md b/docs/befundliste.md index 1a46916..eb9e42e 100644 --- a/docs/befundliste.md +++ b/docs/befundliste.md @@ -236,7 +236,7 @@ enthält JavaFX (Win-Classifier), alle Module, PDFBox, SQLite-JDBC und Log4j2. | 15 | Legacy-Migration mit `.bak`-Sicherung | **erfüllt** | `LegacyConfigurationMigrator` in `adapter-out`; GUI-Pfad ruft `detectedLegacyConfiguration` + `migrateConfigurationIfNeeded` in `BootstrapRunner` auf. `GuiConfigurationPropertiesWriterTest` prüft Backup-Schema. | | 16 | Keine neuen Provider über Claude/OpenAI-kompatibel hinaus | **erfüllt** | Codebase enthält ausschließlich `ClaudeAiInvocationAdapter` und `OpenAiCompatibleAiInvocationAdapter`. Kein dritter Provider. | | 17 | Keine neuen Distributionsformate (EXE/Installer) | **erfüllt** | `pom.xml` des Bootstrap-Moduls nutzt ausschließlich `maven-shade-plugin`. Kein `launch4j`, kein `jpackage`, kein Installer. | -| 18 | Kein manueller Verarbeitungslauf aus GUI | **erfüllt** | `adapter-in-gui` enthält keine Klasse, die `BatchRunProcessingUseCase` aus einem GUI-Event aufruft. Kein „Start"-Button, keine Batch-Ausführungslogik im GUI-Adapter. | +| 18 | Kein manueller Verarbeitungslauf aus GUI (abgelöst ab V2.1) | **erfüllt** | `adapter-in-gui` enthält keine Klasse, die `BatchRunProcessingUseCase` aus einem GUI-Event aufruft. Kein „Start"-Button, keine Batch-Ausführungslogik im GUI-Adapter. | | 19 | Keine DB-/Historienanzeige | **erfüllt** | Kein SQLite-Lesepfad aus `adapter-in-gui`. Kein Historien-Tab. Kein Ergebnis-Browser. | | 20 | Keine fachlichen Änderungen an Kernverarbeitung | **erfüllt** | `DefaultBatchRunProcessingUseCase`, `DocumentProcessingCoordinator`, `AiNamingService`, `AiResponseValidator` sind gegenüber dem V1.1-Freigabestand unverändert. E2E-Tests (`BatchRunEndToEndTest`, 11 Szenarien) sind alle grün. | @@ -293,10 +293,10 @@ GUI-Teststrategie (kein TestFX über Monocle hinaus) und ist keine Abweichung vo Die folgenden Themen wurden im V2.0-Umfang nachweislich **nicht** implementiert und sind ausdrücklich für spätere Ausbaustufen vorgesehen: -- **Manueller Verarbeitungslauf aus der GUI** (V2.1+) +- **Manueller Verarbeitungslauf aus der GUI** (V2.1+) – **umgesetzt ab V2.1** (Tab „Verarbeitungslauf") - **DB-/Historienansicht** in der GUI (V2.x+) - **Kosten-Tracking** und Token-/Preisberechnung (V2.x+) -- **EXE-Wrapper / Installer** (V3+) +- **EXE-Wrapper / Installer** (V3+) – **umgesetzt ab V3**: EXE-Wrapper (M14), MSI-Installer (M15) - **Weitere KI-Provider** über Claude und OpenAI-kompatibel hinaus (V3+) - **Automatischer Fallback zwischen Providern** (V3+) - **Profilverwaltung mit mehreren Konfigurationen je Provider** (V3+) @@ -348,3 +348,8 @@ das Fenster beim Start automatisch maximiert wird. Konfigurationsdatei in `java.util.prefs.Preferences` (Schlüssel `lastConfigPath`). Beim nächsten Start wird diese Datei automatisch geladen, sofern sie noch existiert. Fehlt die Datei, startet die GUI ohne Fehlermeldung mit dem Willkommenstext. + +--- + +> **Hinweis:** Für die Ausbaustufen V2.1 bis V2.9 wurden keine separaten Befundlisteneinträge +> erstellt. Befunde, Fixes und Verbesserungen dieser Stufen sind in den Gitea-Issues dokumentiert. diff --git a/docs/betrieb.md b/docs/betrieb.md index 56f8e62..f7b148b 100644 --- a/docs/betrieb.md +++ b/docs/betrieb.md @@ -189,7 +189,7 @@ Vorlagen für lokale und Test-Konfigurationen befinden sich in: | `max.retries.transient` | Maximale transiente Fehlversuche pro Dokument (ganzzahlig, >= 1) | | `max.pages` | Maximale Seitenzahl pro Dokument (ganzzahlig, > 0) | | `max.text.characters` | Maximale Zeichenanzahl des Dokumenttexts für KI-Anfragen (ganzzahlig, > 0) | -| `max.title.length` | Maximale Länge des Basistitels in Zeichen (ganzzahlig, 10..120, Default 60). Werte unter 10 oder über 120 verhindern den Start. Werte 10–19 und 100–120 erzeugen eine Startwarnung. | +| `max.title.length` | Maximale Länge des Basistitels in Zeichen (ganzzahlig, 10..120, Default 60). Werte unter 10 oder über 120 verhindern den Start. Werte 10–39 und 100–120 erzeugen eine Startwarnung. | | `prompt.template.file` | Pfad zur externen Prompt-Datei (muss vorhanden sein) | ### Provider-Parameter diff --git a/docs/freigabe-v2_9.md b/docs/freigabe-v2_9.md new file mode 100644 index 0000000..1318ed1 --- /dev/null +++ b/docs/freigabe-v2_9.md @@ -0,0 +1,112 @@ +# V2.9-Freigabe + +## Geprüfter Stand + +- Git-Branch: `main` +- Git-Commit (HEAD, zum Zeitpunkt der Prüfung): `6ff463b7efd935960c246dd48f9c55906699a82d` +- Datum der Prüfung: 2026-04-28 + +--- + +## Umfang gegenüber V2.0 + +V2.9 ist die erste umfangreiche Funktionserweiterung nach dem V2.0-Abschluss. +Der Schwerpunkt liegt auf dem neuen Tab „Verarbeitungslauf", der PDF-Vorschau, +dem editierbaren Dateinamen-Bereich und der Kommunikation von Verarbeitungsergebnissen +an den Benutzer. + +### Neu in V2.9 + +| Thema | Issues | Beschreibung | +|---|---|---| +| Tab „Verarbeitungslauf" (Grundstruktur) | #20, #21 | Zweiter Tab mit Ergebnistabelle, Detailbereich und PDF-Vorschau; Anwendungs-Icon und System-Tray | +| PDF-Vorschau (PDFBox-Migration) | #27, #29 | Direktes Rendering via `PDFRenderer.renderImageWithDPI`; Lazy Rendering mit In-Memory-Cache; Mausrad-Navigation | +| Vollbild-Start | #28 | `stage.setMaximized(true)` beim GUI-Start | +| Letzte Konfiguration automatisch laden | #33 | `java.util.prefs.Preferences` (`lastConfigPath`) | +| Historischer Dateiname für SKIPPED-Dokumente | #41 | Spalte „Neuer Dateiname" zeigt historischen KI-Vorschlag für übersprungene Einträge | +| Detailbereich für SKIPPED-Zeilen | #30 | `GuiHistoricalDocumentContextPort` liefert historischen Kontext; Detailbereich zeigt Datum, Name und Reasoning aus früherem Lauf | +| Manuelle Dateinamen-Eingabe (nicht verarbeitete Dateien) | #31 | Dateiname-Editor für `FAILED_RETRYABLE`, `FAILED_PERMANENT`, `SKIPPED_FINAL_FAILURE` zur manuellen Kopie | +| Benutzerfreundliche Fehlermeldungen | #43 | `AiFailureMessageTranslator` übersetzt technische Fehler für `FAILED`-Einträge ins Deutsche | +| Differenzierte Status-Icons mit Farben | #44 | Unicode-Symbole `✓ ↻ × ≡ ⊘ ⟳` mit farbiger CSS-Darstellung statt Emoji | +| Einzelinstanz-Schutz | #35 | Loopback-ServerSocket verhindert parallele Instanzen; zweite Instanz beendet sich sofort | +| UX-Fixes im Detailbereich | #39, #40, #45, #46, #47 | Abstände, Button-Deaktivierung, Hinweisbereich | +| Konfigurationsbereich kompakter | #24 | Layout-Optimierungen im Konfigurationstab | +| Legacy-Datumsformat-Behandlung | #48 | `stringToInstant()`-Fehlerbehandlung; korrekte Abschlussmeldung bei SKIPPED-only-Läufen | +| Prompt-Optimierung bei Zeichenlimit | #42 | Prompt weist KI explizit zur Kürzung auf konfiguriertes Zeichenlimit an | + +--- + +## Ausgeführte Prüfungen + +| Prüfung | Ergebnis | +|---|---| +| Vollständiger Maven-Reactor-Build (`clean verify`, alle 6 Module, `-DskipPitest=true`) | **ERFOLGREICH** | +| Unit-Tests gesamt | **siehe Tabelle** | +| Shaded-JAR erzeugt unter `pdf-umbenenner-bootstrap/target/` | **ja** | +| Architekturkonsistenz (kein JavaFX in Domain/Application, keine Adapter-zu-Adapter-Abhängigkeiten) | **ja** | +| Naming-Regel (keine M/AP/V-Bezeichner in Code) | **ja** | +| Dokumentation (`gui-bedienanleitung.md`, `betrieb.md`) auf Konsistenz mit Implementierung geprüft | **ja** | + +--- + +## Build- und Test-Ergebnisse + +Ausgeführtes Kommando: +``` +.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-adapter-in-gui,pdf-umbenenner-bootstrap --also-make -DskipPitest=true +``` + +**Gesamtergebnis: BUILD SUCCESS** + +| Modul | Tests | Failures | Errors | Skipped | +|---|---|---|---|---| +| `pdf-umbenenner-domain` | 227 | 0 | 0 | 0 | +| `pdf-umbenenner-application` | 455 | 0 | 0 | 0 | +| `pdf-umbenenner-adapter-in-cli` | 8 | 0 | 0 | 0 | +| `pdf-umbenenner-adapter-in-gui` | 190 | 0 | 0 | 0 | +| `pdf-umbenenner-adapter-out` | 371 | 0 | 0 | 0 | +| `pdf-umbenenner-bootstrap` | 147 | 0 | 0 | 0 | +| **Gesamt** | **1.398** | **0** | **0** | **0** | + +--- + +## Bekannte Einschränkungen + +### #42 – Prompt-Kürzungsverhalten modellabhängig + +Der Prompt weist die KI explizit an, bei Überschreitung des konfigurierten Zeichenlimits +den Titel auf die zulässige Länge zu kürzen. Ob das Modell dieser Anweisung zuverlässig +folgt, hängt vom eingesetzten Modell ab. Modelle mit schwacher Instruction-Following-Fähigkeit +können das Limit ignorieren; in diesem Fall greift die bestehende serverseitige +Validierung und der Versuch wird als Fehler klassifiziert. + +--- + +## Offene Punkte (für nachfolgende Stufen) + +Die folgenden Issues sind bekannt, aber nicht Release-Blocker für V2.9: + +| Issue | Thema | +|---|---| +| #7 | Persistenz-Browser / Historienansicht in der GUI | +| #22 | Kosten-Tracking und Token-Anzeige | +| #23 | Weitere KI-Provider jenseits Claude / OpenAI-kompatibel | +| #32 | Platzhalterbild in PDF-Vorschau bei fehlendem/ungültigem PDF | +| #34 | Dokumentation des Tab-„Verarbeitungslauf"-Bedienkonzepts vervollständigen | +| #44 | Icon-Farben unter bestimmten Windows-Systemthemen prüfen | +| #49 | Abbruch eines laufenden Verarbeitungslaufs aus der GUI | +| #50 | Fortschrittsanzeige während des Verarbeitungslaufs | +| #51 | Filter- und Sortierfunktion in der Ergebnistabelle | + +--- + +## Freigabeaussage + +V2.9 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der hexagonalen +Architektur sind eingehalten. Die fachliche Kernverarbeitung des PDF-Umbenenners +bleibt unverändert gegenüber V2.0. Keine Release-Blocker. + +Der vollständige Maven-Reactor-Build ist grün (1.398 Tests, 0 Failures, 0 Errors, +0 Skipped). Die Dokumentation (`gui-bedienanleitung.md`, `betrieb.md`) ist auf +den V2.9-Stand gebracht. Die bekannte Einschränkung (#42) ist dokumentiert +und kein funktionaler Defekt. diff --git a/docs/gui-bedienanleitung.md b/docs/gui-bedienanleitung.md index ff6a885..530446a 100644 --- a/docs/gui-bedienanleitung.md +++ b/docs/gui-bedienanleitung.md @@ -18,8 +18,8 @@ Die GUI gliedert sich in zwei feste Tabs: Weiterhin **nicht** enthalten sind ein Historien-Tab, eine Datenbankansicht und ein Kosten-Tracking — diese Ausbauten sind für spätere Stufen vorbehalten. -Der headless Batch-/Scheduler-Betrieb über `--headless` bleibt der einzige Weg, -PDF-Dateien automatisiert zu verarbeiten. +Für unbeaufsichtigte, geplante Läufe (z. B. Windows Task Scheduler) bleibt +`--headless` der empfohlene Weg. --- @@ -468,13 +468,25 @@ in den Lauf ein. Vor dem Start muss die Konfiguration daher gespeichert sein. - Nach jeder abgeschlossenen Datei erscheint ohne manuellen Refresh eine neue Zeile mit den fünf Spalten **Status-Icon**, **Originaldateiname**, **Neuer Dateiname**, **Datum** und **Dauer**. -- Für Fehler- und Übersprungen-Fälle wird bei den Spalten „Neuer Dateiname" und „Datum" - ein Gedankenstrich `—` eingetragen. -- Die Status-Icons folgen: ✅ erfolgreich, ⚠️ fehlgeschlagen (retryable), - ❌ fehlgeschlagen (permanent), ⏭️ übersprungen. -- Ein Klick auf eine Zeile zeigt die KI-Begründung im Seitenbereich. Liegt keine - Begründung vor, erscheint der Hinweistext „Für diesen Eintrag liegt kein KI-Reasoning - vor.". +- Für `FAILED_*`-Zeilen und `SKIPPED_FINAL_FAILURE`-Zeilen wird in den Spalten + „Neuer Dateiname" und „Datum" ein Gedankenstrich `—` eingetragen. + `SKIPPED_ALREADY_PROCESSED`-Zeilen zeigen in der Spalte „Neuer Dateiname" den + historischen Zieldateinamen aus dem letzten erfolgreichen Lauf; „Datum" bleibt `—`. +- Status-Icons (Unicode-Zeichen mit Farbe): + + | Symbol | Farbe | Bedeutung | + |--------|-------|-----------| + | `✓` | Grün | Erfolgreich | + | `↻` | Orange | Fehlgeschlagen (wiederholbar) | + | `×` | Rot | Fehlgeschlagen (permanent) | + | `≡` | Blau | Übersprungen (bereits erfolgreich verarbeitet) | + | `⊘` | Grau | Übersprungen (endgültig fehlgeschlagen) | + | `⟳` | Grau | Zurückgesetzt – wartet auf nächsten Lauf | + +- Ein Klick auf eine Zeile öffnet den Detailbereich rechts. Für `FAILED_*`-Einträge + zeigt der Detailbereich eine übersetzte Fehlermeldung (Präfix `⚠`) anstelle des + KI-Reasonings. Liegt weder Reasoning noch Fehlermeldung vor, erscheint der + Hinweistext „Für diesen Eintrag liegt kein KI-Reasoning vor.". - Nach Laufende erscheint die Zusammenfassung `X erfolgreich, Y fehlgeschlagen, Z übersprungen` im Meldungs- und Zusammenfassungsbereich. @@ -604,18 +616,43 @@ Das Panel enthält drei Bereiche: (preserveRatio=true). Keine Scrollbalken, keine manuelle Zoom-Einstellung. - Das Rendering erfolgt direkt über Apache PDFBox bei 120 DPI. -### KI-Begründung +### KI-Begründung und Fehlertext -Der mittlere Bereich zeigt das KI-Reasoning des ausgewählten Eintrags. Liegt kein -Reasoning vor (z. B. bei Übersprungen-Einträgen), erscheint der Hinweis +Der mittlere Bereich zeigt das KI-Reasoning des ausgewählten Eintrags. + +Für Einträge mit Status `FAILED_*` wird – sofern kein KI-Reasoning vorliegt – +stattdessen eine übersetzte Fehlermeldung angezeigt (Präfix `⚠`), zum Beispiel: + +- „PDF enthält keinen lesbaren Text. Möglicherweise handelt es sich um einen Scan + ohne Texterkennung (OCR). Eine automatische Benennung ist nicht möglich." +- „KI-Dienst: Ungültiger API-Schlüssel. Bitte in den Einstellungen prüfen." +- „KI-Dienst nicht erreichbar. Bitte Verbindung und Konfiguration prüfen." + +Für `SKIPPED_ALREADY_PROCESSED`-Einträge erscheint der Zeitpunkt des letzten +erfolgreichen Verarbeitungslaufs, sofern er in der Datenbank vorliegt. + +Liegt weder Reasoning noch Fehlermeldung vor, erscheint der Hinweis „Für diesen Eintrag liegt kein KI-Reasoning vor.". ### Editierbarer Dateiname -- Unterhalb des Reasoning-Bereichs befindet sich ein **editierbares Textfeld** mit - dem aktuellen Dateinamen des Eintrags. -- Das Feld kann direkt bearbeitet werden. Die Eingabe wird **live validiert** - (Formatprüfung `YYYY-MM-DD - Titel.pdf`, Titelzeichen, Länge). +Unterhalb des Reasoning-Bereichs befindet sich ein **editierbares Textfeld** mit +dem Dateinamen des ausgewählten Eintrags (ohne `.pdf`-Erweiterung; `.pdf` wird als +nicht editierbares Label daneben angezeigt). + +#### Aktivitätszustand je Zeilenstatus + +| Zeilenstatus | Textfeld-Verhalten | +|---|---| +| Kein Eintrag selektiert | Leer, deaktiviert | +| `SUCCESS` | Editierbar; letzter gespeicherter Name vorausgefüllt. Ermöglicht Umbenennung der vorhandenen Zieldatei. | +| `SKIPPED_ALREADY_PROCESSED` | Editierbar (sofern historischer Dateiname vorhanden). Ermöglicht Umbenennung der vorhandenen Zieldatei. | +| `FAILED_RETRYABLE`, `FAILED_PERMANENT`, `SKIPPED_FINAL_FAILURE` | Editierbar; Feld leer. Erlaubt Eingabe eines manuellen Dateinamens für eine direkte Kopie der Quelldatei. | +| Zurückgesetzt (`⟳`) | Deaktiviert | +| Lauf aktiv | Vollständig deaktiviert | + +Das Feld kann direkt bearbeitet werden. Die Eingabe wird **live validiert** +(Formatprüfung `YYYY-MM-DD - Titel.pdf`, Titelzeichen, Länge). - Fehlerhafte Eingaben werden direkt unter dem Feld als rote Meldung angezeigt. - **Speichern:** Der Button **„Übernehmen"** führt die Umbenennung durch – atomare Dateisystem- und DB-Transaktion inkl. automatischer Rollback bei Fehler. @@ -639,3 +676,32 @@ Reasoning vor (z. B. bei Übersprungen-Einträgen), erscheint der Hinweis | Keine Koordination mit parallelen headless Läufen | Ein gleichzeitiger externer headless Lauf wird nicht technisch geblockt. Schreibkonflikte sind nicht ausgeschlossen, wenn dieselbe `.properties`-Datei parallel genutzt wird | | GUI nur für Windows | Die GUI wird offiziell nur unter Windows unterstützt; der headless Betrieb ist für Windows Server geeignet | | Ergebnisliste nicht persistent | Die Ergebnisliste im Verarbeitungslauf-Tab existiert nur für den aktuellen Programmstart; nach Neustart ist die Liste leer | +| Einzelinstanz-Schutz | Wird die Anwendung ein zweites Mal gestartet, während bereits eine Instanz läuft (auch wenn diese im System-Tray minimiert ist), beendet sich die neue Instanz sofort ohne Hinweisfenster | + +--- + +## 15. System-Tray + +Wird das Hauptfenster über das Schließen-Symbol (oder Alt+F4) geschlossen, ohne dass +ungespeicherte Änderungen oder ein aktiver Verarbeitungslauf vorliegen, **minimiert +sich die Anwendung in den Windows System-Tray** statt sich zu beenden. Das Fenster +bleibt im Hintergrund aktiv und ist über das Tray-Icon wieder erreichbar. + +### 15.1 Tray-Icon-Menü + +Ein **Rechtsklick** auf das Tray-Icon öffnet ein Kontextmenü: + +| Eintrag | Wirkung | +|---------|---------| +| **Öffnen** | Bringt das Hauptfenster in den Vordergrund | +| **Beenden** | Beendet die Anwendung vollständig | + +Ein **Doppelklick** auf das Tray-Icon hat denselben Effekt wie „Öffnen". + +### 15.2 Sonderfälle beim Schließen + +| Situation | Verhalten | +|---|---| +| Ungespeicherte Änderungen | Schutzdialog erscheint zuerst (Speichern / Verwerfen / Abbrechen); erst nach Auflösung wird in den Tray minimiert | +| Aktiver Verarbeitungslauf | Hinweisdialog erscheint (Abschnitt 13); nach Soft-Stop oder Abschluss kann in den Tray minimiert werden | +| System-Tray nicht verfügbar | Fenster wird beim Schließen wie ohne Tray-Support behandelt; der Schutzdialog für ungespeicherte Änderungen bleibt aktiv |