pdf-umbenenner/docs/workpackages/M9 - Arbeitspakete.md

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.