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

docs/workpackages/M10 - Arbeitspakete.md

@@ -0,0 +1,401 @@
+# M10 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M10 – GUI-Konfigurationseditor, Dateihandling und Benutzerführung**.
+
+Die Meilensteine **M1** bis **M9** 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 GUI-Modul, Bootstrap, Konfigurationszugriff, Build und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, die V2.0-Meilensteine oder dieses Dokument gedeckt sind.
+- Kein Vorgriff auf **M11+**.
+- Kein Umbau bestehender M1–M9-Strukturen ohne direkten M10-Bezug.
+- Die GUI arbeitet weiterhin ausschließlich auf der bestehenden **`.properties`-Konfigurationswelt**.
+- Die GUI darf in M10 **Dateien lesen, schreiben und normalisiert speichern**, aber noch **keine** sofortige Validierung, keinen Modellabruf und keine technischen Gesamttests ausführen.
+- Das Ergebnis jedes Arbeitspakets muss für Benutzer bereits nachvollziehbar und bedienbar sein, auch wenn der volle V2.0-Komfort erst in M11/M12 erreicht wird.
+- Neue Typen, View-Modelle, Dateidialoge, Editorzustände und Tests so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind.
+
+## Explizit nicht Bestandteil von M10
+
+- sofortige Validierung beim Öffnen oder während der Eingabe
+- zentraler Meldungsbereich mit Info/Hinweis/Warnung/Fehler
+- feldnahe rote Fehlermeldungen unter Eingabefeldern
+- Provider-ComboBox
+- automatischer Modellabruf
+- Umschaltung zwischen Modell-ComboBox und Modell-Textfeld
+- technische Aktion **„Validieren“**
+- technische Aktion **„Technische Tests ausführen“**
+- Aktion **„Modelle neu laden“**
+- wirtschaftliche Warnschwellen für `max.text.characters`
+- Plausibilitäts-/Performance-Hinweise für `max.pages`
+- automatische Prompt-Erzeugung
+- technische Korrekturhilfen mit Bestätigungsdialog
+- SQLite-/Historienanzeige
+- manueller Verarbeitungslauf aus der GUI
+- EXE
+- Installer
+- neues Konfigurationsformat
+- Änderungen an fachlicher Kernverarbeitung, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten
+
+## Verbindliche M10-Regeln für **alle** Arbeitspakete
+
+### 1. Konfigurationswahrheit
+
+Ab M10 gilt verbindlich:
+
+- Die GUI liest, bearbeitet und schreibt dieselbe **`.properties`-Datei** wie der headless Betrieb.
+- Es wird **kein** neues Konfigurationsformat eingeführt.
+- Kommentare, Reihenfolge und Formatierung dürfen beim Speichern **technisch normalisiert** werden.
+- Die GUI bearbeitet **alle aktuell bekannten Konfigurationswerte** des bestehenden Produkts.
+
+### 2. Startzustand der GUI
+
+Ab M10 gilt verbindlich:
+
+- Beim GUI-Start wird **keine Konfiguration automatisch geladen**, sofern nicht eine gültige Konfigurationsdatei explizit über den Startpfad aus M9 übergeben wurde.
+- Ohne geladene Konfiguration zeigt die GUI einen **deutschen Willkommenstext** mit kurzer Anleitung.
+- Der Benutzer kann von dort aus mindestens **„Neu“** und **„Öffnen“** auslösen.
+
+### 3. Neue Konfiguration
+
+Ab M10 gilt verbindlich:
+
+- **„Neu“** erzeugt eine **vollständige Standardvorlage** mit sinnvollen Default-Werten.
+- Diese Vorlage enthält die **bestehende Mehrprovider-Struktur**.
+- Standardmäßig ist der **alphabetisch erste vorhandene Provider** aktiv.
+- Eine neue, noch nie gespeicherte Konfiguration gilt als eigener Editorzustand und darf bearbeitet werden, ohne sofort auf Platte geschrieben zu werden.
+
+### 4. Dateiverhalten
+
+Ab M10 gilt verbindlich:
+
+- **„Öffnen“** und **„Speichern unter“** filtern auf **`*.properties`**.
+- **„Speichern“** verhält sich bei einer neuen, noch nie gespeicherten Konfiguration wie **„Speichern unter“**.
+- **„Speichern unter“** schlägt standardmäßig denselben Standardpfad vor, den der bestehende headless Betrieb in V1.1 verwendet, also **`config/application.properties`** relativ zum Arbeitsverzeichnis. Dadurch ist die in der GUI gespeicherte Datei ohne weitere Schritte für den nächsten headless Scheduler-Lauf nutzbar.
+- Beim Speichern auf eine bereits existierende Datei erscheint eine klare Rückfrage **„Datei überschreiben?“**.
+- Vor dem Überschreiben einer bestehenden `.properties`-Datei legt die GUI eine `.bak`-Sicherung im selben Schema wie der bestehende V1.1-Migrationspfad an (**`<dateiname>.bak`**, bei Kollision **`.bak.1`**, **`.bak.2`**, …).
+
+### 5. Editorzustand und ungespeicherte Änderungen
+
+Ab M10 gilt verbindlich:
+
+- Ungespeicherte Änderungen werden im **Fenstertitel** und im **Header** sichtbar markiert.
+- Vor **Neu**, **Öffnen** oder **Schließen** erscheint bei ungespeicherten Änderungen ein Dialog mit:
+  - **Speichern**
+  - **Verwerfen**
+  - **Abbrechen**
+- In M10 sind diese Entscheidungen rein editorbezogen; sie lösen noch **keine** Validierungs- oder Testlogik aus.
+
+### 6. GUI-Struktur in M10
+
+M10 liefert bereits den echten Konfigurationseditor, aber noch ohne M11/M12-Komfortlogik.
+
+Daraus folgt:
+
+- Es bleibt bei **genau einem Tab**.
+- Die Oberfläche ist in feste, sichtbare Bereiche gegliedert:
+  1. **Header / Konfigurationsdatei**
+  2. **Pfade**
+  3. **Provider**
+  4. **Verarbeitungslimits**
+  5. **Tests**
+  6. **Meldungen**
+- In M10 dürfen Bereiche **„Tests“** und **„Meldungen“** bereits strukturell sichtbar sein, auch wenn ihre echte Funktionalität erst in M11/M12 vervollständigt wird.
+- Die Oberfläche muss scrollbar und benutzbar bleiben; einklappbare Gruppen oder zusätzliche Tabs sind in M10 nicht Ziel.
+
+### 7. Datei- und Ordnerdialoge
+
+Ab M10 gilt verbindlich:
+
+- Für mindestens folgende Pfadangaben stehen ein Texteingabefeld und ein kleiner nativer Datei-/Ordnerdialog-Button bereit:
+  - Quellordner
+  - Zielordner
+  - SQLite-Datei
+  - Prompt-Datei
+- Die GUI darf dabei Windows-typische Pfadangaben nicht künstlich einschränken.
+- Gemappte Laufwerksbuchstaben dürfen nicht durch GUI-Dateilogik beschädigt oder unbrauchbar gemacht werden.
+
+### 8. API-Key-Feld und bestehende Vorrangregel
+
+Ab M10 gilt verbindlich:
+
+- Die GUI bildet den API-Key pro Provider weiterhin innerhalb der bestehenden `.properties`-Konfigurationswelt ab.
+- Die spätere Bewertung des **effektiven** API-Keys muss die bestehende Vorrangregel respektieren:
+  1. providerspezifische Umgebungsvariable,
+  2. bei **OpenAI-kompatibel** zusätzlich die bestehende Legacy-Umgebungsvariable,
+  3. Property-Wert aus der Datei.
+- Der Editorzustand muss deshalb zwischen bearbeitetem Property-Wert und später anzeigbarer Herkunft des effektiven API-Keys anschlussfähig bleiben.
+- Das API-Key-Feld bleibt bewusst ein normales, unmaskiertes Textfeld.
+- Ein leeres API-Key-Feld darf einen bereits vorhandenen Property-Wert nicht stillschweigend entfernen, solange keine ausdrückliche Löschsemantik eingeführt wurde.
+
+---
+
+## AP-001 Editorzustand, Konfigurationsabbild und Standardvorlage einführen
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M10-Startpunkt.
+
+### Ziel
+Der GUI-Editor erhält ein sauberes internes Zustandsmodell für bestehende und neue Konfigurationen, einschließlich vollständiger Standardvorlage und Dirty-State-Grundlage.
+
+### Muss umgesetzt werden
+- GUI-seitiges Editor-/View-Model für die bearbeitbare Konfiguration einführen.
+- Abbildung aller aktuell bekannten Konfigurationswerte in einen GUI-tauglichen Bearbeitungszustand modellieren.
+- Den Bearbeitungszustand so schneiden, dass für den API-Key je Provider sowohl der editierbare Property-Wert als auch die spätere Herkunft des effektiven Werts gemäß bestehender Vorrangregel anschlussfähig bleiben.
+- Saubere Trennung zwischen:
+  - geladener Dateirepräsentation,
+  - bearbeitbarem Editorzustand,
+  - neu erzeugter Standardvorlage,
+  - Dirty-State/Änderungsstand.
+- Vollständige Standardvorlage für **„Neu“** bereitstellen.
+- Sicherstellen, dass die Standardvorlage die bestehende Mehrprovider-Struktur erhält und mit sinnvollen Defaults startet.
+- Mapping so schneiden, dass spätere M11-/M12-Logik darauf aufsetzen kann, ohne ein neues Konfigurationsmodell zu erfinden.
+- JavaDoc und `package-info` für Verantwortlichkeiten und Grenzen ergänzen.
+
+### Explizit nicht Teil
+- JavaFX-Layout
+- Datei öffnen oder speichern
+- Dirty-State-Anzeige im Fenster
+- Dialoge
+- Validierung oder Tests
+
+### Fertig wenn
+- ein konsistenter GUI-Editorzustand modelliert ist,
+- neue Standardkonfigurationen erzeugt werden können,
+- alle aktuell bekannten Konfigurationswerte im Editorzustand abbildbar sind,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Header, leerer Startzustand und Aktionsgrundgerüst der GUI vervollständigen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die GUI zeigt bei fehlender Konfiguration einen benutzerfreundlichen Startzustand und bietet die zentralen Dateiaktionen in einer stabilen Grundstruktur an.
+
+### Muss umgesetzt werden
+- Header-Bereich mit Anzeige des aktuell verwendeten Konfigurationspfads implementieren.
+- Verhalten ohne geladene Konfiguration umsetzen:
+  - leerer Pfad im Header,
+  - deutscher Willkommenstext,
+  - sichtbare Aktionen für **„Neu“** und **„Öffnen“**.
+- Aktionsgrundgerüst für mindestens diese Bedienhandlungen sichtbar und verdrahtbar anlegen:
+  - **Neu**
+  - **Öffnen**
+  - **Speichern**
+  - **Speichern unter**
+- Sicherstellen, dass die GUI ohne geladene Konfiguration nicht verwirrend einen impliziten Standardentwurf zeigt.
+- Grundstruktur des einen GUI-Tabs mit den festen Bereichen anlegen, soweit für M10 erforderlich.
+- JavaDoc/Kommentare für den GUI-Startzustand ergänzen.
+
+### Explizit nicht Teil
+- tatsächliches Dateiladen
+- tatsächliches Speichern
+- unsaved-changes-Dialoge
+- provider-spezifische Komfortlogik aus M11
+- technische Tests oder Meldungslogik
+
+### Fertig wenn
+- die GUI ohne geladene Konfiguration benutzerfreundlich startet,
+- Header und Grundaktionen sichtbar vorhanden sind,
+- der Benutzer klar zwischen **„Neu“** und **„Öffnen“** geführt wird,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 Öffnen bestehender `.properties`-Dateien und Übernahme in den Editorzustand umsetzen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Bestehende Konfigurationsdateien können über den GUI-Dateidialog geladen und in den Editorzustand übernommen werden.
+
+### Muss umgesetzt werden
+- Native Dateiauswahl für **„Öffnen“** mit Filter auf **`*.properties`** implementieren.
+- Bestehende `.properties`-Datei technisch laden und in den Editorzustand überführen.
+- Beim Öffnen einer erkannten Legacy-Konfiguration aus Vor-V1.1 die bestehende Migrationslogik des headless Pfads wiederverwenden; die GUI führt keinen zweiten, separaten Migrationspfad ein.
+- Sicherstellen, dass die Dateiübernahme mit dem aus M9 bereits vorhandenen GUI-Start über gültiges `--config <pfad>` zusammenarbeiten kann.
+- Header-Anzeige nach erfolgreichem Laden auf den vollständigen Pfad aktualisieren.
+- Fehlersituationen beim Laden kontrolliert behandeln, soweit für M10 nötig.
+- Noch nicht implementierte Validierungs- oder Testlogik aus M11/M12 nicht vorwegnehmen.
+- JavaDoc für Dateiladeverantwortung und Editorübernahme ergänzen.
+
+### Explizit nicht Teil
+- Speichern oder Speichern unter
+- Dirty-State-Dialoge
+- sofortige Validierung
+- Modellabruf
+- technische Tests
+
+### Fertig wenn
+- bestehende `.properties`-Dateien per GUI geöffnet werden können,
+- ihr Inhalt im Editorzustand sichtbar und bearbeitbar ist,
+- die Header-Anzeige den geladenen Pfad korrekt darstellt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Speichern, Speichern unter und normalisierte `.properties`-Schreiblogik implementieren
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Der Editor kann neue und bestehende Konfigurationen zuverlässig, normalisiert und benutzerfreundlich als `.properties` schreiben.
+
+### Muss umgesetzt werden
+- Schreiblogik für bestehende und neue Konfigurationen implementieren.
+- **„Speichern“** für bereits bekannte Dateipfade umsetzen.
+- **„Speichern“** für neue, noch nie gespeicherte Konfigurationen wie **„Speichern unter“** behandeln.
+- **„Speichern unter“** mit Vorschlag desselben Standardpfads implementieren, den der bestehende headless Betrieb in V1.1 verwendet, also **`config/application.properties`** relativ zum Arbeitsverzeichnis.
+- Dialogfilter auf **`*.properties`** anwenden.
+- Rückfrage **„Datei überschreiben?“** bei existierender Zieldatei umsetzen.
+- Vor dem Überschreiben einer bestehenden `.properties`-Datei eine `.bak`-Sicherung im selben Schema wie der bestehende V1.1-Migrationspfad anlegen (**`<dateiname>.bak`**, bei Kollision **`.bak.1`**, **`.bak.2`**, …); diese Sicherung ist verbindlicher Teil der Speicherlogik.
+- Speicherung als normalisierte `.properties` sicherstellen.
+- Für API-Key-Felder sicherstellen, dass ein leeres GUI-Feld einen bereits vorhandenen Property-Wert nicht stillschweigend entfernt; stattdessen muss ein kontrolliertes Ergebnis für die spätere Warnanzeige aus M11/M12 bereitstehen.
+- Header-Pfad nach erfolgreichem Erstspeichern bzw. Speichern unter korrekt fortschreiben.
+- JavaDoc für Dateischreibverhalten, API-Key-Erhaltung und Normalisierung ergänzen.
+
+### Explizit nicht Teil
+- Dirty-State-Anzeige im Fenstertitel
+- Dialogverhalten bei ungespeicherten Änderungen vor Neu/Öffnen/Schließen
+- Validierung oder technische Tests
+- automatische Prompt-Erzeugung
+
+### Fertig wenn
+- neue und bestehende Konfigurationen zuverlässig gespeichert werden können,
+- Speichern/Speichern unter benutzerfreundlich und nachvollziehbar arbeiten,
+- normalisierte `.properties`-Dateien geschrieben werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 Dirty-State, optische Kennzeichnung und Schutzdialoge bei ungespeicherten Änderungen umsetzen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Ungespeicherte Änderungen werden sichtbar gemacht und vor verlustbehafteten Bedienhandlungen kontrolliert abgefragt.
+
+### Muss umgesetzt werden
+- Dirty-State aus dem Editorzustand in die GUI übertragen.
+- Optische Kennzeichnung ungespeicherter Änderungen an **beiden** Stellen umsetzen:
+  - Fenstertitel
+  - Header neben dem Konfigurationspfad
+- Schutzdialog vor **Neu**, **Öffnen** und **Schließen** bei ungespeicherten Änderungen implementieren.
+- Dialogoptionen exakt wie definiert bereitstellen:
+  - **Speichern**
+  - **Verwerfen**
+  - **Abbrechen**
+- Sicherstellen, dass der Dialogfluss mit neuer Konfiguration, bestehender Konfiguration und erstmaligem Speichern konsistent zusammenwirkt.
+- Noch keine M11/M12-Validierungs- oder Testlogik mit diesem Dialog vermischen.
+- JavaDoc für Dirty-State- und Schutzdialog-Verhalten ergänzen.
+
+### Explizit nicht Teil
+- sofortige Validierung
+- technischer Gesamttest
+- Meldungsbereichslogik
+- provider-spezifische Komfortlogik
+
+### Fertig wenn
+- ungespeicherte Änderungen sichtbar markiert werden,
+- verlustbehaftete Bedienhandlungen kontrolliert abgefragt werden,
+- die Dialogoptionen konsistent funktionieren,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-006 Vollständige Editoroberfläche mit allen Konfigurationswerten und nativen Datei-/Ordnerdialogen vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Die GUI bildet alle aktuell bekannten Konfigurationswerte sichtbar und bearbeitbar ab, einschließlich der relevanten Pfad-Picker.
+
+### Muss umgesetzt werden
+- Die feste Oberflächenstruktur für den einen Tab vollständig ausbauen.
+- Alle aktuell bekannten Konfigurationswerte in geeigneten Eingabefeldern abbilden.
+- Für mindestens diese Pfade jeweils Texteingabefeld plus kleinen nativen Datei-/Ordnerdialog-Button umsetzen:
+  - Quellordner
+  - Zielordner
+  - SQLite-Datei
+  - Prompt-Datei
+- Sicherstellen, dass Eingabefelder und Dialoge auf denselben Editorzustand arbeiten.
+- Windows-typische Pfadangaben und gemappte Laufwerksbuchstaben technisch unbeeinträchtigt übernehmen.
+- Provider-bezogene Felder so einhängen, dass spätere M11-Komfortlogik darauf aufsetzen kann, ohne das Grundlayout neu zu erfinden.
+- Noch keine sofortige Validierung, keinen Modellabruf und keine technische Testfunktion aktivieren.
+- JavaDoc für GUI-Bereichsverantwortung und Pfadbedienung ergänzen.
+
+### Explizit nicht Teil
+- Provider-ComboBox
+- Modelllistenlogik
+- feldnahe Fehlermeldungen
+- zentraler Meldungsbereich mit echter Semantik
+- technische Tests oder Korrekturhilfen
+
+### Fertig wenn
+- alle aktuell bekannten Konfigurationswerte im GUI-Editor sichtbar und bearbeitbar sind,
+- die relevanten Datei-/Ordnerdialoge funktional vorhanden sind,
+- Windows-Pfade und gemappte Laufwerke nicht künstlich beschädigt werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-007 M10-Integration, GUI-Dateifluss über `--config` und benutzernahe Regressionstests absichern
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der vollständige M10-Datei- und Editorfluss wird integriert abgesichert, einschließlich des Zusammenspiels mit dem in M9 eingeführten Startpfad.
+
+### Muss umgesetzt werden
+- Sicherstellen, dass ein gültiger übergebener GUI-Konfigurationspfad aus M9 direkt als Editorinhalt geladen werden kann.
+- Sicherstellen, dass der GUI-Start ohne Konfiguration weiterhin im definierten Willkommenstext-Zustand landet.
+- Regressionstests für die wesentlichen M10-Bedienflüsse ergänzen, insbesondere für:
+  - GUI-Start ohne geladene Konfiguration,
+  - **Neu** mit Standardvorlage,
+  - **Öffnen** bestehender `.properties`,
+  - Wiederverwendung der bestehenden headless Migrationslogik beim Öffnen einer Legacy-Konfiguration,
+  - **Speichern** und **Speichern unter**,
+  - Überschreibdialog,
+  - `.bak`-Sicherung beim Überschreiben einer bestehenden `.properties`-Datei,
+  - Dirty-State-Markierung,
+  - Schutzdialog bei offenen Änderungen,
+  - gültigen GUI-Start mit `--config`.
+- Tests so schneiden, dass sie M10 zuverlässig absichern, ohne M11/M12-Funktionalität künstlich zu simulieren.
+- Abschließende Konsistenzprüfung des M10-Stands gegen den definierten Scope durchführen.
+
+### Explizit nicht Teil
+- sofortige Validierung beim Öffnen
+- technischer Gesamttest
+- Modellabruf
+- Korrekturhilfen
+- DB-/Historienfunktionalität
+
+### Fertig wenn
+- der vollständige M10-Datei- und Editorfluss integriert funktioniert,
+- die wesentlichen Bedienpfade automatisiert abgesichert sind,
+- der Stand buildbar, testbar und übergabefähig ist,
+- noch keine Funktionalität aus M11+ vorweggenommen wurde.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M10 – GUI-Konfigurationseditor, Dateihandling und Benutzerführung** zugeschnitten. Sie liefern einen echten, benutzerfreundlichen Konfigurationseditor auf Basis der bestehenden `.properties`-Wahrheit, ohne bereits Provider-Komfortlogik, sofortige Validierung oder technische Test-/Korrekturfunktionen aus **M11/M12** vorwegzunehmen.