# 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**