Files

Marcus van Elst 8a785f1baa Kleinere Korrekturen

2026-04-10 07:50:51 +02:00

11 KiB

Raw Blame History

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:

OpenAI-kompatibel
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:

spezifische Umgebungsvariable für den OpenAI-kompatiblen Provider
bisherige Legacy-Umgebungsvariable
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

11 KiB Raw Blame History Unescape Escape