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. 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.

6. 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.

7. GUI-Threadingmodell

Ab M9 gilt verbindlich für alle V2.0-Meilensteine:

• Jede potenziell blockierende Operation der GUI – insbesondere providerseitiger Modellabruf, providerseitige technische Tests, Pfad- und Dateisystemprüfungen, SQLite-Prüfungen sowie das Lesen und Schreiben der .properties-Datei – läuft auf einem Hintergrund-Worker-Thread.
• UI-Updates erfolgen ausschließlich über den JavaFX Application Thread (Platform.runLater).
• Die GUI darf während laufender Hintergrund-Operationen nicht einfrieren.
• Diese Regel ist Referenz für alle threadingbezogenen Formulierungen in M9–M13; Wiederholungen sind in einzelnen Meilensteinen nicht erforderlich.

8. Exit-Codes

Ab M9 gilt verbindlich für alle V2.0-Meilensteine:

• Exit-Code 0: normale erfolgreiche Beendigung eines headless Laufs sowie für das reguläre Beenden der GUI.
• Exit-Code 1: 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 im headless Lauf ändern dieses Exit-Code-Modell nicht; sie bleiben Teil des fachlichen Laufresultats wie bereits in V1.1.

9. GUI-Logging

Ab M9 gilt verbindlich:

• Der GUI-Adapter nutzt denselben Log4j2-Stack wie der headless Pfad.
• Logformat und Log-Verzeichnis bleiben gegenüber dem headless Betrieb unverändert.
• Mindesteintrag für GUI-nahe Ereignisse sind: Start- und Beendigungsereignisse der GUI, Modellabruf-Versuche (Provider, Erfolg/Misserfolg, ohne API-Key), Dateischreibvorgänge inkl. Zielpfad, Ergebnisse der Aktionen Validieren und Technische Tests ausführen, sowie alle schreibenden Korrekturen.

10. GUI-Teststrategie

Ab M9 gilt verbindlich für alle V2.0-Meilensteine:

• View-Modelle und Application-nahe GUI-Logik werden mit JUnit unit-getestet. Testfokus liegt auf Zustandsübergängen, Validierungsregeln und Datenflüssen, nicht auf Rendering.
• GUI-Smoke-Tests laufen unter headless JavaFX (Monocle) in der Maven-Test-Phase. Sie prüfen, dass zentrale GUI-Pfade (Start, Laden, grundlegende Interaktionen) technisch durchlaufen, ohne einen sichtbaren Desktop vorauszusetzen.
• Es wird kein TestFX und kein weiteres GUI-Testframework über Monocle hinaus eingeführt.
• Diese Teststrategie gilt als Referenz für alle testbezogenen Formulierungen in den Arbeitspaketen von M9 bis M13.

11. JavaDoc-Standard für V2.0

Ab M9 gilt verbindlich für alle V2.0-Meilensteine:

Für jede neu hinzugefügte oder substanziell geänderte öffentliche Klasse, öffentliche Methode und jedes neue Java-Package gilt:

• Klassen-JavaDoc: Zweck, Verantwortung und Abgrenzung der Klasse.
• Methoden-JavaDoc: Zweck, Parameter, Rückgabewert und dokumentierte Ausnahmen.
• package-info.java: pro neuem Package, mit Kurzbeschreibung der Paketverantwortung.

Dieser Standard gilt als Bestandteil jedes „Fertig wenn"-Abschnitts in V2.0. Ein Arbeitspaket ist erst dann fertig, wenn die betroffenen öffentlichen Klassen und Methoden dem JavaDoc-Standard entsprechen.

---

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.
• 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.
• 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 gemäß der in M9 festgelegten GUI-Teststrategie ergänzen.
• 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.
• 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.