# 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 ` Ab M9 gilt verbindlich: - **`--config `** 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 ` 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 ` 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 `** 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 ` 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 `** 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 ` 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.