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

docs/workpackages/M13 - Arbeitspakete.md

@@ -0,0 +1,384 @@
+# M13 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M13 – V2.0-Abschluss, Dokumentation und Qualitätsnachweis**.
+
+Die Meilensteine **M1** bis **M12** 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 Dokumentation, Build, Bootstrap, GUI, CLI, Konfigurationsbeispiele und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, `meilensteine-v2_0.md` oder dieses Dokument gedeckt sind.
+- Kein Vorgriff auf spätere Ausbaustufen **jenseits von V2.0**.
+- Kein Umbau bestehender M1–M12-Strukturen ohne direkten M13-Bezug.
+- M13 ergänzt **keine neue Produktfunktionalität**, sondern dokumentiert, stabilisiert und belegt den bereits definierten V2.0-Gesamtstand.
+- GUI und headless bleiben **ein gemeinsames ausführbares JAR**; M13 erfindet keine neue Distributionsform.
+- Der bestehende **headless Server-/Scheduler-Betrieb** darf weder technisch noch dokumentarisch still gebrochen werden.
+- Änderungen klein, fokussiert und architekturtreu halten.
+- Ein Arbeitspaket darf nur dann einen Release-Blocker beheben, wenn dieser im unmittelbar vorhergehenden Prüf-Arbeitspaket **konkret nachgewiesen und eingegrenzt** wurde.
+
+## Explizit nicht Bestandteil von M13
+
+- DB-/Historienanzeige
+- manueller Verarbeitungslauf aus der GUI
+- EXE
+- Installer
+- neues Konfigurationsformat
+- neue Provider über Claude und OpenAI-kompatibel hinaus
+- Cost-Tracking oder Token-/Preisberechnung
+- neue Tabs oder größere GUI-Ausbaustufen jenseits des vorhandenen V2.0-Umfangs
+- neue fachliche Regeln für Dateinamensbildung, Retry, Persistenz oder Laufverhalten
+- plattformübergreifender offizieller GUI-Support außerhalb des definierten Windows-Ziels
+
+## Verbindliche M13-Regeln für **alle** Arbeitspakete
+
+### 1. M13 ist ein Abschluss- und Nachweismeilenstein
+
+Ab M13 gilt verbindlich:
+
+- Der funktionale V2.0-Umfang wird **nicht erweitert**, sondern für Betrieb, Übergabe und Freigabe abgesichert.
+- Änderungen in Produktionscode sind nur zulässig, wenn sie für:
+  - dokumentierte Start-/Betriebssemantik,
+  - belastbare Tests,
+  - Packaging-Stabilität,
+  - oder konkret nachgewiesene Release-Blocker
+  zwingend erforderlich sind.
+
+### 2. GUI und headless müssen gemeinsam und widerspruchsfrei beschrieben sein
+
+Ab M13 gilt verbindlich:
+
+- Die Dokumentation beschreibt den gemeinsamen Betrieb eines **einzigen ausführbaren JARs**.
+- **GUI ist Standardstart**.
+- **`--headless`** aktiviert den bisherigen Batch-/Scheduler-Betrieb.
+- **`--config <pfad>`** gilt für GUI und headless.
+- Verhalten bei ungültigem oder nicht vorhandenem `--config` muss für beide Startarten klar dokumentiert und testbar belegt sein.
+
+### 3. `.properties` bleibt die einzige Konfigurationswahrheit
+
+Ab M13 gilt verbindlich:
+
+- Dokumentation, Konfigurationsbeispiele, GUI-Verhalten und headless Betrieb verwenden weiterhin dieselbe `.properties`-Struktur.
+- M13 führt keine zweite Konfigurationswelt für GUI oder headless ein.
+- Prompt-Datei und Properties-Datei bleiben getrennte Artefakte; die Prompt-Datei bleibt externe Datei.
+
+### 4. Headless-Abwärtskompatibilität ist release-kritisch
+
+Ab M13 gilt verbindlich:
+
+- Bestehender headless Betrieb ohne GUI-Einsatz bleibt lauffähig.
+- Headless darf keine separate JavaFX-Installation voraussetzen.
+- Bestehendes Default-Verhalten für headless Starts **ohne `--config`** bleibt erhalten.
+- Regressionen im bisherigen Server-/Scheduler-Betrieb gelten in M13 als **Release-Blocker**.
+
+### 5. Windows-zentrierte GUI-Dokumentation
+
+Ab M13 gilt verbindlich:
+
+- Die GUI wird für **Windows** dokumentiert.
+- Windows-spezifische Pfade und gemappte Laufwerke bleiben Teil des Zielbilds.
+- Dokumentation und Beispiele dürfen diese Pfadrealität nicht still relativieren oder auf UNC-only reduzieren.
+
+### 6. Qualitätsnachweis basiert auf real ausgeführten Prüfungen
+
+Ab M13 gilt verbindlich:
+
+- Ein V2.0-Freigabestand wird nur auf Basis **real ausgeführter Builds und Tests** beschrieben.
+- Prüf- und Freigabedokumente müssen den tatsächlich ausgeführten Stand wiedergeben.
+- Reine Absichtserklärungen ohne realen Nachweis sind für M13 unzureichend.
+
+### 7. Release-Blocker und finale Freigabe sind getrennte Schritte
+
+Ab M13 gilt verbindlich:
+
+- Zuerst wird eine **Befundliste** mit konkret eingegrenzten Restthemen erstellt.
+- Danach dürfen nur die dokumentierten Release-Blocker gezielt behoben werden.
+- Erst danach erfolgt eine finale Gesamtprüfung und Freigabedokumentation.
+
+---
+
+## AP-001 V2.0-Betriebs- und Startdokumentation für GUI und headless konsolidieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M13-Startpunkt.
+
+### Ziel
+Der V2.0-Betrieb wird für Benutzer und Betreiber klar, widerspruchsfrei und vollständig beschrieben.
+
+### Muss umgesetzt werden
+- README bzw. vorhandene Start-/Betriebsdokumentation gezielt auf den V2.0-Stand erweitern.
+- Mindestens folgende Punkte klar und konsistent dokumentieren:
+  - gemeinsames ausführbares JAR,
+  - GUI als Standardstart,
+  - `--headless`,
+  - `--config <pfad>`,
+  - Exit-Code-Modell von V2.0 mit `0` für normale erfolgreiche GUI-/headless-Beendigung und `1` für harte Start-, Bootstrap-, Konfigurations- oder Initialisierungsfehler,
+  - Verhalten bei fehlender oder ungültiger Konfiguration,
+  - Verhalten bei GUI-Startfehlern,
+  - Windows-Bezug und gemappte Laufwerke.
+- Dokumentieren, dass V2.0 **keinen** manuellen Verarbeitungslauf aus der GUI enthält.
+- Dokumentieren, dass die GUI in V2.0 der Konfiguration, Validierung und technischen Prüfung dient.
+- Terminologie zwischen README, JavaDoc, GUI-Texten und Startsemantik vereinheitlichen.
+
+### Explizit nicht Teil
+- neue Produktfunktionalität
+- vollständige Testergänzung
+- Release-Blocker-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- der V2.0-Betrieb für GUI und headless klar dokumentiert ist,
+- die Startoptionen widerspruchsfrei beschrieben sind,
+- die Dokumentation zum realen Verhalten des aktuellen Codes passt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Konfigurationsbeispiele, Standardvorlage und Prompt-Bezug für den V2.0-Endstand konsolidieren
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die im Repository enthaltenen Konfigurations- und Prompt-Beispiele passen konsistent zum realen V2.0-Verhalten der GUI und des headless Betriebs.
+
+### Muss umgesetzt werden
+- Vorhandene Konfigurationsbeispiele prüfen und auf den V2.0-Stand bringen.
+- Sicherstellen, dass mindestens nachvollziehbar und konsistent abgebildet sind:
+  - mehrere Provider-Konfigurationen in einer Datei,
+  - genau ein aktiver Provider,
+  - GUI-relevante und headless-relevante Konfigurationswerte,
+  - `prompt.template.file`,
+  - konservative Default-Werte,
+  - V2.0-relevante Grenz- und Warnparameter.
+- Die Standardvorlage für **„Neue Konfiguration“** und die dokumentierten Konfigurationsbeispiele semantisch aufeinander abstimmen.
+- Sicherstellen, dass die Dokumentation den gemeinsamen Standardpfad `config/application.properties` relativ zum Arbeitsverzeichnis konsistent beschreibt, wo dies für GUI-Speichervorschläge und headless Standardverhalten relevant ist.
+- Den Umgang mit `.bak`-Sicherungen beim Überschreiben bestehender `.properties`-Dateien konsistent dokumentieren.
+- Den Umgang mit automatisch erzeugbarer deutscher Standard-Prompt-Datei dokumentieren.
+- Sicherstellen, dass Dateinamen, Pfadbeispiele und Properties-Namen zum tatsächlichen Code passen.
+
+### Explizit nicht Teil
+- neue GUI-Funktionalität
+- größere Prompt-Überarbeitung jenseits des dokumentierten Standardfalls
+- Release-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- Konfigurationsbeispiele und Standardvorlage konsistent zum V2.0-Stand sind,
+- Prompt-Bezug und automatische Prompt-Erzeugung nachvollziehbar beschrieben sind,
+- Properties-Namen und Beispielwerte zum realen Code passen,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 Regressionstests für headless Abwärtskompatibilität, Startoptionen und Konfigurationspfade ergänzen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Die kritischen V2.0-Risiken im bisherigen Server-/Scheduler-Betrieb werden automatisiert abgesichert.
+
+### Muss umgesetzt werden
+- Regressionstests für den headless Betrieb ergänzen oder vervollständigen, insbesondere für:
+  - headless Start ohne `--config` mit bestehendem Default-Verhalten,
+  - headless Start mit gültigem `--config`,
+  - headless Start mit ungültigem bzw. nicht vorhandenem `--config` als harter Startfehler,
+  - keine unzulässige Abhängigkeit von separater JavaFX-Installation im headless Pfad.
+- Tests für Parsing und Semantik von `--headless` und `--config` ergänzen.
+- Tests für das verbindliche Exit-Code-Modell im headless Pfad ergänzen, soweit dies stabil automatisierbar ist.
+- Sicherstellen, dass bestehender Batch-/Scheduler-Betrieb durch V2.0 nicht still verändert wird.
+- Relevante Start- und Fehlermeldungssemantik mit absichern, soweit dies stabil automatisierbar ist.
+
+### Explizit nicht Teil
+- GUI-interaktive Bedienpfade
+- Release-Befundliste
+- Freigabedokument
+- neue Produktfunktionalität
+
+### Fertig wenn
+- die headless Abwärtskompatibilität belastbar automatisiert abgesichert ist,
+- Startoptionen und Konfigurationspfade regressionssicher geprüft werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 GUI-Smoke- und Interaktionstests für den V2.0-Kernumfang vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Die zentralen V2.0-GUI-Pfade sind automatisiert so abgesichert, dass Bedienung, Startzustände und wichtige Fehlersituationen regressionssicher werden.
+
+### Muss umgesetzt werden
+- GUI-nahe Tests für die zentralen V2.0-Bedienpfade ergänzen oder vervollständigen, insbesondere für:
+  - leerer GUI-Start ohne geladene Konfiguration,
+  - Willkommenstext und sichtbare Grundaktionen,
+  - `--config` im GUI-Start mit gültiger Datei,
+  - `--config` im GUI-Start mit nicht vorhandener Datei inklusive Fehlermeldung und Fallback auf leeren GUI-Zustand,
+  - Dirty-State-Kennzeichnung,
+  - Schutzdialoge bei ungespeicherten Änderungen,
+  - Arbeiten von **„Validieren“** und **„Technische Tests ausführen“** auf dem aktuellen Editorzustand.
+- Soweit stabil automatisierbar, auch zentrale Meldungs- und Validierungsflüsse mit absichern.
+- Sicherstellen, dass die Tests den echten V2.0-Kernumfang prüfen und keine späteren GUI-Ausbaustufen vorwegnehmen.
+
+### Explizit nicht Teil
+- DB-/Historienansicht
+- manueller Verarbeitungslauf
+- Release-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- die zentralen V2.0-GUI-Pfade automatisiert abgesichert sind,
+- GUI-Start, Fallback-Verhalten und Schutzdialoge regressionssicher geprüft werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 Build-, Packaging- und Artefaktdokumentation für das gemeinsame V2.0-JAR vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Das gemeinsame ausführbare JAR für GUI und headless ist nachvollziehbar beschrieben und sein Build-/Packaging-Verhalten ist für die Übergabe ausreichend dokumentiert.
+
+### Muss umgesetzt werden
+- Dokumentation für Build und Packaging des gemeinsamen V2.0-JAR ergänzen oder schärfen.
+- Mindestens folgende Punkte nachvollziehbar beschreiben:
+  - gemeinsames ausführbares JAR,
+  - integrierte JavaFX-Laufzeit im GUI-Fall,
+  - keine EXE und kein Installer in V2.0,
+  - headless Start ohne separate JavaFX-Installation,
+  - relevante Build-Kommandos,
+  - Artefakterzeugung und Startbeispiele.
+- Prüfen, ob bestehende Packaging-/Build-Hinweise oder Konfigurationsbeispiele widersprüchlich oder veraltet sind, und diese gezielt bereinigen.
+- Nur dann produktiven Build-Code anfassen, wenn für eine korrekte V2.0-Dokumentation ein nachweisbarer Widerspruch zum realen Packaging-Verhalten besteht.
+
+### Explizit nicht Teil
+- neue Distributionsformate
+- EXE oder Installer
+- Release-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- Build- und Packaging-Verhalten des gemeinsamen JAR nachvollziehbar dokumentiert ist,
+- veraltete oder widersprüchliche Angaben bereinigt sind,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-006 Integrierte Gesamtprüfung des V2.0-Stands und belastbare Befundliste erstellen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Der V2.0-Gesamtstand wird ganzheitlich geprüft, und es entsteht eine belastbare Befundliste, aus der ausschließlich reale Release-Blocker ableitbar sind.
+
+### Muss umgesetzt werden
+- Den vollständigen V2.0-Projektstand ganzheitlich gegen die bestehenden Spezifikationen, den V1.1-Ist-Stand und `meilensteine-v2_0.md` prüfen.
+- Tatsächlich ausführen und auswerten:
+  - vollständigen Maven-Reactor-Build,
+  - relevante Test-Suiten,
+  - headless Smoke-/Regressionstests,
+  - GUI-nahe Smoke-/Interaktionstests, soweit im Projekt vorhanden,
+  - Prüfung der Konfigurations- und Dokumentationsbeispiele.
+- Die Ergebnisse in einer im Repository verbleibenden **Befundliste** dokumentieren.
+- Befunde klar klassifizieren, insbesondere in:
+  - Release-Blocker,
+  - nicht blockierende Restpunkte,
+  - bewusst außerhalb von V2.0 liegende Themen.
+- Sicherstellen, dass nur **konkret nachgewiesene** Release-Blocker für das Folge-Arbeitspaket in Betracht kommen.
+
+### Explizit nicht Teil
+- Behebung der gefundenen Blocker
+- neue Produktfunktionalität
+- finale Freigabedokumentation
+
+### Fertig wenn
+- die integrierte Gesamtprüfung real durchgeführt und dokumentiert wurde,
+- eine belastbare Befundliste im Repository vorliegt,
+- Release-Blocker klar und eng eingegrenzt sind,
+- der Stand weiterhin fehlerfrei buildbar bleibt.
+
+---
+
+## AP-007 Nachgewiesene V2.0-Release-Blocker gezielt beheben
+
+### Voraussetzung
+AP-006 ist abgeschlossen.
+
+### Ziel
+Die im vorherigen Arbeitspaket konkret dokumentierten Release-Blocker werden gezielt und ohne Scope-Ausweitung beseitigt.
+
+### Muss umgesetzt werden
+- Ausschließlich die in der Befundliste aus AP-006 dokumentierten **Release-Blocker** beheben.
+- Änderungen strikt auf die tatsächlich nachgewiesenen Blocker begrenzen.
+- Betroffene Tests, Dokumentation und Konfigurationsbeispiele mitziehen, soweit dies zur sauberen Behebung erforderlich ist.
+- Sicherstellen, dass durch die Behebung keine Themen späterer Ausbaustufen still vorweggenommen werden.
+- Den relevanten Build-/Testumfang erneut ausführen und grün bekommen.
+
+### Explizit nicht Teil
+- Behebung nicht blockierender Restpunkte
+- neue Features
+- finaler Freigabenachweis
+
+### Fertig wenn
+- die dokumentierten Release-Blocker gezielt behoben sind,
+- die relevanten Builds und Tests erneut erfolgreich laufen,
+- keine Scope-Ausweitung auf spätere Ausbaustufen stattgefunden hat,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## AP-008 Finale V2.0-Gesamtprüfung und Freigabedokumentation erstellen
+
+### Voraussetzung
+AP-007 ist abgeschlossen.
+
+### Ziel
+Der V2.0-Gesamtstand wird abschließend geprüft und als freigabefähiger Stand nachvollziehbar dokumentiert.
+
+### Muss umgesetzt werden
+- Die integrierte Gesamtprüfung nach den Blockerbehebungen erneut durchführen.
+- Tatsächlich ausführen und bewerten:
+  - vollständigen Maven-Reactor-Build,
+  - maßgebliche Test-Suiten,
+  - headless Smoke-/Regressionstests,
+  - GUI-nahe Smoke-/Interaktionstests,
+  - Konfigurations- und Dokumentationsbeispielprüfung.
+- Eine im Repository verbleibende **Freigabedokumentation** erstellen, die mindestens festhält:
+  - geprüften Stand,
+  - ausgeführte Prüfungen,
+  - Build-/Test-Ergebnisse,
+  - offene nicht blockierende Restpunkte,
+  - klare Freigabeaussage für V2.0.
+- Sicherstellen, dass die Freigabedokumentation keine Aussagen trifft, die nicht durch reale Prüfungen gedeckt sind.
+
+### Explizit nicht Teil
+- neue Produktfunktionalität
+- weitere Qualitätskampagnen jenseits des V2.0-Abschlusses
+- spätere Ausbaustufen V2.1+
+
+### Fertig wenn
+- der V2.0-Gesamtstand erneut vollständig geprüft wurde,
+- eine belastbare Freigabedokumentation im Repository vorliegt,
+- der V2.0-Stand als freigabefähig nachvollziehbar beschrieben ist,
+- ein fehlerfreier, übergabefähiger Abschlussstand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M13 – V2.0-Abschluss, Dokumentation und Qualitätsnachweis** zugeschnitten. Sie decken den vollständigen Zielumfang dieses Abschlussmeilensteins ab, ohne spätere Ausbaustufen vorwegzunehmen.