Doku: R4 Dokumentations-Review umgesetzt

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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.

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

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.

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,
+Für unbeaufsichtigte, geplante Läufe (z. B. Windows Task Scheduler) bleibt
-PDF-Dateien automatisiert zu verarbeiten.
+`--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"
+- Für `FAILED_*`-Zeilen und `SKIPPED_FINAL_FAILURE`-Zeilen wird in den Spalten
-  ein Gedankenstrich `—` eingetragen.
+  „Neuer Dateiname" und „Datum" ein Gedankenstrich `—` eingetragen.
-- Die Status-Icons folgen: ✅ erfolgreich, ⚠️ fehlgeschlagen (retryable),
+  `SKIPPED_ALREADY_PROCESSED`-Zeilen zeigen in der Spalte „Neuer Dateiname" den
-  ❌ fehlgeschlagen (permanent), ⏭️ übersprungen.
+  historischen Zieldateinamen aus dem letzten erfolgreichen Lauf; „Datum" bleibt `—`.
-- Ein Klick auf eine Zeile zeigt die KI-Begründung im Seitenbereich. Liegt keine
+- Status-Icons (Unicode-Zeichen mit Farbe):
-  Begründung vor, erscheint der Hinweistext „Für diesen Eintrag liegt kein KI-Reasoning
+
-  vor.".
+  | 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,17 +616,42 @@ 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
+Der mittlere Bereich zeigt das KI-Reasoning des ausgewählten Eintrags.
-Reasoning vor (z. B. bei Übersprungen-Einträgen), erscheint der Hinweis
+
+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
+Unterhalb des Reasoning-Bereichs befindet sich ein **editierbares Textfeld** mit
-  dem aktuellen Dateinamen des Eintrags.
+dem Dateinamen des ausgewählten Eintrags (ohne `.pdf`-Erweiterung; `.pdf` wird als
-- Das Feld kann direkt bearbeitet werden. Die Eingabe wird **live validiert**
+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
@@ -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 |