196 lines
5.4 KiB
Markdown
196 lines
5.4 KiB
Markdown
# 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.
|