From 22ec512cd7a0d41615864c3e861992cb8a34877a Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Mon, 13 Apr 2026 08:06:34 +0200 Subject: [PATCH] =?UTF-8?q?=C3=9Cberarbeitung=20und=20Freigabe=20aller=20V?= =?UTF-8?q?2.0=20Planungsdokumente?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/workpackages/M10 - Arbeitspakete.md | 14 ++++++++---- docs/workpackages/M11 - Arbeitspakete.md | 10 +++++++- docs/workpackages/M9 - Arbeitspakete.md | 29 ++++++++++++++++++++++-- 3 files changed, 46 insertions(+), 7 deletions(-) diff --git a/docs/workpackages/M10 - Arbeitspakete.md b/docs/workpackages/M10 - Arbeitspakete.md index 5110b89..b218dd3 100644 --- a/docs/workpackages/M10 - Arbeitspakete.md +++ b/docs/workpackages/M10 - Arbeitspakete.md @@ -81,7 +81,7 @@ 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 **`pdf-umbenenner.properties`** vor. +- **„Speichern unter”** schlägt standardmäßig **`config/application.properties`** relativ zum Arbeitsverzeichnis vor, so ist die 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?“**. ### 5. Editorzustand und ungespeicherte Änderungen @@ -225,7 +225,12 @@ Bestehende Konfigurationsdateien können über den GUI-Dateidialog geladen und i ### Muss umgesetzt werden - Native Dateiauswahl für **„Öffnen“** mit Filter auf **`*.properties`** implementieren. - Bestehende `.properties`-Datei technisch laden und in den Editorzustand überführen. -- Die durchgeführte Legacy-Migration im Editorzustand als ausstehende Migrationsmeldung festhalten, sodass der in M11 eingeführte zentrale Meldungsbereich diese Meldung beim Anbinden automatisch anzeigen kann. In M10 selbst erscheint noch kein sichtbarer Migrationshinweis. +- **Legacy-Migration beim Öffnen**: Wenn die geöffnete Datei in der Vor-V1.1-Legacy-Form (flache `api.*`-Schlüssel) vorliegt, muss die GUI dieselbe Migrationslogik wie der headless Pfad anwenden: + 1. `.bak`-Sicherung der Originaldatei anlegen (`.bak`, bei Kollision `.bak.1`, `.bak.2`, …), + 2. Inhalt ins neue Mehrprovider-Schema überführen (Legacy-Werte → `openai-compatible`, `ai.provider.active=openai-compatible`), + 3. migrierte Datei speichern, + 4. die durchgeführte Migration im Editorzustand als ausstehende Migrationsmeldung festhalten, sodass der in M11 eingeführte zentrale Meldungsbereich diese Meldung später sichtbar anzeigen kann. +- In M10 selbst erscheint noch kein sichtbarer Migrationshinweis; dieser wird erst in M11 durch den zentralen Meldungsbereich angezeigt. - Sicherstellen, dass die Dateiübernahme mit dem aus M9 bereits vorhandenen GUI-Start über gültiges `--config ` zusammenarbeiten kann. - Header-Anzeige nach erfolgreichem Laden auf den vollständigen Pfad aktualisieren. - Fehlersituationen beim Laden kontrolliert behandeln, soweit für M10 nötig. @@ -259,9 +264,10 @@ Der Editor kann neue und bestehende Konfigurationen zuverlässig, normalisiert u - 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 **`pdf-umbenenner.properties`** implementieren. +- **„Speichern unter”** mit Vorschlag **`config/application.properties`** relativ zum Arbeitsverzeichnis implementieren. - Dialogfilter auf **`*.properties`** anwenden. -- Rückfrage **„Datei überschreiben?“** bei existierender Zieldatei umsetzen. +- Rückfrage **„Datei überschreiben?”** bei existierender Zieldatei umsetzen. +- Vor dem Überschreiben einer bestehenden `.properties`-Datei eine **`.bak`-Sicherung** im selben Schema wie der V1.1-Migrationspfad anlegen (`.bak`, bei Kollision `.bak.1`, `.bak.2`, …). Bestehende Sicherungen werden nicht überschrieben. - 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. diff --git a/docs/workpackages/M11 - Arbeitspakete.md b/docs/workpackages/M11 - Arbeitspakete.md index 208923f..4e8203c 100644 --- a/docs/workpackages/M11 - Arbeitspakete.md +++ b/docs/workpackages/M11 - Arbeitspakete.md @@ -121,7 +121,15 @@ Ab M11 gilt verbindlich: - **`max.pages`** wird **nicht** als direkte Kostenwarnung behandelt, sondern höchstens als **Plausibilitäts-/Performance-Hinweis**. - Weitere riskante, aber formal zulässige Konfigurationen dürfen als Warnung oder Hinweis sichtbar gemacht werden, soweit sie aus dem vorhandenen Zielbild klar ableitbar sind. -### 7. Grenzen von M11 +### 7. API-Key-Herkunft und Env-Var-Schutz + +Ab M11 gilt verbindlich: + +- Die GUI macht die Herkunft des effektiven API-Keys für den Benutzer **sichtbar**, insbesondere wenn eine providerspezifische Umgebungsvariable aktuell Vorrang vor dem Property-Wert hat. +- Das API-Key-Eingabefeld ist ein **normales, unmaskiertes Textfeld** (pragmatische V2.0-Entscheidung, keine Sicherheitsbehauptung). +- Ein leeres API-Key-Feld darf einen bereits vorhandenen Property-Wert **nicht stillschweigend löschen**, wenn keine Umgebungsvariable greift. Stattdessen bleibt der Property-Wert erhalten und eine **deutliche Warnung** wird angezeigt. + +### 8. Grenzen von M11 M11 liefert eine sofort reagierende, benutzerfreundliche Provider- und Validierungsoberfläche, aber noch **keine** vollständige technische Gesamtprüfung des Systems. diff --git a/docs/workpackages/M9 - Arbeitspakete.md b/docs/workpackages/M9 - Arbeitspakete.md index 18dce5b..86aadac 100644 --- a/docs/workpackages/M9 - Arbeitspakete.md +++ b/docs/workpackages/M9 - Arbeitspakete.md @@ -110,7 +110,32 @@ Daraus folgt: - Diese Shell dient nur dem Nachweis des GUI-Startpfads. - Ein echter Konfigurationseditor ist ausdrücklich erst Gegenstand von **M10**. -### 9. GUI-Teststrategie +### 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: @@ -119,7 +144,7 @@ Ab M9 gilt verbindlich für alle V2.0-Meilensteine: - 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. -### 10. JavaDoc-Standard für V2.0 +### 11. JavaDoc-Standard für V2.0 Ab M9 gilt verbindlich für alle V2.0-Meilensteine: