Doku: R4 Dokumentations-Review umgesetzt
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
+8
-3
@@ -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.
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
@@ -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.
|
||||
+81
-15
@@ -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,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
|
||||
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**
|
||||
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
|
||||
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user