Meilensteine für V2.0 in der Pre-Version angelegt

docs/workpackages/M9 - Arbeitspakete.md

@@ -0,0 +1,381 @@
+# M9 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M9 – GUI-Grundgerüst, neues Betriebsmodell und Packaging-Basis**.
+
+Die Meilensteine **M1** bis **M8** sowie der dokumentierte Ist-Stand **V1.1** werden als vollständig umgesetzt und freigegeben vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, Build und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand oder dieses Dokument gedeckt sind.
+- Kein Vorgriff auf **M10+**.
+- Kein Umbau bestehender M1–M8-Strukturen ohne direkten M9-Bezug.
+- Die neue GUI wird als **eigener Inbound-Adapter** umgesetzt und **nicht** in Bootstrap vermischt.
+- Der bestehende **headless Batch-Betrieb** darf weder technisch noch verhaltensseitig still gebrochen werden.
+- Änderungen klein, fokussiert und architekturtreu halten.
+- Neue Typen, CLI-Optionen, Startpfade, Packaging-Anpassungen und Tests so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind.
+- Ein Arbeitspaket darf nur dann auf GUI-Verhalten aufbauen, wenn das technische Startfundament im unmittelbar vorhergehenden Arbeitspaket bereits hergestellt wurde.
+
+## Explizit nicht Bestandteil von M9
+
+- GUI-Konfigurationseditor
+- Willkommenstext und vollständige GUI-Benutzerführung aus M10
+- Öffnen/Speichern/Speichern unter in der GUI
+- Bearbeitung der `.properties`-Inhalte in der GUI
+- Datei-/Ordnerdialoge
+- Provider-ComboBox, Modellabruf oder Modellfeldlogik
+- sofortige Validierung im Editor
+- zentraler Meldungsbereich und feldnahe Fehlermeldungen
+- technische Tests und Korrekturhilfen in der GUI
+- automatische Prompt-Erzeugung
+- DB-/Historienanzeige
+- manueller Verarbeitungslauf aus der GUI
+- EXE
+- Installer
+- offizieller plattformübergreifender GUI-Support
+- neues Konfigurationsformat
+- Änderungen an fachlicher Benennungslogik, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten
+
+## Verbindliche M9-Regeln für **alle** Arbeitspakete
+
+### 1. Betriebsmodell
+
+Ab M9 gilt verbindlich:
+
+- **GUI ist der neue Standardstart**.
+- Über **`--headless`** startet weiterhin der bestehende Batch-/Scheduler-Betrieb.
+- Die Anwendung bleibt **ein einziges ausführbares JAR**.
+- Es gibt in M9 **keine EXE** und **keinen Installer**.
+
+### 2. CLI-Option `--config <pfad>`
+
+Ab M9 gilt verbindlich:
+
+- **`--config <pfad>`** steht für **GUI und headless** zur Verfügung.
+- Wird **headless ohne `--config`** gestartet, bleibt das bisherige Default-Verhalten der Konfigurationsauflösung erhalten.
+- Zeigt **`--config <pfad>` im GUI-Start** auf eine nicht existente Datei:
+  - erscheint eine klare Fehlermeldung,
+  - danach verhält sich die GUI so, als wäre `--config` nicht angegeben worden.
+- Zeigt **`--config <pfad>` im headless Start** auf eine nicht existente Datei, ist das ein **harter Startfehler**; ein stiller Fallback auf das Default-Verhalten ist in diesem Fall unzulässig.
+
+### 3. Modul- und Architekturregel
+
+Ab M9 gilt verbindlich:
+
+- Die Modulstruktur wird um **genau ein neues Modul** erweitert:
+  - `pdf-umbenenner-adapter-in-gui`
+- Die GUI ist ein **Inbound-Adapter**.
+- **Bootstrap** bleibt verantwortlich für:
+  - Startmoduswahl,
+  - Konfigurationsauflösung,
+  - Objektgraph,
+  - kontrollierten Start des passenden Adapters,
+  - Exit-Code-Ableitung bei harten Startfehlern.
+- Domain und Application bleiben frei von JavaFX-Typen.
+
+### 4. JavaFX- und Headless-Isolation
+
+Ab M9 gilt verbindlich:
+
+- JavaFX wird für den GUI-Betrieb **mit dem ausführbaren JAR ausgeliefert**.
+- Der **headless Start** darf **keine externe JavaFX-Installation** voraussetzen.
+- GUI-Code und JavaFX dürfen im **headless Pfad** nicht unnötig früh initialisiert oder geladen werden.
+- Fehlen GUI-Voraussetzungen beim tatsächlichen GUI-Start, ist das ein **kontrollierter GUI-Startfehler** mit klarer Rückmeldung.
+
+### 5. Logging-Basis und bestehender Log4j2-Stack
+
+Ab M9 gilt verbindlich:
+
+- Der GUI-Adapter nutzt denselben bestehenden Log4j2-Stack wie der headless Pfad.
+- Es wird **keine** zweite Logging-Konfiguration für die GUI eingeführt.
+- Logformat und Log-Pfad bleiben gegenüber dem bestehenden headless Betrieb unverändert.
+
+### 6. Plattformziel
+
+Ab M9 gilt verbindlich:
+
+- Die GUI wird offiziell nur für **Windows** vorgesehen.
+- Der headless Betrieb bleibt für **Windows Server / Task Scheduler** kompatibel.
+- M9 führt noch keine GUI-Funktionalität ein, die gemappte Laufwerke oder Datei-Dialoge fachlich ausreizt; die technische Grundlage darf dem späteren Windows-zentrierten Pfadverhalten jedoch nicht widersprechen.
+
+### 7. Exit-Code-Semantik
+
+Ab M9 gilt verbindlich:
+
+- **`0`** für die normale erfolgreiche Beendigung eines headless Laufs sowie für das reguläre Beenden der GUI.
+- **`1`** für harte Start-, Bootstrap-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler, einschließlich ungültiger CLI-Verwendung, nicht existenter `--config`-Datei im headless Start und GUI-Startfehlern vor erfolgreicher Anzeige der Oberfläche.
+- Dokumentbezogene Verarbeitungsfehler des bestehenden headless Laufs verändern dieses Exit-Code-Modell nicht.
+
+### 8. GUI-Zielstand innerhalb von M9
+
+M9 liefert **kein** vollständiges GUI-Produkt, sondern nur ein **technisch lauffähiges Grundgerüst**.
+
+Daraus folgt:
+
+- Es ist eine **minimale JavaFX-GUI-Shell** zulässig und zweckmäßig.
+- Diese Shell dient nur dem Nachweis des GUI-Startpfads.
+- Ein echter Konfigurationseditor ist ausdrücklich erst Gegenstand von **M10**.
+
+---
+
+## AP-001 Neues GUI-Modul und Maven-/Reactor-Basis einführen
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M9-Startpunkt.
+
+### Ziel
+Die Projektstruktur wird um ein eigenständiges GUI-Modul erweitert, ohne die bestehende Architektur oder den bisherigen headless Stand zu beschädigen.
+
+### Muss umgesetzt werden
+- Neues Modul **`pdf-umbenenner-adapter-in-gui`** anlegen.
+- Modul korrekt in Parent-POM und Reactor aufnehmen.
+- Abhängigkeiten so schneiden, dass das GUI-Modul als **Inbound-Adapter** auf die bestehenden inneren Schichten aufsetzen kann.
+- JavaFX-Grundabhängigkeiten nur dort einführen, wo sie für das GUI-Modul technisch erforderlich sind.
+- Sicherstellen, dass Domain, Application, Adapter-Out und CLI-Adapter frei von JavaFX-Abhängigkeiten bleiben.
+- Sicherstellen, dass das GUI-Modul den vorhandenen Log4j2-Stack des Projekts ohne neue Logging-Konfiguration mitbenutzt.
+- Erste neutrale Paket- und Klassenstruktur im neuen Modul anlegen, soweit für einen buildbaren Stand nötig.
+- JavaDoc und `package-info` für die neue Modulverantwortung ergänzen.
+
+### Explizit nicht Teil
+- tatsächlicher GUI-Start
+- CLI-Parsing für neue Optionen
+- Bootstrap-Anpassungen
+- Packaging des gemeinsamen JARs
+- GUI-Inhalt jenseits einer neutralen Modulbasis
+
+### Fertig wenn
+- das neue GUI-Modul im Reactor vorhanden ist,
+- die Abhängigkeitsrichtung architekturtreu bleibt,
+- der Gesamtbuild weiterhin fehlerfrei ist,
+- noch kein M10+-Verhalten vorweggenommen wurde.
+
+---
+
+## AP-002 Startmodus- und CLI-Optionsmodell für GUI, `--headless` und `--config` einführen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die Anwendung kann Startmodus und Konfigurationspfad formal eindeutig interpretieren, ohne den bestehenden headless Betrieb zu verlieren.
+
+### Muss umgesetzt werden
+- Technisches Modell für die Startmodi einführen:
+  - GUI-Standardstart,
+  - expliziter `--headless`-Start.
+- Neue CLI-Option **`--config <pfad>`** für beide Startarten einführen.
+- Parsing und Validierung der relevanten Optionen im Startpfad modellieren.
+- Bestehendes Default-Verhalten für headless Starts **ohne** `--config` ausdrücklich erhalten.
+- Klare Behandlung für fehlerhafte CLI-Verwendungen modellieren, insbesondere für:
+  - `--config` ohne Wert,
+  - unbekannte oder widersprüchliche Startparameter, soweit für M9 erforderlich.
+- Rückgabemodell so schneiden, dass Bootstrap daraus kontrolliert GUI-Start, headless Start oder harten Startfehler ableiten kann.
+- JavaDoc für Startmodussemantik und Konfigurationspfadbezug ergänzen.
+
+### Explizit nicht Teil
+- tatsächliches Laden einer GUI-Oberfläche
+- konkrete Behandlung nicht existenter Konfigurationsdateien im fertigen Startfluss
+- Packaging
+- GUI-Benutzerführung
+
+### Fertig wenn
+- Startmodus und Konfigurationspfad technisch eindeutig interpretierbar sind,
+- headless ohne `--config` weiterhin anschlussfähig bleibt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 Bootstrap-Verdrahtung für zwei Startpfade und kontrollierte Fehlerableitung erweitern
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Bootstrap kann zwischen GUI und headless sauber umschalten, ohne seine Verantwortung zu überschreiten.
+
+### Muss umgesetzt werden
+- Bootstrap so erweitern, dass es abhängig vom geparsten Startmodus den passenden Inbound-Adapter startet.
+- Sicherstellen, dass der bestehende headless Pfad fachlich und technisch erhalten bleibt.
+- Kontrollierte Fehlerableitung für harte Startfehler ergänzen, soweit M9 dies bereits erfordert.
+- Exit-Code-Modell für V2.0 an die bestehende V1.1-/M7-Semantik anschließen: `0` für normale erfolgreiche GUI-/headless-Beendigung, `1` für harte Start-, Bootstrap-, Konfigurations- oder Initialisierungsfehler.
+- Behandlung des Konfigurationspfadbezugs im Bootstrap vervollständigen.
+- Sicherstellen, dass Bootstrap keine GUI-Fachlogik oder M10-Editorlogik aufnimmt.
+- JavaDoc und `package-info` für aktualisierte Bootstrap-Verantwortung ergänzen.
+
+### Explizit nicht Teil
+- minimale GUI-Shell selbst
+- JavaFX-Packaging
+- GUI-Benutzerführung
+- Dateieditor oder Validierungslogik
+
+### Fertig wenn
+- Bootstrap technisch zwischen GUI und headless umschalten kann,
+- der headless Pfad weiterhin fehlerfrei und anschlussfähig bleibt,
+- harte Startfehler kontrolliert ableitbar sind,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Minimale JavaFX-GUI-Shell als Standardstartpfad bereitstellen
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Der neue Standardstartpfad führt in eine minimale, technisch saubere JavaFX-GUI-Shell, ohne bereits Editorlogik aus M10 vorzuziehen.
+
+### Muss umgesetzt werden
+- Minimale JavaFX-Einstiegsklasse im GUI-Modul implementieren.
+- Neutrale GUI-Shell bereitstellen, die den erfolgreichen GUI-Start technisch sichtbar macht.
+- Die GUI-Shell so schneiden, dass sie später ohne Architekturbruch zum Konfigurationseditor ausgebaut werden kann.
+- Sicherstellen, dass beim tatsächlichen GUI-Start klare Rückmeldungen für GUI-bezogene Startfehler möglich sind.
+- Sicherstellen, dass die GUI-Shell keine M10-Funktionalität vorwegnimmt, insbesondere:
+  - kein Konfigurationseditor,
+  - keine Dateioperationen,
+  - keine Validierung,
+  - keine Providerbedienung.
+- JavaDoc für Zweck und klare Nicht-Ziele der minimalen GUI-Shell ergänzen.
+
+### Explizit nicht Teil
+- Willkommenstext im finalen V2.0-Sinne
+- bearbeitbare Eingabefelder
+- Buttons **Neu**, **Öffnen**, **Speichern** usw.
+- Meldungsbereich
+- technische Tests
+
+### Fertig wenn
+- die Anwendung im Standardstart in eine minimale GUI-Shell startet,
+- die Shell technisch sauber vom headless Pfad getrennt ist,
+- noch kein M10+-Verhalten implementiert wurde,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 Konfigurationspfad-Semantik für GUI und headless vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Das Verhalten von `--config <pfad>` ist für beide Startarten vollständig, abwärtskompatibel und kontrolliert umgesetzt.
+
+### Muss umgesetzt werden
+- Verhalten für **existierende** Konfigurationsdateien in GUI und headless vervollständigen.
+- Verhalten für **nicht existente** Konfigurationsdateien explizit umsetzen:
+  - GUI: Fehlermeldung, danach GUI-Start wie ohne `--config`
+  - headless: harter Startfehler
+- Sicherstellen, dass das bestehende Default-Verhalten für headless **ohne** `--config` unangetastet bleibt.
+- Kontrollierte Rückmeldungen für problematische Konfigurationspfade ergänzen.
+- Keine GUI-Editorlogik oder Dateibearbeitung einführen; es geht ausschließlich um Startsemantik.
+- JavaDoc für die endgültige M9-Semantik von `--config` ergänzen.
+
+### Explizit nicht Teil
+- Bearbeiten oder Speichern der Konfiguration in der GUI
+- Datei-Dialoge
+- neue Konfigurationswerte
+- inhaltliche Validierung der `.properties`
+
+### Fertig wenn
+- `--config` für GUI und headless kontrolliert funktioniert,
+- die unterschiedlichen Fehlerpfade wie festgelegt umgesetzt sind,
+- headless ohne `--config` weiterhin kompatibel bleibt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-006 Packaging-Basis für gemeinsames JAR mit integrierter JavaFX-Laufzeit herstellen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Das Projekt erzeugt weiterhin genau ein ausführbares Artefakt, das den GUI-Standardstart technisch ermöglicht und den headless Pfad nicht unnötig belastet.
+
+### Muss umgesetzt werden
+- Build-/Packaging-Konfiguration so erweitern, dass weiterhin **ein gemeinsames ausführbares JAR** entsteht.
+- JavaFX-Laufzeit und erforderliche GUI-Bestandteile in das Artefakt integrieren, soweit für den Windows-GUI-Start von M9 erforderlich.
+- Sicherstellen, dass der headless Startpfad keine unnötig frühe JavaFX-Initialisierung erzwingt.
+- Konkret absichern, dass der headless Startpfad ohne Initialisierung der JavaFX-Application-Klasse durchlaufen kann.
+- Packaging so schneiden, dass keine EXE und kein Installer eingeführt werden.
+- Bestehende Artefakterzeugung aus V1.1 nicht still zerstören.
+- Dokumentierende Build-Hinweise ergänzen, soweit für M9 zwingend nötig.
+
+### Explizit nicht Teil
+- vollständige Enddokumentation von V2.0
+- M10-GUI-Funktionalität
+- plattformübergreifendes Packaging
+- EXE-/Installer-Bau
+
+### Fertig wenn
+- weiterhin genau ein ausführbares JAR erzeugt wird,
+- dieses JAR den M9-GUI-Start technisch tragen kann,
+- der headless Startpfad weiterhin anschlussfähig ist und ohne JavaFX-Application-Initialisierung nachweisbar bleibt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-007 Start-, Fehler- und Packaging-Tests für den vollständigen M9-Zielstand vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der vollständige M9-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Tests für den GUI-Standardstart ergänzen, soweit im Projekt technisch sinnvoll automatisierbar.
+- Tests für **`--headless`** ergänzen.
+- Automatisierten Nachweis ergänzen, dass der headless Start ohne Initialisierung der JavaFX-Application-Klasse durchlaufen kann.
+- Tests für **`--config <pfad>`** in beiden Startarten ergänzen.
+- Negativtests für ungültige oder fehlende Konfigurationspfade ergänzen, insbesondere:
+  - GUI mit nicht existenter Konfigurationsdatei,
+  - headless mit nicht existenter Konfigurationsdatei,
+  - `--config` ohne Wert.
+- Tests ergänzen, die belegen, dass headless ohne `--config` weiterhin das bisherige Default-Verhalten nutzt.
+- Smoke-Tests für die Artefakterzeugung und Packaging-Basis ergänzen.
+- Mindestens einen technischen Test ergänzen, der das GUI-Threadingmodell belegt, z. B. den Nachweis, dass der UI-Thread während eines simulierten langen Hintergrundvorgangs nicht blockiert.
+- Tests für das verbindliche Exit-Code-Modell von GUI- und headless Startpfad ergänzen, soweit im Projekt stabil automatisierbar.
+- Sicherstellen, dass dokumentbezogene Batch-Funktionalität nicht versehentlich regressiert ist.
+- Den M9-Stand abschließend auf Architekturtreue, Abwärtskompatibilität und Nicht-Vorgriff auf M10+ prüfen.
+
+### Explizit nicht Teil
+- GUI-Editor-Tests aus M10
+- Validierungs- und Modellabruf-Tests aus M11
+- technische Test- und Korrekturhilfe-Tests aus M12
+- Abschlussdokumentation aus M13
+
+### Fertig wenn
+- der vollständige M9-Zielstand automatisiert abgesichert ist,
+- GUI- und headless Startpfade kontrolliert nachgewiesen sind,
+- das gemeinsame JAR reproduzierbar gebaut wird,
+- der definierte M9-Zielzustand vollständig erreicht ist,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete decken den vollständigen Zielumfang von **M9 – GUI-Grundgerüst, neues Betriebsmodell und Packaging-Basis** ab:
+
+- neues GUI-Modul als eigener Inbound-Adapter
+- GUI als Standardstart
+- `--headless` als erhaltener Batch-/Scheduler-Pfad
+- neue CLI-Option `--config <pfad>` für beide Startarten
+- kontrollierte, unterschiedliche Fehlersemantik für GUI und headless bei nicht existenter Konfigurationsdatei
+- saubere Bootstrap-Umschaltung zwischen zwei Startpfaden
+- minimale JavaFX-GUI-Shell als technischer Nachweis des GUI-Starts
+- ein gemeinsames ausführbares JAR mit integrierter JavaFX-Basis
+- Absicherung, dass headless ohne unnötige GUI-Initialisierung weiter nutzbar bleibt
+- Tests für Startverhalten, Fehlerpfade und Packaging
+
+Damit ist M9 bewusst klar von den späteren GUI-Funktionalitäten aus **M10** bis **M13** getrennt und liefert dennoch einen eigenständig lauffähigen, architekturtreuen und reviewbaren Zwischenstand.