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.