marcus
f4cfb5cbc0
- Fuehrt neuen Inbound-Adapter-Subpfad batchrun/ mit Tab, Koordinator, Launcher-Port und Ergebniszeilen-Model ein; der Batch-Lauf laeuft auf einem Hintergrund-Worker, UI-Updates ausschliesslich via FX-Dispatcher. - Ergaenzt application.port.in um BatchRunProgressObserver, BatchRunCancellationToken, DocumentCompletionEvent/-Status und RunSummary; DefaultBatchRunProcessingUseCase und DocumentProcessingCoordinator melden Lauf-/Dokument-Ereignisse an den Beobachter und unterstuetzen Soft-Stop zwischen Kandidaten. - Verdrahtet BootstrapRunner so, dass die GUI den vollstaendigen Headless-Pipelinepfad (Migration, Validierung, Schema-Init, Lock, Use-Case) mit Observer und Cancellation ausfuehrt; headless-Verhalten bleibt unveraendert. - Editor-Workspace bettet den zweiten Tab ein, sperrt Tab 1 mit Hinweisbanner waehrend eines Laufs und fragt den Benutzer beim Schliessen waehrend eines laufenden Batches. - Fuegt Tests fuer Observer-Wiring, Koordinator-Lebenszyklus und Tab-Smoke-Verhalten ein; aktualisiert die GUI-Bedienanleitung und docs/betrieb.md auf den neuen Tab. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
12 KiB
12 KiB
V2.7 – GUI-Verarbeitungslauf mit Live-Verfolgung
Status: Freigegeben
Erstellt: 2026-04-22
Überarbeitet: 2026-04-22 (nach Review, finale Version)
Autor: Marcus (mit Claude als Mentor)
Ziel
V2.7 erweitert die JavaFX-GUI um einen zweiten Tab „Verarbeitungslauf", über den der Benutzer einen Batch-Lauf direkt aus der GUI starten und dessen Fortschritt in Echtzeit verfolgen kann. Der bestehende headless-Betrieb über den Windows Task Scheduler bleibt unverändert erhalten.
Hintergrund
Bisheriger Zustand
- Die GUI dient in V2.0–V2.6 ausschließlich der Konfiguration und technischen Validierung
- Ein Verarbeitungslauf kann nur über die Kommandozeile bzw. eine Batch-Datei gestartet werden
- Es gibt keine Möglichkeit, den Fortschritt eines laufenden Batches live zu beobachten
Motivation
- Der manuelle Kommandozeilenstart ist für den Alltagsbetrieb umständlich
- Ohne Live-Anzeige ist unklar, ob und wie schnell die Verarbeitung voranschreitet
- Eine einzelne Datei wird schnell verarbeitet – eine Gesamtfortschrittsanzeige ist daher sinnvoller als eine dateiweise Einzelanzeige
Zielbild
Nach Abschluss von V2.7 kann der Benutzer:
- Im neuen Tab „Verarbeitungslauf" einen Batch-Lauf starten
- Den Gesamtfortschritt über alle Dateien live verfolgen
- Jede abgeschlossene Datei mit Ergebnis in einer Liste sehen
- Das KI-Reasoning zu einer Datei per Klick im Seitenbereich einsehen
- Den laufenden Batch per Soft-Stop sauber abbrechen
Fachliche Anforderungen
Neuer Tab „Verarbeitungslauf"
- Der bestehende Tab „Konfiguration" bleibt Tab 1 – unverändert
- Tab 2 heißt „Verarbeitungslauf"
- Tab-Struktur war in V2.0 bereits vorbereitet
Layout Tab 2
┌─────────────────────────────────────────────────────────┐
│ [Fortschrittsbalken] 12 / 47 Dateien │
├──────────────────────────────────┬──────────────────────┤
│ Ergebnisliste │ Seitenbereich │
│ (scrollbar) │ (KI-Reasoning) │
│ │ │
│ │ │
├──────────────────────────────────┴──────────────────────┤
│ Meldungs- und Zusammenfassungsbereich │
├─────────────────────────────────────────────────────────┤
│ [Starten] [Abbrechen] │
└─────────────────────────────────────────────────────────┘
Meldungs- und Zusammenfassungsbereich
Der untere Bereich des Tab 2 dient als einheitlicher Meldungs- und Zusammenfassungsbereich. Er übernimmt zwei Rollen:
- Meldungsbereich – zeigt Startfehler, Hinweise (z. B. 0 Dateien) und technische Exceptions
- Zusammenfassung – zeigt nach Laufende:
{X} erfolgreich, {X} fehlgeschlagen, {X} übersprungen
Während des Laufs ist der Bereich leer oder zeigt den letzten Statushinweis. Es gibt in Tab 2 keinen separaten zweiten Meldungsbereich.
Konfigurationsquelle beim Start
- Der Lauf verwendet ausschließlich den zuletzt gespeicherten Stand der
.properties-Datei - Ungespeicherte Änderungen im Konfigurationseditor (Tab 1) fließen nicht in den Lauf ein
- Der Starten-Button prüft vor dem Lauf, ob die gespeicherte Konfiguration lauffähig ist – nicht den aktuellen Editorzustand
Startvoraussetzungen und Startfehler
Ein Lauf startet nur, wenn alle folgenden Voraussetzungen erfüllt sind:
| Voraussetzung | Verhalten bei Fehler |
|---|---|
| Gespeicherte Konfiguration vorhanden und lauffähig | Fehlermeldung, kein Lauf |
| Quellordner vorhanden und lesbar | Fehlermeldung, kein Lauf |
| Zielordner vorhanden oder anlegbar | Fehlermeldung, kein Lauf |
| SQLite-Datei nutzbar | Fehlermeldung, kein Lauf |
| API-Key vorhanden | Fehlermeldung, kein Lauf |
| Kein anderer Verarbeitungslauf in dieser Anwendungsinstanz aktiv | Fehlermeldung, kein Lauf |
Bei einem Startfehler:
- Erscheint eine klare Fehlermeldung im Meldungs- und Zusammenfassungsbereich
- Fortschrittsbalken und Ergebnisliste bleiben unverändert
- Starten-Button bleibt aktiv, Abbrechen-Button bleibt deaktiviert
Verhalten bei 0 verarbeitbaren Dateien
- Kein technischer Fehler
- Kein Lauf im eigentlichen Sinne
- Hinweis im Meldungs- und Zusammenfassungsbereich: „Keine verarbeitbaren Dateien im Quellordner gefunden"
- Zusammenfassung:
0 erfolgreich, 0 fehlgeschlagen, 0 übersprungen
Fortschrittsbalken
- Die zu verarbeitende Dateimenge wird einmalig beim Start bestimmt
- Der Nenner bleibt für den gesamten Lauf konstant – Dateien die während des Laufs im Quellordner auftauchen oder verschwinden, werden nicht berücksichtigt
- Gezählt werden alle abgeschlossenen Dateien: erfolgreich + fehlgeschlagen + übersprungen
- Daneben wird der Zählerstand angezeigt, z. B. „12 / 47 Dateien"
- Vor dem ersten Start: leer / 0 %
Statusmodell
Jede Datei erhält nach Abschluss genau einen der folgenden Status:
| Status | Icon | Bedeutung |
|---|---|---|
| Erfolgreich | ✅ | Datei wurde umbenannt, Zieldatei erzeugt |
| Fehlgeschlagen (retryable) | ⚠️ | Transienter Fehler, wird beim nächsten Lauf erneut versucht |
| Fehlgeschlagen (permanent) | ❌ | Inhaltsfehler, kein weiterer Retry |
| Übersprungen | ⏭️ | Datei war bereits verarbeitet oder wurde bewusst ausgelassen |
Alle vier Status zählen als abgeschlossen im Sinne des Fortschrittsbalkens.
Ergebnisliste
Jede abgeschlossene Datei erscheint als neue Zeile in der Liste. Nach Abschluss jeder Datei erscheint ohne manuellen Refresh ein neuer Eintrag. Die Liste wächst während des Laufs von oben nach unten.
| Spalte | Erfolg | Fehler / Übersprungen |
|---|---|---|
| Status-Icon | ✅ / ⚠️ / ❌ / ⏭️ | wie links |
| Originaldateiname | Quelldateiname | Quelldateiname |
| Neuer Dateiname | Finaler Zieldateiname | — |
| Datum | Ermitteltes Datum | — |
| Dauer | Verarbeitungszeit in Sekunden | Verarbeitungszeit in Sekunden |
- Klick auf eine Zeile zeigt Details im Seitenbereich
- Die Liste ist scrollbar
- Die Liste ist nicht persistent: bleibt nur für die Dauer des aktuellen Programmstarts
- Bei einem neuen Lauf innerhalb desselben Programmstarts wird die Liste geleert
- Nach Programmstart ist die Liste leer
Seitenbereich (KI-Reasoning)
- Rechts neben der Ergebnisliste, fest im Layout verankert (kein Popup, kein Dialog)
- Zeigt nach Klick auf eine Zeile:
- Originaldateiname
- Ermittelter Titel
- Ermitteltes Datum
- KI-Reasoning (Volltext)
- Liegt für einen Eintrag kein KI-Reasoning vor (Fehler vor KI-Aufruf, übersprungen), erscheint der Hinweistext: „Für diesen Eintrag liegt kein KI-Reasoning vor."
- Vor dem ersten Klick: Hinweistext „Datei auswählen für Details"
- Bei neuem Lauf wird der Seitenbereich geleert
Starten-Button
- Startet den Verarbeitungslauf über alle Dateien im konfigurierten Quellordner
- Verwendet die gespeicherte Konfiguration – nicht den aktuellen Editorzustand
- Gleiches fachliches Batch-Verhalten wie der headless-Betrieb: gleiche Anwendungslogik, gleicher Use Case, nur andere Präsentationsschicht
- Keine Dateiauswahl – alle Dateien werden verarbeitet
- Während des Laufs: deaktiviert
- Nach Abschluss oder Abbruch: wieder aktiv
Abbrechen-Button
- Nur während eines laufenden Batches aktiv, sonst deaktiviert
- Verhalten: Soft-Stop
- Die aktuell in Bearbeitung befindliche Datei wird vollständig fertig verarbeitet
- Das Stop-Flag wird nach Abschluss jeder Datei und vor Start der nächsten Datei geprüft – niemals mitten in einer atomaren Persistenzoperation
- Danach wird der Lauf sauber beendet, keine halbfertigen Zustände in der SQLite-Datenbank
- Nach dem Soft-Stop erscheint die Zusammenfassung im Meldungs- und Zusammenfassungsbereich
Konfiguration während des Laufs
- Tab 1 „Konfiguration" wird während eines laufenden Verarbeitungslaufs gesperrt
- Im Konfiguration-Tab erscheint ein sichtbarer Hinweis: „Konfiguration während eines laufenden Verarbeitungslaufs nicht editierbar"
- Nach Abschluss, Abbruch oder unerwarteter Exception wird Tab 1 wieder freigegeben
Verhalten bei unerwarteter technischer Exception
Tritt während des Laufs eine unerwartete Exception auf:
- Die GUI wechselt in einen definierten terminalen Zustand:
- Starten-Button: aktiv
- Abbrechen-Button: deaktiviert
- Tab 1: entsperrt
- Meldungs- und Zusammenfassungsbereich: Fehlermeldung sichtbar
- Es entsteht kein „hängender" UI-Zustand
Fenster schließen während eines laufenden Laufs
- Schließt der Benutzer das Fenster während ein Lauf aktiv ist, wird der Close-Request abgefangen
- Es erscheint ein Hinweisdialog mit zwei Optionen:
- „Nicht schließen" – Lauf läuft weiter
- „Lauf beenden und schließen" – Soft-Stop wird ausgelöst, nach Abschluss der aktuellen Datei schließt die Anwendung
- Kein Hard-Abbruch ohne Benutzerentscheidung
Parallele Läufe
- Pro Anwendungsinstanz ist nur ein Verarbeitungslauf gleichzeitig zulässig
- Ein zweiter Startversuch während ein Lauf aktiv ist wird verweigert mit der Meldung: „Ein Verarbeitungslauf ist bereits aktiv."
- Bekannte Einschränkung: Ein gleichzeitiger externer headless-Lauf (Windows Task Scheduler) wird von der GUI nicht aktiv erkannt und nicht technisch geblockt. Der Benutzer ist selbst verantwortlich, parallele Läufe zu vermeiden. Diese Einschränkung ist seit V2.0 dokumentiert und bleibt in V2.7 unverändert bestehen.
Nicht in V2.7 enthalten
- Dateiauswahl (welche Dateien verarbeitet werden sollen)
- Einzeldatei-Fortschrittsanzeige
- Historien-Tab / SQLite-Ansicht
- Kosten-Tracking
- Automatischer Neustart nach Abschluss
- Benachrichtigungen (Windows-Tray, Toast)
- Parallelverarbeitung mehrerer Dateien
- Technisches Locking gegen externe headless-Läufe
Abnahmekriterien
- Tab 2 „Verarbeitungslauf" ist in der GUI vorhanden und erreichbar
- Starten-Button verwendet ausschließlich die gespeicherte Konfiguration
- Starten-Button startet den Batch-Lauf über alle Dateien im Quellordner
- Die Dateimenge wird beim Start einmalig bestimmt; der Nenner des Fortschrittsbalkens bleibt während des gesamten Laufs konstant
- Fortschrittsbalken zählt alle abgeschlossenen Dateien (erfolgreich + fehlgeschlagen + übersprungen)
- Nach Abschluss jeder Datei erscheint ohne manuellen Refresh ein neuer Eintrag in der Ergebnisliste
- Alle fünf Spalten der Ergebnisliste sind für Erfolgsfälle korrekt befüllt
- Spalte „Neuer Dateiname" und „Datum" zeigen
—für Fehler- und Übersprungen-Fälle - Alle vier Status-Icons sind korrekt: ✅ ⚠️ ❌ ⏭️
- Klick auf Zeile zeigt KI-Reasoning im Seitenbereich
- Einträge ohne KI-Reasoning zeigen den definierten Hinweistext im Seitenbereich
- Seitenbereich zeigt vor erstem Klick den Hinweistext „Datei auswählen für Details"
- Soft-Stop beendet den Lauf nach Abschluss der aktuellen Datei; keine weitere Datei wird begonnen
- Meldungs- und Zusammenfassungsbereich zeigt nach Laufende die Zusammenfassung mit korrekten Zählern
- Tab 1 ist während des Laufs gesperrt, Hinweis ist sichtbar
- Tab 1 wird nach Abschluss, Abbruch oder Exception wieder entsperrt
- Bei unerwarteter Exception wechselt die GUI in den definierten terminalen Zustand
- Ergebnisliste und Seitenbereich sind nach Programmstart leer
- Ergebnisliste und Seitenbereich werden bei neuem Lauf geleert
- Start mit nicht lauffähiger Konfiguration wird verweigert; Fehlermeldung erscheint im Meldungs- und Zusammenfassungsbereich
- Start bei leerem Quellordner erzeugt keinen Fehler; Hinweis erscheint im Meldungs- und Zusammenfassungsbereich
- Zweiter Startversuch während laufendem Lauf wird verweigert; Meldung erscheint
- Close-Request während Lauf öffnet Hinweisdialog mit zwei Optionen
- headless-Betrieb ist unverändert funktionsfähig
mvn clean verifyist grün