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

# M12 - Arbeitspakete

## Geltungsbereich

Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M12 – Technische Tests, Korrekturhilfen und Windows-/Netzlaufwerksfähigkeit**.

Die Meilensteine **M1** bis **M11** 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 Domain, Application, Adapter, Bootstrap, GUI 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 **M13+**.
- Kein Umbau bestehender M1–M11-Strukturen ohne direkten M12-Bezug.
- **„Validieren“** und **„Technische Tests ausführen“** arbeiten mit dem **aktuellen GUI-Zustand**, nicht mit dem zuletzt gespeicherten Dateistand.
- Es erfolgt **kein implizites Speichern**.
- Der Gesamttest läuft **immer vollständig** durch und bricht **nicht** beim ersten Fehler ab.
- Schreibende Korrekturen dürfen nur nach **einem gesammelten Bestätigungsdialog** erfolgen.
- Netzlaufwerke über **gemappte Laufwerksbuchstaben** sind im Windows-Kontext ausdrücklich zu unterstützen.
- Änderungen klein, fokussiert und architekturtreu halten.
- Neue Testmodelle, Prüfergebnisse, Korrekturpläne, Ports, Services und GUI-Zustände so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind.

## Explizit nicht Bestandteil von M12

- DB-/Historienanzeige
- manueller Verarbeitungslauf aus der GUI
- EXE
- Installer
- neues Konfigurationsformat
- neue Provider über Claude und OpenAI-kompatibel hinaus
- Cost-Tracking oder Token-/Preisberechnung
- mehrseitige GUI oder weitere Tabs
- Änderungen an fachlicher Kernverarbeitung, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten
- plattformübergreifende GUI-Unterstützung außerhalb des definierten Windows-Ziels

## Verbindliche M12-Regeln für **alle** Arbeitspakete

### 1. Unterschied zwischen „automatischer Validierung“, Aktion „Validieren“ und „Technische Tests ausführen“

Ab M12 gilt verbindlich:

- **Automatische Validierung** bleibt die in M11 definierte Hintergrundprüfung beim Öffnen und während der Bearbeitung.
- **Aktion „Validieren“** ist die explizite, **nicht schreibende, lokale Gesamtprüfung** des aktuellen Editorzustands.
- **Aktion „Validieren“** arbeitet ohne implizites Speichern und ohne schreibende Korrekturen.
- **„Technische Tests ausführen“** ist ein **vollständiger Gesamttest** des aktuellen Editorzustands.
- Der Gesamttest darf zusätzlich zu lokalen Prüfungen auch technische Prüfungen gegen Dateisystem und Provider durchführen.
- Der Gesamttest darf **korrigierende Maßnahmen** vorschlagen, aber erst nach Bestätigung durchführen.

### 2. Vollständiger Gesamttest ohne Frühabbruch

Ab M12 gilt verbindlich:

- Der Gesamttest führt **alle definierten Prüfpunkte** aus.
- Ein einzelner Fehler darf **nicht** dazu führen, dass spätere Prüfpunkte ausgelassen werden.
- Alle Befunde werden gesammelt im zentralen Meldungsbereich ausgegeben.
- Die Ausführung basiert auf dem **aktuellen GUI-Zustand**, auch wenn dieser noch ungespeichert ist.

### 3. Definierte Prüfpunkte des Gesamttests

Ab M12 gilt verbindlich, dass der Gesamttest mindestens folgende Prüfpunkte unterstützt:

- Konfiguration grundsätzlich validierbar
- Provider-Konfiguration prüfbar
- Base-URL/Endpoint technisch erreichbar
- API-Key vorhanden, auch wenn der effektive Wert ausschließlich über eine passende Umgebungsvariable bereitgestellt wird
- API-Key technisch akzeptiert
- Modellliste abrufbar
- ausgewähltes Modell plausibel
- Prompt-Datei vorhanden und lesbar
- Quellordner vorhanden und lesbar
- Zielordner vorhanden oder anlegbar sowie schreibbar
- SQLite-Datei bzw. SQLite-Pfad technisch nutzbar

### 4. Schreibende Korrekturhilfen

Ab M12 gilt verbindlich:

- Schreibende Korrekturen werden **nicht still** durchgeführt.
- Vor schreibenden Korrekturen wird **ein gesammelter Bestätigungsdialog** angezeigt.
- Nur **sichere technische Korrekturen** dürfen angeboten werden.
- Nicht automatisch korrigierbar bleiben insbesondere:
  - falscher API-Key,
  - unerreichbare Base-URL,
  - nicht verfügbare Modellliste,
  - fachlich unplausible, aber formal zulässige Werte.

