# V1.1 – Ist-Stand des PDF-Umbenenners

## Zweck dieses Dokuments

Dieses Dokument beschreibt den **tatsächlichen Ist-Stand der Software bis einschließlich V1.1**.  
Es ergänzt die bestehenden Spezifikations- und Projektdokumente um den konkret erreichten Erweiterungsstand nach der vollständig umgesetzten und freigegebenen V1.

Ziel ist, dass eine KI oder ein Entwickler zusammen mit den übrigen Repository-Dokumenten den aktuellen Funktionsumfang und die Architektur **präzise und ohne Rückgriff auf Chat-Verläufe** verstehen kann.

Dieses Dokument ist **kein Soll-Konzept** und **kein neues Arbeitspaket**, sondern eine Beschreibung des erreichten Stands.

---

## Einordnung des Stands

### Ausgangsbasis

Vor V1.1 lag eine vollständig umgesetzte, getestete, dokumentierte und freigegebene **V1** des Projekts vor.  
Diese V1 entsprach dem Umsetzungsstand der Meilensteine **M1 bis M8**.

Damit war insbesondere bereits vorhanden:

- vollständiges Maven-Multi-Module-Projekt
- strikte hexagonale Architektur
- Batch-Verarbeitung über Standalone-JAR
- PDF-Erkennung und PDF-Textauslese
- SQLite-Persistenz
- Retry-, Skip- und Statuslogik
- KI-gestützte Ermittlung eines Benennungsvorschlags
- Dateinamensbildung und Zielkopie
- Logging, Qualitätsabsicherung, Dokumentation und Freigabestand

### Ziel von V1.1

V1.1 wurde bewusst **klein und minimal-invasiv** definiert.

Es handelt sich **nicht** um einen allgemeinen V2-Ausbau und **nicht** um einen Produktumbau mit GUI, Installer oder EXE.

Der Fokus von V1.1 ist ausschließlich:

- Erweiterung der bestehenden KI-Anbindung um **native Claude-Unterstützung**
- gleichzeitiger Erhalt des bisherigen **OpenAI-kompatiblen Wegs**
- Mehrprovider-Konfiguration mit **genau einem aktiven Provider**
- Wahrung der bestehenden Architekturprinzipien
- Wahrung der fachlichen und technischen Regeln aus V1
- Abwärtskompatibilität bestehender Konfigurationen

---

## Inhaltlicher Umfang von V1.1

V1.1 erweitert die bestehende Anwendung um eine **Mehrprovider-fähige KI-Konfiguration**, bei der genau **ein Provider aktiv** ist.

### In V1.1 enthalten

- Unterstützung von **zwei real nutzbaren KI-Providern**
  - OpenAI-kompatibler Provider
  - nativer Claude-Provider
- Properties-basierte Konfiguration für mehrere Provider
- Auswahl genau **eines aktiven Providers**
- Beibehaltung des bisherigen fachlichen KI-Vertrags
- Integration der Providerwahl in die bestehende technische Konfiguration
- Migration alter V1-Konfigurationen auf die neue Struktur
- Sicherung alter Konfigurationen über `.bak`
- vollständige Tests und Nachschärfung der Build-/Qualitätshygiene

### In V1.1 ausdrücklich **nicht** enthalten

- GUI
- Installer
- EXE-Paketierung
- mehrere Profile pro Provider
- automatischer Fallback zwischen Providern
- neue fachliche Regeln für Dateinamen
- neue Retry-Semantik
- neue Statussemantik
- neue Persistenz-Wahrheiten
- Änderungen am Grundprinzip des Batch-Betriebs

---

## Fachlich-technische Kernaussage von V1.1

Die Anwendung verarbeitet weiterhin OCR-verarbeitete PDF-Dateien lokal und erzeugt daraus im Erfolgsfall korrekt benannte Zielkopien.

Der Unterschied zu V1 ist:

> Die Ermittlung des KI-basierten Benennungsvorschlags kann nun wahlweise
> über einen **OpenAI-kompatiblen Provider** oder über die **native Claude-API**
> erfolgen.

Dabei bleibt für den restlichen fachlichen Ablauf entscheidend:

- der Input bleibt ein aufbereiteter Dokumenttext
- die KI liefert weiterhin denselben fachlichen Vorschlagsinhalt
- der restliche Verarbeitungsfluss bleibt unverändert

---

## Unveränderte Regeln aus V1

V1.1 ändert **nicht** die fachlichen Kernregeln des Systems.

