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

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