Vorbereitungen zu V1.1

docs/workpackages/V1.1 - Neue Arbeitspakete.md

@@ -0,0 +1,324 @@
+# Arbeitspakete – Erweiterung um native Anthropic Claude-Anbindung
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für die Erweiterung **„Zusätzliche KI-Provider-Familie Anthropic Claude über die native Messages API"**.
+
+Der Basisstand des Projekts ist vollständig umgesetzt, dokumentiert, getestet und freigegeben. Diese Erweiterung ist eine **bewusst minimale Ergänzung** dieses Basisstands.
+
+Das einzige Ziel dieser Erweiterung ist:
+- den bestehenden, OpenAI-kompatiblen KI-Weg unverändert nutzbar zu halten,
+- zusätzlich die **native Anthropic Messages API** als zweiten, gleichwertig unterstützten KI-Provider anzubinden,
+- und zwischen beiden Providern über die Konfiguration genau **einen aktiven Provider** auszuwählen.
+
+Die Arbeitspakete sind 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.
+
+## Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, Konfiguration, Dokumentation und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die verbindlichen Spezifikationen, dieses Dokument oder den tatsächlich vorliegenden Code gedeckt sind.
+- Änderungen strikt nach dem Prinzip: **so wenig wie möglich, so viel wie nötig**.
+- Keine allgemeine Provider-Plattform und keine Abstraktion für hypothetische weitere Provider.
+- Kein Umbau des bestehenden fachlichen Ablaufs ohne direkten Bezug zur Provider-Erweiterung.
+- Das bestehende fachliche Verhalten des Basisstands bleibt unverändert, soweit dieses Dokument nichts anderes ausdrücklich erweitert.
+- Jeder positive Zwischenstand muss bereits **vollständig buildbar, testbar und dokumentiert** sein.
+- Zu jedem Arbeitspaket gehören die unmittelbar betroffenen:
+  - Implementierungen,
+  - Tests (inkl. ggf. Mutationstests in den unmittelbar betroffenen Modulen),
+  - JavaDoc / `package-info`,
+  - Konfigurationsbeispiele,
+  - sowie sonstige Repository-Dokumente mit direktem Bezug.
+
+## Explizit nicht Bestandteil dieser Erweiterung
+
+- Provider-Familien jenseits der zwei explizit unterstützten (OpenAI-kompatibel, Anthropic Messages API)
+- mehrere Konfigurationen je Provider-Familie (Profilverwaltung)
+- automatische Fallback-Umschaltung zwischen Providern
+- parallele Nutzung mehrerer Provider in einem Lauf
+- Änderung des fachlichen Ergebnisvertrags der KI
+- Änderung der Dateinamensregeln
+- Änderung der Retry-Regeln
+- Änderung des Batch-Betriebsmodells
+- Änderung der bestehenden fachlichen Kernlogik außerhalb der für die Claude-Integration nötigen Anbindung
+- Persistenz- oder Schemaänderungen ohne zwingenden Bedarf für die Provider-Erweiterung (additive Provider-Identifikator-Spalte ist explizit zwingend, mehr nicht)
+
+## Verbindliche Regeln für **alle** Arbeitspakete
+
+### 1. Minimale Erweiterung des Basisstands
+Die Erweiterung darf den bestehenden fachlichen Ablauf **nicht stillschweigend verändern**.
+
+Ziel ist ausschließlich:
+- den bestehenden OpenAI-kompatiblen KI-Weg weiter nutzbar zu halten,
+- zusätzlich einen nativen Anthropic-Messages-API-Adapter zu integrieren,
+- und zwischen beiden Wegen über die Konfiguration genau **einen aktiven Provider** auszuwählen.
+
+### 2. Einheitlicher fachlicher KI-Vertrag
+Unabhängig vom Provider gilt weiterhin derselbe fachliche Vertrag:
+- gleicher fachlicher Input
+- gleicher fachlicher Output (`NamingProposal`)
+- gleicher Validierungs- und Folgeprozess in der Anwendung
+- keine provider-spezifische Verzweigung im fachlichen Kern
+- der bestehende strukturierte Ergebnisvertrag bleibt unverändert; es entsteht **kein** provider-spezifischer Sonderweg
+
+### 3. Genau ein aktiver Provider
+Es werden gespeichert:
+- **genau eine** Konfiguration für die OpenAI-kompatible Provider-Familie
+- **genau eine** Konfiguration für die Anthropic-Provider-Familie
+- **genau ein** aktiver Provider
+
+Es gibt:
+- keine Profilverwaltung
+- keine Prioritätenliste
+- keinen Mehrfach-Fallback
+- keine automatische Umschaltung bei Fehlern
+
+### 4. Properties-Datei bleibt führend
+Die Konfiguration bleibt in der `.properties`-Datei geführt.
+
+Die Struktur darf weiterentwickelt werden, muss aber:
+- bestehende Properties-Dateien des Vorgängerstands **weiterhin akzeptieren**,
+- diese **beim ersten Start** kontrolliert in die neue Struktur überführen,
+- **vor** der Migration immer eine `.bak`-Sicherung anlegen.
+
+### 5. Migration bestehender Properties beim ersten Start
+Wird eine Legacy-Form erkannt, gilt verbindlich:
+1. Legacy-Form erkennen
+2. `.bak`-Sicherung anlegen
+3. Datei in die neue Struktur migrieren (Legacy-Werte → Namensraum `openai-compatible`, `ai.provider.active=openai-compatible`)
+4. Datei erneut laden und validieren
+5. Erst danach den normalen Lauf fortsetzen
+
+Alte und neue Struktur sind **kein** dauerhaft gleichrangiges Endformat.
+
+### 6. OpenAI-kompatibler Weg bleibt funktional unverändert
+Der bestehende OpenAI-kompatible Adapter bleibt funktional unverändert nutzbar.
+
+Daraus folgt:
+- kein fachlicher Regressionsumbau des bisherigen Provider-Verhaltens
+- bestehende Konfigurationen müssen nach der Migration weiterhin funktional anschlussfähig sein
+- die Erweiterung darf den bestehenden Weg nicht beschädigen
+
+### 7. Claude wird über die native Messages API angebunden
+Anthropic Claude wird über einen **eigenen nativen Adapter** im Adapter-Out-Modul angebunden.
+
+Daraus folgt:
+- Endpunkt, Authentifizierungsschema, Request- und Response-Format der Anthropic Messages API leben **ausschließlich** im Adapter
+- Domain und Application bleiben provider-neutral
+- die provider-spezifische Request-/Response-Abbildung darf den fachlichen Vertrag nicht verändern
+- Adapter dürfen nicht voneinander abhängen; es gibt keine gemeinsame Zwischenschicht
+
+### 8. Provider-Auswahl ist strikt und ohne Fallback
+Der aktive Provider wird ausschließlich aus der Konfiguration bestimmt.
+
+Daraus folgt:
+- nur der aktive Provider wird verwendet
+- der inaktive Provider wird in keiner Fehlersituation als Backup verwendet
+- Fehler des aktiven Providers bleiben Fehler dieses einen Pfads und folgen der bestehenden Retry- und Fehlersemantik
+
+### 9. Keine Zusatzänderungen ohne direkten Provider-Bezug
+Es werden nur solche Änderungen eingeführt, die für die zusätzliche Claude-Integration und die dafür nötige Provider-Auswahl tatsächlich erforderlich sind.
+
+Daraus folgt:
+- keine zusätzlichen Komfortfunktionen
+- keine allgemeine Provider-Plattform
+- keine Änderungen an Persistenz oder Nachvollziehbarkeit, sofern sie für diese Erweiterung nicht zwingend erforderlich sind (additive Provider-Identifikator-Spalte ist die einzige zwingende Persistenzänderung)
+
+### 10. Architekturtreue
+Es gilt unverändert:
+- strikte hexagonale Architektur
+- Abhängigkeiten zeigen nach innen
+- keine Infrastrukturtypen in Domain oder Application
+- keine direkte Adapter-zu-Adapter-Kopplung
+- keine Vermischung von Provider-spezifischer HTTP-Kommunikation mit fachlicher Entscheidungslogik
+- der `AiNamingPort` bleibt provider-neutral
+
+---
+
+## AP-001 – Konfigurations-Schema, Migration mit `.bak` und Startvalidierung
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der Startpunkt der Erweiterung.
+
+### Ziel
+Die Konfiguration wird mit minimalem Eingriff so erweitert, dass zwischen den unterstützten Provider-Familien gewählt werden kann, und bestehende Properties-Dateien aus dem Vorgängerstand werden beim ersten Start automatisch sicher in das neue Schema überführt.
+
+### Muss umgesetzt werden
+- Properties-Schema minimal so erweitern, dass folgende Informationen konfigurierbar sind:
+  - aktiver Provider (`ai.provider.active`),
+  - Konfigurations-Namensraum für die OpenAI-kompatible Provider-Familie,
+  - Konfigurations-Namensraum für die Claude-Provider-Familie.
+- Legacy-Form (flache `api.*`-Schlüssel) eindeutig erkennen.
+- Vor jeder Migration automatisch eine **`.bak`-Sicherung** anlegen.
+- Migration als **In-Place-Update** umsetzen:
+  - Legacy lesen,
+  - in neues Schema überführen,
+  - in-place schreiben,
+  - neu laden,
+  - validieren.
+- Legacy-Werte korrekt in den Namensraum `openai-compatible` überführen und `ai.provider.active=openai-compatible` setzen.
+- Startvalidierung gezielt erweitern, insbesondere für:
+  - genau ein gesetzter, unterstützter aktiver Provider,
+  - nur die für den aktiven Provider nötigen Pflichtwerte,
+  - technisch konsistente Provider-Konfiguration (Modellname, Timeout, ggf. Basis-URL),
+  - API-Schlüssel des aktiven Providers (Umgebungsvariable hat Vorrang vor Properties).
+- Konfigurationsbeispiele, JavaDoc und unmittelbar betroffene Repository-Dokumente anpassen.
+- Tests ergänzen für:
+  - erfolgreiche Migration einer realistischen Legacy-Datei,
+  - `.bak`-Erzeugung,
+  - korrekte Übernahme der Legacy-Werte in den `openai-compatible`-Namensraum,
+  - Abweisung ungültiger oder fehlender `ai.provider.active`,
+  - Abweisung unvollständiger Pflichtwerte für den aktiven Provider,
+  - Vorrang der Umgebungsvariablen vor dem Properties-Schlüssel des aktiven Providers.
+
+### Explizit nicht Teil
+- nativer Claude-Adapter
+- Bootstrap-Auswahl des aktiven Providers (folgt in AP-002)
+- Refactoring des bestehenden OpenAI-kompatiblen Adapters über das für das neue Schema nötige Maß hinaus
+- Persistenz- oder Schemaänderungen
+- fachliche Änderungen am KI-Ergebnisvertrag
+
+### Fertig wenn
+- das erweiterte Properties-Schema technisch nutzbar ist,
+- Legacy-Dateien beim ersten Start sicher mit `.bak` migriert werden,
+- ungültige Provider-Konfigurationen sauber abgewiesen werden,
+- der Build weiterhin fehlerfrei ist und alle bestehenden Tests grün bleiben.
+
+---
+
+## AP-002 – Bestehenden OpenAI-kompatiblen Pfad an die Provider-Auswahl anbinden
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Der bestehende OpenAI-kompatible KI-Weg wird mit minimalem Umbau so eingebettet, dass das Bootstrap-Modul den aktiven Provider aus der Konfiguration auswählen und verdrahten kann, ohne den bisherigen fachlichen Ablauf zu verändern.
+
+### Muss umgesetzt werden
+- Im Bootstrap-Modul eine **Provider-Auswahl** einführen, die anhand von `ai.provider.active` genau eine `AiNamingPort`-Implementierung als aktive Implementierung verdrahtet.
+- Den bestehenden OpenAI-kompatiblen Adapter so anbinden, dass er die Werte aus dem Namensraum `ai.provider.openai-compatible.*` konsumiert.
+- Den bisherigen OpenAI-kompatiblen Weg dabei funktional unverändert erhalten.
+- Application und Domain weiterhin frei von provider-spezifischen HTTP-/JSON-Typen halten.
+- Provider-spezifische Request-/Response-Abbildung und Fehlerbehandlung weiterhin klar im Adapter-Out kapseln.
+- Sicherstellen, dass ein zukünftiger zweiter Provider nur durch eine zusätzliche Implementierung im Adapter-Out und einen zusätzlichen Eintrag in der Provider-Auswahl angebunden wird – ohne neue Zwischenschicht und ohne Adapter-zu-Adapter-Kopplung.
+- Den Provider-Identifikator des aktiven Providers in die Versuchshistorie einfließen lassen (additive Schema-Erweiterung mit definiertem Default für historische Versuche).
+- Logging-Mindestumfang um den **aktiven Provider beim Laufstart** ergänzen.
+- Relevante JavaDoc- und Repository-Dokumentation mitziehen.
+- Tests gezielt anpassen oder ergänzen, um nachzuweisen:
+  - der bisherige OpenAI-kompatible Pfad bleibt funktional intakt,
+  - die Provider-Auswahl ist technisch sauber angebunden,
+  - eine ungültige Provider-Auswahl scheitert in der Startvalidierung,
+  - der Provider-Identifikator landet pro Versuch korrekt in der Persistenz,
+  - der fachliche Ergebnisvertrag bleibt unverändert,
+  - bestehende Datenbestände bleiben lesbar und korrekt interpretierbar.
+
+### Explizit nicht Teil
+- nativer Claude-Adapter
+- Fallback-Logik
+- zusätzliche Provider-Familien
+- Persistenz- oder Schemaänderungen jenseits der additiven Provider-Identifikator-Spalte
+- globale Abschlussprüfung
+
+### Fertig wenn
+- der OpenAI-kompatible Weg über die neue Provider-Auswahl sauber nutzbar bleibt,
+- sein fachliches Verhalten gegenüber dem Vorgängerstand unverändert ist,
+- keine Provider-Implementierungsdetails in den fachlichen Kern durchsickern,
+- der Provider-Identifikator persistent erfasst wird,
+- bestehende Datenbestände unverändert nutzbar bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 – Nativen Anthropic-Messages-API-Adapter implementieren und verdrahten
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Ein nativer Adapter für die Anthropic Messages API ist technisch nutzbar, wird über die Provider-Auswahl als aktiver Provider verdrahtet und liefert fachlich denselben Ergebnisvertrag wie der bestehende OpenAI-kompatible Weg.
+
+### Muss umgesetzt werden
+- Im Adapter-Out-Modul eine zweite `AiNamingPort`-Implementierung anlegen, die die **native Anthropic Messages API** anspricht.
+- Die Claude-spezifische Konfiguration aus dem Namensraum `ai.provider.claude.*` technisch anbinden, mindestens:
+  - Modellname,
+  - API-Schlüssel (Umgebungsvariable hat Vorrang),
+  - Timeout,
+  - Basis-URL als optionaler Konfigurationswert mit fachlich neutralem Default.
+- Provider-spezifische Request-Erzeugung und Response-Verarbeitung so umsetzen, dass das fachliche JSON-Ergebnis (`date`, `title`, `reasoning`) wie beim bestehenden Weg in den vorhandenen Domain-Typ `NamingProposal` abgebildet wird.
+- Technische Fehlerfälle des Claude-Pfads (HTTP-Fehler, Timeouts, ungültige Antwortstrukturen, Authentifizierungsfehler) **im Adapter** klassifizieren und auf die bestehende technische Fehlersemantik des Projekts abbilden. Es entstehen keine neuen Fehlerklassen.
+- Sicherstellen, dass Claude **keinen** Sonderweg im fachlichen Kern erzwingt und keine Application-/Domain-Klasse provider-spezifisch wird.
+- Die Provider-Auswahl im Bootstrap-Modul um die neue Implementierung erweitern. Das geschieht ausschließlich in der bereits in AP-002 angelegten Auswahlstelle, ohne neue Zwischenschicht.
+- Adapter-zu-Adapter-Kopplung aktiv vermeiden: keine gemeinsame Basisklasse, kein gemeinsamer Hilfsadapter zwischen Port und konkreten Adaptern.
+- Konfigurationsbeispiele, JavaDoc und unmittelbar betroffene Repository-Dokumente mitziehen.
+- Tests ergänzen für:
+  - korrekte Request-Erzeugung gegen die Anthropic Messages API (Adapter-Test mit gemocktem HTTP-Layer),
+  - korrekte Response-Abbildung auf den bestehenden fachlichen Vertrag,
+  - technische Claude-Fehlerfälle (HTTP-Fehler, Timeout, Auth-Fehler, defekte Antwortstruktur) und deren Klassifikation,
+  - Auswahl und Nutzung von Claude als aktivem Provider über die Konfiguration,
+  - keine fachliche Sonderbehandlung gegenüber dem OpenAI-kompatiblen Pfad,
+  - korrekter Provider-Identifikator in der Versuchshistorie für Claude-Läufe.
+
+### Explizit nicht Teil
+- automatische Fallback-Logik
+- weitere Provider-Familien
+- Persistenz- oder Schemaänderungen jenseits der bereits in AP-002 eingeführten additiven Provider-Identifikator-Spalte
+- neue Fachfunktionalität außerhalb der Provider-Erweiterung
+- globale Abschlussprüfung
+
+### Fertig wenn
+- der native Anthropic-Messages-API-Adapter technisch nutzbar ist,
+- Claude über die Konfiguration als aktiver Provider auswählbar ist,
+- sein Ergebnis fachlich auf denselben Vertrag wie der bestehende Provider abgebildet wird,
+- provider-spezifische Details ausschließlich im Adapter-Out leben,
+- der bestehende OpenAI-kompatible Pfad weiterhin unverändert nutzbar ist,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 – Regressionsschutz, Dokumentationskonsolidierung und Abschlussnachweis
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Der vollständige Erweiterungsstand wird automatisiert abgesichert, dokumentarisch konsolidiert und als minimale Erweiterung des freigegebenen Basisstands belastbar nachgewiesen.
+
+### Muss umgesetzt werden
+- Den vollständigen Erweiterungsstand gegen die in diesem Dokument definierten Regeln prüfen.
+- Tests vervollständigen bzw. konsolidieren, insbesondere für:
+  - erfolgreiche Migration einer realistischen Legacy-Properties-Datei,
+  - `.bak`-Erzeugung,
+  - OpenAI-kompatibler Provider weiterhin nutzbar (Regression),
+  - nativer Anthropic-Provider nutzbar,
+  - genau ein aktiver Provider, ohne Fallback-Umschaltung,
+  - einheitlicher fachlicher Ergebnisvertrag über beide Provider hinweg,
+  - Provider-Identifikator in der Versuchshistorie korrekt gesetzt,
+  - Logging des aktiven Providers beim Laufstart vorhanden,
+  - Sensibilitätsregel für KI-Inhalte gilt provider-unabhängig,
+  - bestehende Datenbestände bleiben lesbar und korrekt interpretierbar.
+- Vorhandene PIT-/Mutationstest-Konfiguration auf die neuen oder geänderten Klassen ausdehnen, soweit für den Stand sinnvoll.
+- Smoke-Tests so erweitern, dass für **beide** Provider-Konfigurationen der Bootstrap-Pfad bis zur erfolgreichen Verdrahtung des `AiNamingPort` durchläuft (ohne realen externen Aufruf).
+- Konfigurationsbeispiele, Startdokumentation und sonstige Repository-Dokumente konsolidieren, sodass die Erweiterung ohne implizite Annahmen verständlich bleibt.
+- Einen knappen, im Repository verbleibenden Abschlussnachweis ergänzen, der mindestens festhält:
+  - welche Prüfungen tatsächlich ausgeführt wurden,
+  - dass die Erweiterung minimal-invasiv umgesetzt wurde,
+  - dass beide Provider-Familien unterstützt werden,
+  - dass die Konfigurationsmigration und `.bak`-Sicherung nachgewiesen sind,
+  - dass keine Architekturbrüche eingeführt wurden.
+- Den relevanten Build-/Test-Umfang tatsächlich ausführen.
+
+### Explizit nicht Teil
+- weitere Provider-Familien
+- zusätzliche Konfigurationsprofile
+- neue Komfort- oder Bedienfunktionen
+- weitergehende Architekturumbauten ohne direkten Bezug zur Erweiterung
+
+### Fertig wenn
+- der vollständige Erweiterungsstand automatisiert abgesichert ist,
+- die Dokumentation konsistent zum realen Verhalten passt,
+- die Minimalinvasivität gegenüber dem Basisstand belastbar nachgewiesen ist,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.