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