pdf-umbenenner/README.md

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

> **V2.0:** Die Anwendung enthält ab V2.0 eine lokale JavaFX-Desktop-GUI als Standardstart.
> Die GUI dient der Konfiguration, Validierung und technischen Diagnose.
> Der headless Batch-Betrieb bleibt über `--headless` vollständig erhalten.
> Details zum Betrieb: [`docs/betrieb.md`](docs/betrieb.md)

## Zielbild

Der PDF-Umbenenner ist als schlanke, lokal gestartete Anwendung ausgelegt:

- **Java 21**
- **Maven Multi-Module**
- **ausführbares Standalone-JAR** (ein gemeinsames JAR für GUI und headless)
- **GUI-Standardstart** ab V2.0 (JavaFX-Desktop, offiziell Windows)
- **headless Betrieb** über `--headless`, z. B. für den **Windows Task Scheduler**
- **`--config <pfad>`** für GUI und headless
- **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-in-gui`
- `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.

**GUI-Standardstart** (öffnet die JavaFX-Desktop-Oberfläche):

```bash
java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar
```

**headless Betrieb** (Batch-/Scheduler-Start ohne GUI):

```bash
java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless
```

**Explizite Konfigurationsdatei** (für GUI und headless):

```bash
java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --config C:\Pfad\zur\config.properties
java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless --config C:\Pfad\zur\config.properties
```

Das JAR ist das einzige Distributionsartefakt und enthält JavaFX für den GUI-Start bereits
integriert. Ausführliche Build-, Packaging- und Starthinweise sowie Informationen zur JavaFX-
Integration und zum headless Betrieb befinden sich in [`docs/betrieb.md`](docs/betrieb.md).

## 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-v2_0.md`
- `docs/betrieb.md`
- `docs/gui-bedienanleitung.md`
- `docs/freigabe-v2_0.md`
- `docs/workpackages/...`

Empfohlene Leserichtung:

1. `CLAUDE.md`
2. technische Zielarchitektur
3. fachliche Anforderungen
4. Meilensteine
5. `docs/betrieb.md` für Betriebs- und Startdetails
6. `docs/gui-bedienanleitung.md` für die GUI-Bedienung
7. 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 (V2.0) 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 (OpenAI-kompatibel und Anthropic Claude)
- Dateinamensbildung und Zielkopie
- Retry-Logik, Logging und betriebliche Robustheit
- JavaFX-Desktop-GUI als Standardstart (Konfigurationseditor, Validierung, technische Tests)
- headless Batch-Betrieb über `--headless` (rückwärtskompatibel zu V1.x)

## Lizenz / Nutzung

Falls für dieses Repository eine konkrete Lizenz vorgesehen ist, sollte sie hier ergänzt werden.