marcus/pdf-umbenenner
1
0
Fork 0
Code Issues 14 Releases 2 Activity
Files
ef985fb6af75525a7308398d189dd96a05a92886
pdf-umbenenner/docs/specs/V2_7_-_Spezifikation.md
T
marcus f4cfb5cbc0 Ergaenze zweiten GUI-Tab fuer Verarbeitungslauf mit Live-Fortschritt 
- 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>
2026-04-22 15:29:06 +02:00

298 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
1. Im neuen Tab „Verarbeitungslauf" einen Batch-Lauf starten
2. Den Gesamtfortschritt über alle Dateien live verfolgen
3. Jede abgeschlossene Datei mit Ergebnis in einer Liste sehen
4. Das KI-Reasoning zu einer Datei per Klick im Seitenbereich einsehen
5. 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 verify` ist grün
Reference in New Issue View Git Blame Copy Permalink