Insbesondere unverändert bleiben:

- Zielformat: `YYYY-MM-DD - Titel.pdf`
- Dublettenregel `(1)`, `(2)`, …
- 20-Zeichen-Regel für den Basistitel
- deutsche, verständliche Titel
- Quelldatei bleibt unverändert
- Fingerprint-basierte Identifikation
- SQLite als lokaler Persistenzspeicher
- Retry- und Skip-Regeln
- Statusmodell
- Run-Lock
- Start über Standalone-JAR / Task Scheduler
- keine Dauerlauf-Anwendung
- keine GUI / kein Webserver / kein App-Server

---

## Architekturstand in V1.1

V1.1 wahrt die bestehende Architektur.

### Unverändert gültig

- strikte hexagonale Architektur
- Ports and Adapters
- Abhängigkeiten zeigen nach innen
- keine Infrastruktur im Domain-Kern
- keine direkte Adapter-zu-Adapter-Kopplung
- Logging bleibt technische Infrastruktur
- Konfiguration bleibt technische Infrastruktur
- Bootstrap verdrahtet die konkrete Laufzeitumgebung

### Bedeutung für die KI-Integration

Die Mehrprovider-Fähigkeit wird **architekturtreu** eingeführt:

- der fachliche/application-seitige KI-Vertrag bleibt erhalten
- die Provider-spezifischen Unterschiede liegen in den technischen Adaptern
- die konkrete Providerauswahl erfolgt über Konfiguration und Bootstrap
- es entsteht keine provider-spezifische Fachlogik im Kern

---

## KI-Provider in V1.1

### Unterstützte Provider

V1.1 unterstützt genau diese zwei Providerarten:

1. **OpenAI-kompatibel**
2. **Claude nativ**

### Aktiver Provider

Es gibt immer **genau einen aktiven Provider**.

V1.1 führt **keinen** automatischen Fallback zwischen Providern ein.  
Wenn der aktive Provider fehlschlägt, gilt der bestehende Fehler- und Retry-Rahmen.

### Keine Profilverwaltung

Pro Provider gibt es in V1.1 genau **eine** Konfiguration.  
Benannte Profile oder mehrere alternative Konfigurationssätze pro Provider sind nicht Bestandteil von V1.1.

---

## KI-Vertrag bleibt unverändert

V1.1 ändert **nicht** den fachlichen Ergebnisvertrag der KI.

Die Erweiterung betrifft den technischen Zugriffsweg auf die KI, **nicht** den fachlichen Inhalt der KI-Antwort.

Damit bleibt der Grundsatz bestehen:

- die KI liefert denselben fachlichen Vorschlagsinhalt wie zuvor
- die Anwendung behält die Hoheit über Validierung, Datumsauflösung, Titelregeln und weitere technische Verarbeitung
- der restliche Systemablauf bleibt gegenüber V1 stabil

---

## Konfigurationsmodell in V1.1

### Allgemeiner Grundsatz

Die `.properties`-Datei bleibt die **Wahrheit** der Konfiguration.

### Erweiterung in V1.1

Die Konfiguration kann nun mehrere Provider-Konfigurationen enthalten, von denen genau **eine aktiv** ist.

### Abwärtskompatibilität

Bestehende V1-Konfigurationen bleiben nutzbar.

Dazu wurde in V1.1 vorgesehen:

- Erkennung alter Konfigurationsstruktur
- Migration auf die neue Struktur beim ersten Start
- vorherige Anlage einer Sicherung mit `.bak`

### Legacy-Kompatibilität beim API-Key

Für den OpenAI-kompatiblen Provider wurde die Abwärtskompatibilität auch für bestehende API-Key-Setups beibehalten.

Die Auflösung erfolgt in dieser Reihenfolge:

1. spezifische Umgebungsvariable für den OpenAI-kompatiblen Provider
2. bisherige Legacy-Umgebungsvariable
3. Property-basierter API-Key

Dadurch brechen bestehende Setups nicht still.

### Strikte Provider-Validierung

Die Konfiguration des aktiven Providers wird vor dem eigentlichen Lauf sauber validiert.

Dazu gehört insbesondere die Base-URL-Prüfung:

- syntaktisch gültige URI
- absolute URI
- nur `http` oder `https`

Ungültige Provider-Konfiguration ist eine ungültige Startkonfiguration und verhindert den Laufbeginn.

---

## Persistenz und Nachvollziehbarkeit

