marcus/pdf-umbenenner
1
0
Fork 0
Code Activity
Files
67ab91cd7022d4b55eba9293179d065a9d3894ab
pdf-umbenenner/docs/betrieb.md
Marcus van Elst 5099ff4aca V1.1 Änderungen
2026-04-09 05:42:02 +02:00

12 KiB
Raw Blame History

Betriebsdokumentation – PDF Umbenenner

Zweck

Der PDF Umbenenner liest bereits OCR-verarbeitete, durchsuchbare PDF-Dateien aus einem konfigurierten Quellordner, ermittelt per KI-Aufruf einen normierten deutschen Dateinamen und legt eine Kopie im konfigurierten Zielordner ab. Die Quelldatei bleibt unverändert.

Voraussetzungen

  • Java 21 (JRE oder JDK)
  • Zugang zu einem OpenAI-kompatiblen KI-Dienst (API-Schlüssel erforderlich)
  • Quellordner mit OCR-verarbeiteten PDF-Dateien
  • Schreibzugriff auf Zielordner und Datenbankverzeichnis

Start des ausführbaren JAR

Das ausführbare JAR wird durch den Maven-Build im Verzeichnis pdf-umbenenner-bootstrap/target/ erzeugt:

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

Die Anwendung liest die Konfiguration aus config/application.properties relativ zum Arbeitsverzeichnis, in dem der Befehl ausgeführt wird.

Start über Windows Task Scheduler

Empfohlene Startsequenz für den Windows Task Scheduler:

  1. Aktion: Programm/Skript starten
  2. Programm: java
  3. Argumente: -jar C:\Pfad\zur\Installation\pdf-umbenenner-bootstrap\target\pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar
  4. Starten in: C:\Pfad\zur\Installation (muss das Verzeichnis mit config\application.properties und config\prompts\ enthalten)

Hinweis: Das „Starten in"-Verzeichnis ist das Arbeitsverzeichnis der Anwendung. Die Konfigurationsdatei config/application.properties sowie das Prompt-Verzeichnis config/prompts/ müssen relativ zu diesem Verzeichnis erreichbar sein. Der JAR-Pfad in den Argumenten muss absolut oder relativ zum Starten-in-Verzeichnis korrekt angegeben sein.

Konfiguration

Die Konfiguration wird aus config/application.properties geladen. Vorlagen für lokale und Test-Konfigurationen befinden sich in:

  • config/application-local.example.properties
  • config/application-test.example.properties

Pflichtparameter (allgemein)

Parameter Beschreibung
source.folder Quellordner mit OCR-PDFs (muss vorhanden und lesbar sein)
target.folder Zielordner für umbenannte Kopien (wird angelegt, wenn nicht vorhanden)
sqlite.file SQLite-Datenbankdatei (übergeordnetes Verzeichnis muss existieren)
ai.provider.active Aktiver KI-Provider: openai-compatible oder claude
max.retries.transient Maximale transiente Fehlversuche pro Dokument (ganzzahlig, >= 1)
max.pages Maximale Seitenzahl pro Dokument (ganzzahlig, > 0)
max.text.characters Maximale Zeichenanzahl des Dokumenttexts für KI-Anfragen (ganzzahlig, > 0)
prompt.template.file Pfad zur externen Prompt-Datei (muss vorhanden sein)

Provider-Parameter

Nur der aktive Provider muss vollständig konfiguriert sein. Der inaktive Provider wird nicht validiert.

OpenAI-kompatibler Provider (ai.provider.active=openai-compatible):

