README hinzugefügt

README.md

@@ -0,0 +1,195 @@
+# PDF-Umbenenner
+
+Ein lokal gestartetes Java-Programm zur KI-gestützten Umbenennung bereits OCR-verarbeiteter, durchsuchbarer PDF-Dateien.
+
+Die Anwendung liest PDF-Dateien aus einem konfigurierbaren Quellordner, extrahiert den Text, ermittelt daraus per KI einen normierten Dateinamen und legt **eine Kopie** im Zielordner ab. Die Quelldateien bleiben unverändert.
+
+## Zielbild
+
+Der PDF-Umbenenner ist bewusst als schlanke Batch-Anwendung ausgelegt:
+
+- **Java 21**
+- **Maven Multi-Module**
+- **ausführbares Standalone-JAR**
+- **lokaler Start**, z. B. über den **Windows Task Scheduler**
+- **kein Webserver**
+- **kein Applikationsserver**
+- **keine Dauerlauf-Anwendung**
+- **kein interner Scheduler**
+- **SQLite** als lokaler Persistenzspeicher
+- **Log4j2** für Logging
+- strikte **hexagonale Architektur / Ports and Adapters**
+
+## Fachlicher Überblick
+
+Die Anwendung verarbeitet Dokumente in einem robusten, nachvollziehbaren Ablauf:
+
+1. Quellordner lesen
+2. PDF-Kandidaten erkennen
+3. Fingerprint der Quelldatei bestimmen
+4. bereits erfolgreich verarbeitete bzw. final fehlgeschlagene Dokumente überspringen
+5. PDF-Text extrahieren
+6. KI-basierten Benennungsvorschlag erzeugen
+7. normierten Zieldateinamen bilden
+8. Kollisionen im Zielordner über Dubletten-Suffixe auflösen
+9. Kopie im Zielordner ablegen
+10. Ergebnis und Versuchshistorie in SQLite persistieren
+
+## Dateinamensregeln
+
+Das Zielformat lautet:
+
+```text
+YYYY-MM-DD - Titel.pdf
+```
+
+Bei Namenskollisionen werden Suffixe direkt vor `.pdf` ergänzt:
+
+```text
+YYYY-MM-DD - Titel(1).pdf
+YYYY-MM-DD - Titel(2).pdf
+```
+
+Wichtige Regeln:
+
+- die **20 Zeichen** beziehen sich nur auf den **Basistitel**
+- das Dubletten-Suffix zählt **nicht** zu diesen 20 Zeichen
+- Titel werden auf **Deutsch** erzeugt
+- Eigennamen bleiben unverändert
+- Quelldateien werden **nie** überschrieben, verschoben oder verändert
+
+## KI-Anbindung
+
+Die KI-Anbindung ist konfigurationsgetrieben. Der fachliche Vertrag bleibt unabhängig vom Anbieter gleich: Aus dem Dokumentinhalt wird ein strukturierter Benennungsvorschlag abgeleitet, aus dem die Anwendung den finalen Dateinamen bildet.
+
+Der aktuelle Stand unterstützt mehrere Provider über Konfiguration, darunter:
+
+- **OpenAI-kompatible Endpunkte**
+- **Claude API**
+
+Die Provider-Auswahl ist **Konfiguration**, keine Architekturentscheidung.
+
+## Wichtige Annahmen und Grenzen
+
+- Die Anwendung erwartet **bereits OCR-verarbeitete, durchsuchbare PDFs**.
+- Nicht durchsuchbare oder inhaltlich nicht brauchbare PDFs werden als Fehler behandelt.
+- Mehrdeutige Dokumente erzeugen **kein unsicheres Ergebnis**.
+- Erfolgreich verarbeitete Dateien werden in späteren Läufen nicht erneut verarbeitet.
+- Final fehlgeschlagene Dateien werden in späteren Läufen übersprungen.
+
+## Architektur
+
+Das Projekt ist strikt nach **Ports and Adapters / Hexagonal Architecture** aufgebaut.
+
+### Module
+
+- `pdf-umbenenner-domain`
+- `pdf-umbenenner-application`
+- `pdf-umbenenner-adapter-in-cli`
+- `pdf-umbenenner-adapter-out`
+- `pdf-umbenenner-bootstrap`
+
+### Grundprinzipien
+
+- Abhängigkeiten zeigen immer **nach innen**
+- Domain kennt **keine Infrastruktur**
+- externe Zugriffe erfolgen ausschließlich über **Ports**
+- technische Implementierungen liegen in **Adaptern**
+- keine direkte Adapter-zu-Adapter-Kopplung
+
+## Konfiguration
+
+Die Anwendung wird über eine `.properties`-Datei konfiguriert.
+
+Typische Bereiche sind:
+
+- Quellordner
+- Zielordner
+- SQLite-Datei
+- KI-Provider und Modell
+- Timeout
+- Seitenlimit
+- Textlimit für KI-Aufrufe
+- Prompt-Datei
+- Logging
+
+Für einen lokalen Einstieg dient die Beispielkonfiguration unter:
+
+```text
+config/application-local.example.properties
+```
+
+## Build
+
+Projektweit:
+
+```bash
+./mvnw clean verify
+```
+
+Unter Windows:
+
+```powershell
+.\mvnw.cmd clean verify
+```
+
+## Start
+
+Das ausführbare Artefakt wird im Bootstrap-Modul erzeugt. Der Start erfolgt als normales Java-Programm:
+
+```bash
+java -jar <bootstrap-jar>.jar
+```
+
+Die konkrete JAR-Datei hängt vom aktuellen Build-Stand ab.
+
+## Logging, Status und Nachvollziehbarkeit
+
+Der PDF-Umbenenner ist auf Nachvollziehbarkeit und Wiederholbarkeit ausgelegt:
+
+- persistente Dokumenthistorie in **SQLite**
+- Status- und Retry-Semantik für robuste Batch-Läufe
+- Idempotenz über inhaltsbasierten Fingerprint
+- Logging über **Log4j2**
+- Schutz sensibler KI-Inhalte im Log
+
+## Dokumentation im Repository
+
+Die maßgeblichen Dokumente sind:
+
+- `CLAUDE.md`
+- `docs/specs/technik-und-architektur.md`
+- `docs/specs/fachliche-anforderungen.md`
+- `docs/specs/meilensteine.md`
+- `docs/workpackages/...`
+
+Empfohlene Leserichtung:
+
+1. `CLAUDE.md`
+2. technische Zielarchitektur
+3. fachliche Anforderungen
+4. Meilensteine
+5. aktives Arbeitspaket
+
+## Entwicklungsleitplanken
+
+- kleine, fokussierte Änderungen
+- keine stillen Annahmen bei Dokumentkonflikten
+- keine unnötigen Refactorings
+- Architekturtreue hat Vorrang
+- keine Meilenstein- oder Arbeitspaket-Bezeichner in Produktionscode, Kommentaren oder JavaDoc
+
+## Status des Projekts
+
+Das Repository verfolgt einen inkrementellen, meilensteinbasierten Ausbau. Der aktuelle Produktstand baut auf einem vollständig implementierten Kern für:
+
+- Konfiguration und Startvalidierung
+- Quellordner-Scan und PDF-Textauslese
+- Fingerprint, SQLite-Persistenz und Idempotenz
+- KI-Integration für Benennungsvorschläge
+- Dateinamensbildung und Zielkopie
+- Retry-Logik, Logging und betriebliche Robustheit
+
+## Lizenz / Nutzung
+
+Falls für dieses Repository eine konkrete Lizenz vorgesehen ist, sollte sie hier ergänzt werden.