Das bestehende Zwei-Ebenen-Modell bleibt erhalten:

- Dokument-Stammsatz
- Versuchshistorie

V1.1 führt **keine neue Persistenz-Wahrheit** ein.

Die durch V1 etablierten Regeln zu Status, Retry, Zielerfolg, Proposal-Quelle und Historisierung bleiben in Kraft.

Die Erweiterung um mehrere Provider dient der technisch sauberen Mehrprovider-Nutzung und der konsistenten Nachvollziehbarkeit des verwendeten Providers im Rahmen der bestehenden Architektur.

---

## Qualitäts- und Stabilisierungsschritte nach der V1.1-Implementierung

Nach der funktionalen Einführung von V1.1 wurde der Stand zusätzlich qualitativ nachgeschärft.

Diese Nachschärfungen gehören zum erreichten Ist-Stand.

### 1. Rückwärtskompatibilität und Provider-Validierung

Es wurden Korrekturen durchgeführt für:

- Legacy-Fallback beim OpenAI-kompatiblen API-Key
- strikte Validierung der Provider-Base-URL
- Sicherstellung, dass alte Setups nicht still brechen

### 2. Dokumentation

Es wurde eine README für das Repository ergänzt, damit der Projektstand und die Grundbenutzung nachvollziehbar dokumentiert sind.

### 3. Compiler-, Test- und Build-Hygiene

Es wurden mehrere kleinere Qualitätskorrekturen durchgeführt, unter anderem:

- Bereinigung von Raw-Type-/Unchecked-Warnungen in Tests
- Beseitigung veralteter API-Nutzung in Bootstrap-Testhilfen
- Bereinigung des Logging-Klassenpfads im Testkontext
- bewusste Konfiguration des Annotation Processings

### 4. Mutationstest- und Build-Verbesserungen

Die Qualität des Test- und PIT-Stands wurde gezielt verbessert, insbesondere in:

- `adapter-out`
- `bootstrap`

Zusätzlich wurde ein PIT-Timeout bereinigt, das durch einen langsamen Integrationstest mit Netzwerkaufruf verursacht wurde.

### 5. Bewertung verbliebener Build-Hinweise

Verbleibende Log4j2-/Shade-Hinweise wurden geprüft und als funktional unkritisch eingeordnet, soweit sie keine reale Auswirkung auf den Produktivbetrieb haben.

---

## Ergebnisstatus von V1.1

V1.1 ist als **fertiger, implementierter und getesteter Ist-Stand** zu verstehen.

Das bedeutet:

- die Erweiterung ist umgesetzt
- die Erweiterung ist in die bestehende Architektur eingebettet
- die relevanten Qualitäts- und Stabilitätskorrekturen wurden nachgezogen
- der Projektstand nach V1.1 ist gegenüber V1 fachlich stabil erweitert und technisch nachgeschärft

---

## Verhältnis zu den übrigen Repository-Dokumenten

Dieses Dokument ersetzt **nicht** die bestehenden Spezifikationsdokumente.

Es ergänzt sie um die Aussage:

> **Was ist nach Abschluss von V1.1 zusätzlich tatsächlich vorhanden?**

Für eine vollständige Einordnung bleiben weiterhin maßgeblich:

- `CLAUDE.md`
- `docs/specs/technik-und-architektur.md`
- `docs/specs/fachliche-anforderungen.md`
- `docs/specs/meilensteine.md`

Dieses Dokument beschreibt den **erreichten zusätzlichen Ist-Zustand bis einschließlich V1.1**.

---

## Kompakte Zusammenfassung für KI-Systeme

Wenn eine KI diesen Stand kurz einordnen soll, gilt:

- V1 des `pdf-umbenenner` war vollständig umgesetzt und freigegeben
- V1.1 ist eine **kleine, minimal-invasive Erweiterung**
- V1.1 fügt **native Claude-Unterstützung** hinzu
- der bisherige **OpenAI-kompatible Weg bleibt erhalten**
- die Konfiguration unterstützt mehrere Provider, aber **genau einen aktiven Provider**
- bestehende Konfigurationen bleiben per Migration und Legacy-Fallback kompatibel
- fachliche Regeln, Architekturprinzipien und Kernverhalten aus V1 bleiben unverändert
- nach der Implementierung wurden zusätzliche Qualitäts-, Build- und Testhygiene-Maßnahmen durchgeführt
- der Ist-Zustand des Projekts umfasst damit **V1 + V1.1**