Parameter Beschreibung
ai.provider.openai-compatible.baseUrl Basis-URL des KI-Dienstes (z. B. https://api.openai.com/v1)
ai.provider.openai-compatible.model Modellname (z. B. gpt-4o-mini)
ai.provider.openai-compatible.timeoutSeconds HTTP-Timeout in Sekunden (ganzzahlig, > 0)
ai.provider.openai-compatible.apiKey API-Schlüssel (Umgebungsvariable OPENAI_COMPATIBLE_API_KEY hat Vorrang)

Anthropic Claude-Provider (ai.provider.active=claude):

Parameter Beschreibung
ai.provider.claude.baseUrl Basis-URL (optional; Standard: https://api.anthropic.com)
ai.provider.claude.model Modellname (z. B. claude-3-5-sonnet-20241022)
ai.provider.claude.timeoutSeconds HTTP-Timeout in Sekunden (ganzzahlig, > 0)
ai.provider.claude.apiKey API-Schlüssel (Umgebungsvariable ANTHROPIC_API_KEY hat Vorrang)

Optionale Parameter

Parameter Beschreibung Standard
runtime.lock.file Lock-Datei für Startschutz pdf-umbenenner.lock im Arbeitsverzeichnis
log.directory Log-Verzeichnis ./logs/
log.level Log-Level (DEBUG, INFO, WARN, ERROR) INFO
log.ai.sensitive KI-Rohantwort und Reasoning ins Log schreiben (true/false) false

API-Schlüssel

Pro Provider-Familie existiert eine eigene Umgebungsvariable, die Vorrang vor dem Properties-Wert hat:

Provider Umgebungsvariable
openai-compatible OPENAI_COMPATIBLE_API_KEY
claude ANTHROPIC_API_KEY

Schlüssel verschiedener Provider-Familien werden niemals vermischt.

Migration älterer Konfigurationsdateien

Ältere Konfigurationsdateien, die noch die flachen Schlüssel api.baseUrl, api.model, api.timeoutSeconds und api.key verwenden, werden beim ersten Start automatisch in das aktuelle Schema überführt.

Was passiert

  1. Die Anwendung erkennt die veraltete Form anhand der flachen api.*-Schlüssel.
  2. Vor jeder Änderung wird eine Sicherungskopie der Originaldatei angelegt:
    • Standardfall: config/application.properties.bak
    • Falls .bak bereits existiert: config/application.properties.bak.1, .bak.2, …
    • Bestehende Sicherungen werden niemals überschrieben.
  3. Die Datei wird in-place in das neue Schema überführt:
    • api.baseUrl → ai.provider.openai-compatible.baseUrl
    • api.model → ai.provider.openai-compatible.model
    • api.timeoutSeconds → ai.provider.openai-compatible.timeoutSeconds
    • api.key → ai.provider.openai-compatible.apiKey
    • ai.provider.active=openai-compatible wird ergänzt.
    • Alle übrigen Schlüssel bleiben unverändert.
  4. Die migrierte Datei wird über eine temporäre Datei (*.tmp) und atomischen Move/Rename geschrieben. Das Original wird niemals teilbeschrieben.
  5. Die migrierte Datei wird sofort neu eingelesen und validiert.

Bei Migrationsfehler

Schlägt die Validierung der migrierten Datei fehl, bricht die Anwendung mit Exit-Code 1 ab. Die Sicherungskopie (.bak) bleibt in diesem Fall erhalten und enthält die unveränderte Originaldatei. Die Konfiguration muss dann manuell korrigiert werden.

Betreiber-Hinweis

Die Umgebungsvariable PDF_UMBENENNER_API_KEY des Vorgängerstands wird nicht automatisch umbenannt. Falls dieser Wert bislang verwendet wurde, muss er auf OPENAI_COMPATIBLE_API_KEY umgestellt werden.

Prompt-Konfiguration

Der Prompt wird aus der in prompt.template.file konfigurierten externen Textdatei geladen. Der Dateiname der Prompt-Datei dient als Prompt-Identifikator in der Versuchshistorie (SQLite) und ermöglicht so die Nachvollziehbarkeit, welche Prompt-Version für welchen Verarbeitungsversuch verwendet wurde.

Eine Vorlage befindet sich in config/prompts/template.txt und kann direkt verwendet oder an den jeweiligen KI-Dienst angepasst werden.

Die Anwendung ergänzt den Prompt automatisch um:

  • einen Dokumenttext-Abschnitt
  • eine explizite JSON-Antwortspezifikation mit den Feldern title, reasoning und date

Der Prompt in template.txt muss deshalb keine JSON-Formatanweisung enthalten – nur den inhaltlichen Auftrag an die KI.

Zielformat

Jede erfolgreich verarbeitete PDF-Datei wird im Zielordner unter folgendem Namen abgelegt:

YYYY-MM-DD - Titel.pdf

Bei Namenskollisionen wird ein laufendes Suffix angehängt:

YYYY-MM-DD - Titel(1).pdf
YYYY-MM-DD - Titel(2).pdf

Das Suffix zählt nicht zu den 20 Zeichen des Basistitels.

Retry- und Skip-Verhalten

Dokumentstatus

Die folgende Tabelle beschreibt die persistenten Statuszustände der Dokument-Stammsätze in der SQLite-Datenbank. Diese Zustände sind nach Abschluss eines Verarbeitungsversuchs dauerhaft gespeichert.

Status Bedeutung
READY_FOR_AI Verarbeitbar, KI-Pfad noch nicht durchlaufen
PROPOSAL_READY KI-Benennungsvorschlag liegt vor, Zielkopie noch nicht geschrieben
SUCCESS Erfolgreich verarbeitet und kopiert (terminaler Endzustand)
FAILED_RETRYABLE Fehlgeschlagen, erneuter Versuch in späterem Lauf möglich
FAILED_FINAL Terminal fehlgeschlagen, wird nicht erneut verarbeitet
SKIPPED_ALREADY_PROCESSED Übersprungen – Dokument bereits erfolgreich verarbeitet
SKIPPED_FINAL_FAILURE Übersprungen – Dokument terminal fehlgeschlagen

Zusätzlich kennt das System den transienten Zustand PROCESSING, der während der aktiven Verarbeitung eines Dokuments im Stammsatz gesetzt werden kann. Er wird nach Abschluss des Verarbeitungsversuchs stets durch einen der obigen Zustände ersetzt und ist kein gültiger Endstatus in der Datenbank.

Retry-Regeln

Deterministische Inhaltsfehler (z. B. kein extrahierbarer Text, Seitenlimit überschritten, unbrauchbarer KI-Titel):

  • Erster Fehler → FAILED_RETRYABLE (ein Wiederholversuch in späterem Lauf erlaubt)
  • Zweiter Fehler → FAILED_FINAL (kein weiterer Versuch)

Transiente technische Fehler (z. B. KI nicht erreichbar, HTTP-Timeout):

  • Wiederholbar bis zum Grenzwert max.retries.transient
  • Bei Erreichen des Grenzwerts → FAILED_FINAL

Technischer Sofort-Wiederholversuch:

Bei einem Schreibfehler der Zielkopie wird innerhalb desselben Laufs exakt ein Sofort-Wiederholversuch unternommen. Dieser zählt nicht zum laufübergreifenden Fehlerzähler.

Logging

Logs werden in das konfigurierte log.directory geschrieben (Standard: ./logs/). Log-Rotation erfolgt täglich und bei Erreichen von 10 MB je Datei.

Sensible KI-Inhalte

Standardmäßig werden die vollständige KI-Rohantwort und das KI-Reasoning nicht ins Log geschrieben, sondern ausschließlich in der SQLite-Datenbank gespeichert.

Die Ausgabe kann für Diagnosezwecke mit log.ai.sensitive=true freigeschaltet werden. Erlaubte Werte: true oder false. Jeder andere Wert ist ungültig und verhindert den Start.

Exit-Codes

Code Bedeutung
0 Lauf technisch ordnungsgemäß ausgeführt (auch bei dokumentbezogenen Teilfehlern)
1 Harter Start- oder Bootstrap-Fehler (ungültige Konfiguration, Lock nicht erwerbbar, Schema-Initialisierungsfehler)

Dokumentbezogene Fehler einzelner PDF-Dateien führen nicht zu Exit-Code 1.

Startschutz (Parallelinstanzschutz)

Die Anwendung verwendet eine exklusive Lock-Datei, um parallele Instanzen zu verhindern. Wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort mit Exit-Code 1.

Der Pfad der Lock-Datei ist über runtime.lock.file konfigurierbar. Ohne Konfiguration wird pdf-umbenenner.lock im Arbeitsverzeichnis verwendet.

SQLite-Datenbank

Die SQLite-Datei enthält:

  • Dokument-Stammsätze: Gesamtstatus, Fehlerzähler, letzter Zieldateiname, Zeitstempel
  • Versuchshistorie: Jeder Verarbeitungsversuch mit Modell, Prompt-Identifikator, KI-Rohantwort, Reasoning, Datum, Titel und Fehlerstatus

Die Datenbank ist die führende Wahrheitsquelle für Bearbeitungsstatus und Nachvollziehbarkeit. Sie muss nicht manuell verwaltet werden – das Schema wird beim Start automatisch initialisiert.

Systemgrenzen

  • Nur OCR-verarbeitete, durchsuchbare PDF-Dateien werden verarbeitet
  • Keine eingebaute OCR-Funktion
  • Kein Web-UI, keine REST-API, keine interaktive Bedienung
  • Kein interner Scheduler – der Start erfolgt extern (z. B. Windows Task Scheduler)
  • Quelldateien werden nie überschrieben, verschoben oder gelöscht
  • Die Identifikation erfolgt über SHA-256-Fingerprint des Dateiinhalts, nicht über Dateinamen
View Git Blame Copy Permalink