### 5. Automatische Prompt-Erzeugung

Ab M12 gilt verbindlich:

- Wenn die konfigurierte Prompt-Datei fehlt, darf eine **sinnvolle Standard-Prompt-Datei** automatisch erzeugt werden.
- Diese Standard-Prompt-Datei ist **deutschsprachig**.
- Sie liegt standardmäßig **im selben Ordner wie die `.properties`-Datei**.
- Die Erzeugung ist eine **schreibende Korrektur** und unterliegt dem gesammelten Bestätigungsdialog.

### 6. Windows- und Netzlaufwerksfähigkeit

Ab M12 gilt verbindlich:

- Die GUI und ihre Prüflogik unterstützen ausdrücklich **gemappte Laufwerksbuchstaben** wie `S:\` oder `H:\`.
- Solche Pfade dürfen **nicht** allein deshalb abgelehnt oder umgedeutet werden, weil dahinter technisch ein UNC-Pfad stehen könnte.
- Maßgeblich ist, dass Windows den Pfad als gültigen Pfad bereitstellt.
- Diese Regel gilt mindestens für:
  - Quellordner,
  - Zielordner,
  - SQLite-Datei,
  - Prompt-Datei.

### 7. Grenzen von M12

M12 liefert die vollständige technische Prüf- und Korrekturunterstützung der V2.0-GUI, aber noch **nicht** den V2.0-Abschluss mit finaler Dokumentation und Gesamtqualitätsnachweis.

---

## AP-001 Prüf- und Korrektur-Kernobjekte, Ergebnissemantik und Port-Verträge präzisieren

### Voraussetzung
Keine. Dieses Arbeitspaket ist der M12-Startpunkt.

### Ziel
Die M12-relevanten Prüf-, Korrektur- und Dialogmodelle werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.

### Muss umgesetzt werden
- Neue M12-relevante Typen bzw. GUI-/Application-nahe Modelle anlegen, insbesondere für:
  - explizite Validierungsanforderung,
  - Gesamttestanforderung,
  - Prüfpunktergebnis,
  - Korrekturvorschlag,
  - gesammelten Korrekturplan,
  - Bestätigungsdialog-Inhalt,
  - schreibenden vs. nicht schreibenden Prüfschritt,
  - Ergebnis eines vollständigen Gesamttests.
- Verträge so schneiden, dass spätere Arbeitspakete unterscheiden können zwischen:
  - lokalem Validierungsbefund,
  - technischem Prüfbefund,
  - korrigierbarem Befund,
  - nicht korrigierbarem Befund,
  - bestätigtem Korrekturplan,
  - abgelehntem Korrekturplan.
- Outbound-Ports bzw. Application-Verträge definieren oder schärfen für:
  - Provider-nahe technische Tests,
  - Dateisystem-/Pfadtests,
  - schreibende Korrekturhilfen,
  - Prompt-Datei-Erzeugung.
- Sicherstellen, dass Domain und Application frei von JavaFX-, HTTP-, NIO- und JDBC-Bibliothekstypen bleiben.
- JavaDoc und `package-info` für Verantwortlichkeiten und Grenzen ergänzen.

### Explizit nicht Teil
- konkrete GUI-Buttons
- konkrete Prüflogik
- konkrete Korrekturen
- Bootstrap-Verdrahtung
- Gesamttest-Orchestrierung

### Fertig wenn
- die M12-relevanten Typen und Verträge vorhanden sind,
- Validieren, Gesamttest und Korrekturplan klar unterscheidbar modelliert sind,
- Domain und Application frei von Infrastrukturtypen bleiben,
- der Build weiterhin fehlerfrei ist.

---

## AP-002 Aktion „Validieren“ als explizite, nicht schreibende Gesamtprüfung des Editorzustands umsetzen

### Voraussetzung
AP-001 ist abgeschlossen.

### Ziel
Die GUI bietet eine explizite Validierungsaktion, die den aktuellen Editorzustand lokal und vollständig prüft, ohne etwas zu speichern oder zu verändern.

### Muss umgesetzt werden
- Die Aktion **„Validieren“** funktionsfähig anbinden.
- Sicherstellen, dass die Aktion mit dem **aktuellen GUI-Zustand** arbeitet, nicht mit dem zuletzt gespeicherten Dateistand.
- Keine implizite Speicherung auslösen.
- Keine schreibenden Korrekturen durchführen.
- Alle lokalen Befunde gesammelt erzeugen und dem vorhandenen Meldungsmodell zuführen.
- Relevante feldnahe Fehlermeldungen ergänzen oder schärfen.
- Eindeutige deutsche Meldungen für Fehler, Warnungen, Hinweise und Infos verwenden.
- Ausführung und Ergebnis der Aktion **„Validieren“** werden im bestehenden Log4j2-Log nachvollziehbar protokolliert.
- JavaDoc/Kommentare für die Abgrenzung zur M12-Gesamttestaktion ergänzen.

### Explizit nicht Teil
- Provider-nahe Remote-Tests
- schreibende Korrekturen
- Bestätigungsdialog für Korrekturmaßnahmen
- Prompt-Datei-Erzeugung

### Fertig wenn
- **„Validieren“** den aktuellen Editorzustand explizit und nicht schreibend prüfen kann,
- keine implizite Speicherung stattfindet,
- die Befunde verständlich und vollständig angezeigt werden,
- der Build weiterhin fehlerfrei ist.

---

## AP-003 Provider-nahe technische Prüflogik für Endpoint, API-Key, Modellliste und Modellplausibilität umsetzen

### Voraussetzung
AP-001 und AP-002 sind abgeschlossen.

### Ziel
Die für V2.0 geforderten providerbezogenen technischen Prüfpunkte können kontrolliert und providerabhängig ausgeführt werden.

### Muss umgesetzt werden
- Die technische Prüflogik für mindestens folgende providerbezogene Prüfpunkte implementieren:
  - Base-URL/Endpoint erreichbar,
  - API-Key vorhanden,
  - API-Key technisch akzeptiert,
  - Modellliste abrufbar,
  - ausgewähltes Modell plausibel.
- Für den Prüfpunkt **„Modellliste abrufbar“** ausdrücklich denselben Outbound-Port und denselben Adapter verwenden, die bereits in M11 für den Modellabruf eingeführt wurden; der Prüfpunkt ist ein zusätzlicher Aufruf, keine zweite Implementierung.
- Die Prüflogik für Claude und OpenAI-kompatibel sauber kapseln.
- Beim Prüfpunkt **„API-Key vorhanden“** die bestehende Vorrangregel respektieren, sodass reine Umgebungsvariablen-Setups nicht fälschlich als fehlender API-Key bewertet werden.
- Sicherstellen, dass providerbezogene technische Fehler verständlich in das bestehende Meldungsmodell überführt werden.
- Sichere Abgrenzung zwischen:
  - fehlender Voraussetzung,
  - technischer Unerreichbarkeit,
  - Authentifizierungsproblem,
  - nicht verfügbarer Modellliste,
  - unplausibler Modellauswahl.
- Provider-nahe technische Prüfungen und Dateisystem-/SQLite-Prüfungen laufen asynchron; die Ergebnisrückführung in die GUI erfolgt über den JavaFX Application Thread.
- Ausführung und Ergebnis der providernahen technischen Prüfpunkte werden im bestehenden Log4j2-Log nachvollziehbar protokolliert.
- Keine impliziten Korrekturen durchführen.
- JavaDoc/Kommentare für technische Prüfpunkte und Nicht-Ziele ergänzen.

### Explizit nicht Teil
- schreibende Korrekturen
- Pfad-/Dateisystemtests
- Gesamttest-Orchestrierung
- Prompt-Datei-Erzeugung

### Fertig wenn
- alle providerbezogenen technischen Prüfpunkte separat ausführbar und auswertbar sind,
- Befunde verständlich im vorhandenen Meldungsmodell ankommen,
- der Build weiterhin fehlerfrei ist.

---

## AP-004 Windows-Pfadprüfung und ausdrückliche Unterstützung gemappter Laufwerke umsetzen

### Voraussetzung
AP-001 und AP-002 sind abgeschlossen.

### Ziel
Die GUI und ihre Prüflogik behandeln Windows-Pfade einschließlich gemappter Laufwerksbuchstaben korrekt und benutzerfreundlich.

### Muss umgesetzt werden
- Pfadprüfungen für folgende Konfigurationswerte vervollständigen:
  - Quellordner,
  - Zielordner,
  - SQLite-Datei,
  - Prompt-Datei.
- Gemappte Laufwerksbuchstaben wie `S:\` oder `H:\` im Windows-Kontext ausdrücklich akzeptieren.
- Sicherstellen, dass solche Pfade nicht allein wegen möglicher UNC-Backings abgelehnt oder umgedeutet werden.
- Lokale Validierungs- und Testbefunde für Pfadprobleme sauber unterscheiden, insbesondere:
  - fehlt,
  - nicht lesbar,
  - nicht schreibbar,
  - ungültig,
  - anlegbar.
- JavaDoc/Kommentare für Windows-/Netzlaufwerksfähigkeit und technische Grenzen ergänzen.

### Explizit nicht Teil
- schreibende Erstellung fehlender Ressourcen
- Prompt-Datei-Erzeugung
- Gesamttest-Orchestrierung
- Provider-nahe Remote-Tests

### Fertig wenn
- Windows-Pfade korrekt validiert werden,
- gemappte Laufwerke als gültige Pfade akzeptiert werden,
- der Build weiterhin fehlerfrei ist.

---

## AP-005 Aktion „Technische Tests ausführen“ als vollständigen Gesamttest ohne Frühabbruch umsetzen

### Voraussetzung
AP-001 bis AP-004 sind abgeschlossen.

### Ziel
Die GUI kann einen vollständigen technischen Gesamttest des aktuellen Editorzustands ausführen und alle Befunde gesammelt zurückgeben.

### Muss umgesetzt werden
- Die Aktion **„Technische Tests ausführen“** funktionsfähig anbinden.
- Sicherstellen, dass sie mit dem **aktuellen GUI-Zustand** arbeitet und nichts implizit speichert.
- Die definierten Prüfpunkte vollständig orchestrieren, insbesondere:
  - Konfiguration grundsätzlich validierbar,
  - Provider-Konfiguration prüfbar,
  - Base-URL/Endpoint erreichbar,
  - API-Key vorhanden,
  - API-Key technisch akzeptiert,
  - Modellliste abrufbar,
  - ausgewähltes Modell plausibel,
  - Prompt-Datei vorhanden und lesbar,
  - Quellordner vorhanden und lesbar,
  - Zielordner vorhanden oder anlegbar sowie schreibbar,
  - SQLite-Datei bzw. SQLite-Pfad technisch nutzbar.
- Sicherstellen, dass der Gesamttest **nicht** beim ersten Fehler abbricht.
- Provider-nahe technische Prüfungen und Dateisystem-/SQLite-Prüfungen laufen asynchron; die Ergebnisrückführung in die GUI erfolgt über den JavaFX Application Thread.
- Alle Befunde gesammelt und verständlich im zentralen Meldungsbereich ausgeben.
- Deutlich kenntlich machen, dass sich das Ergebnis auf den aktuellen Editorzustand bezieht.
- Ausführung, Teilresultate und Gesamtergebnis der Aktion **„Technische Tests ausführen“** werden im bestehenden Log4j2-Log nachvollziehbar protokolliert.
- JavaDoc/Kommentare zur Gesamttest-Semantik ergänzen.

### Explizit nicht Teil
- schreibende Korrekturen
- Sammel-Bestätigungsdialog
- Prompt-Datei-Erzeugung
- Abschlussdokumentation

### Fertig wenn
- die Aktion **„Technische Tests ausführen“** vollständig arbeitet,
- kein Frühabbruch stattfindet,
- alle Befunde gesammelt sichtbar werden,
- der Build weiterhin fehlerfrei ist.

---

## AP-006 Schreibende Korrekturhilfen und gesammelten Bestätigungsdialog einführen

### Voraussetzung
AP-001 bis AP-005 sind abgeschlossen.

### Ziel
Die GUI kann sichere technische Korrekturen gesammelt vorschlagen und nach einmaliger Bestätigung kontrolliert durchführen.

### Muss umgesetzt werden
- Einen gesammelten Korrekturplan aus Prüfbefunden ableiten.
- Einen einmaligen Bestätigungsdialog implementieren, der die geplanten schreibenden Maßnahmen gesammelt anzeigt.
- Nur sichere technische Korrekturen zulassen, insbesondere dort, wo Ressourcen fehlend, aber technisch anlegbar sind.
- Sicherstellen, dass ohne Bestätigung keine schreibenden Änderungen ausgeführt werden.
- Nach Durchführung die Ergebnisse erneut verständlich in den Meldungsbereich zurückführen.
- Schreibende Korrekturen, Bestätigung und Ergebnisrückmeldung werden im bestehenden Log4j2-Log nachvollziehbar protokolliert.
- Keine stillen Auto-Korrekturen im Hintergrund zulassen.
- JavaDoc/Kommentare für die Korrekturgrenzen ergänzen.

### Explizit nicht Teil
- providerbezogene Auto-Heilung
- Änderung fachlich riskanter Werte
- automatische Lauf-/Verarbeitungsstarts
- Abschlussdokumentation

### Fertig wenn
- sichere technische Korrekturen gesammelt vorgeschlagen werden können,
- genau ein Bestätigungsdialog vor der Ausführung erscheint,
- ohne Bestätigung nichts geschrieben wird,
- der Build weiterhin fehlerfrei ist.

---

## AP-007 Automatische deutsche Standard-Prompt-Erzeugung und anlegbare Ressourcen vervollständigen

### Voraussetzung
AP-001 bis AP-006 sind abgeschlossen.

### Ziel
Fehlende, technisch anlegbare Ressourcen können im Rahmen der Korrekturhilfen sinnvoll hergestellt werden; insbesondere kann eine fehlende Prompt-Datei automatisch als deutsche Standarddatei erzeugt werden.

### Muss umgesetzt werden
- Die automatische Erzeugung einer sinnvollen **deutschsprachigen Standard-Prompt-Datei** implementieren.
- Sicherstellen, dass diese standardmäßig **im selben Ordner wie die `.properties`-Datei** angelegt wird.
- Die Erzeugung nur dann als Korrekturmaßnahme anbieten, wenn der vorgesehene Zielpfad tatsächlich beschreibbar ist.
- Wenn der Standardpfad nicht beschreibbar ist, im Bestätigungsdialog entweder einen alternativen Ablageort vorschlagen oder die Erzeugung ausdrücklich als **„nicht möglich, bitte manuell anlegen“** melden.
- Die Erzeugung in den Korrekturplan und Bestätigungsdialog aus AP-006 integrieren.
- Weitere sichere technische Korrekturen für anlegbare Ressourcen dort ergänzen, wo sie für V2.0 explizit gefordert sind, insbesondere:
  - Zielordner anlegen,
  - SQLite-Datei bzw. nutzbaren SQLite-Pfad vorbereiten,
  - Prompt-Datei anlegen.
- Verständliche deutsche Meldungen für Erfolg, Teilfehler und Nichtdurchführbarkeit bereitstellen.
- Prompt-Erzeugung, Ressourcenkorrekturen und deren Ergebnisse werden im bestehenden Log4j2-Log nachvollziehbar protokolliert.
- JavaDoc/Kommentare für Prompt-Generierung und Ressourcenkorrektur ergänzen.

### Explizit nicht Teil
- fachliche Prompt-Evolution über die Standarddatei hinaus
- manuelle Prompt-Bearbeitung in Spezialansichten
- neue Betriebsfeatures
- Abschlussdokumentation

### Fertig wenn
- die Standard-Prompt-Datei automatisch erzeugt werden kann,
- die Erzeugung sauber in den Korrekturplan integriert ist,
- weitere sichere technische Ressourcenkorrekturen funktionieren,
- der Build weiterhin fehlerfrei ist.

---

## AP-008 Tests für Gesamttest, Korrekturdialog, Prompt-Erzeugung und Netzlaufwerksfähigkeit ergänzen

### Voraussetzung
AP-001 bis AP-007 sind abgeschlossen.

### Ziel
Der vollständige M12-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.

### Muss umgesetzt werden
- Tests für **„Validieren“** mit aktuellem, ungespeichertem Editorzustand ergänzen.
- Tests für **„Technische Tests ausführen“** ohne Frühabbruch ergänzen.
- Tests für providerbezogene technische Prüfpunkte ergänzen, soweit innerhalb von M12 sinnvoll und stabil automatisierbar.
- Tests für den gesammelten Bestätigungsdialog ergänzen.
- Tests für sichere technische Korrekturen ergänzen.
- Tests für automatische Prompt-Erzeugung ergänzen.
- Tests für Windows-/Netzlaufwerksannahmen ergänzen, insbesondere dafür, dass gemappte Laufwerksbuchstaben korrekt akzeptiert werden.
- Sicherstellen, dass der definierte M12-Zielzustand vollständig buildbar und übergabefähig ist.

### Explizit nicht Teil
- Abschlussdokumentation des Gesamtprojekts
- GUI-Erweiterungen aus M13+
- DB-/Historienanzeige
- manueller Verarbeitungslauf

### Fertig wenn
- die M12-spezifische Test-Suite grün ist,
- Gesamttest, Korrekturhilfen und Netzlaufwerksfähigkeit automatisiert abgesichert sind,
- ein fehlerfreier, übergabefähiger Stand vorliegt.

---

## Abschlussbewertung

Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M12 – Technische Tests, Korrekturhilfen und Windows-/Netzlaufwerksfähigkeit** zugeschnitten. Sie decken den vollständigen Zielumfang dieses Meilensteins ab, ohne spätere Ausbaustufen vorwegzunehmen.