marcus/pdf-umbenenner
1
0
Fork 0
Code Activity
Files
167b56bec505d3e9049a76307ed85fc63d7d25e8
pdf-umbenenner/docs/specs/technik-und-architektur.md

18 KiB
Raw Blame History

Technik und Architektur – PDF-Umbenenner mit KI

1. Ziel und Geltungsbereich

Dieses Dokument beschreibt die verbindliche technische Zielarchitektur für den PDF-Umbenenner.

Die Anwendung ist ein lokal gestartetes Java-Programm zur KI-gestützten Umbenennung bereits OCR-verarbeiteter, durchsuchbarer PDF-Dateien.

Sie liest PDF-Dateien aus einem konfigurierbaren Quellordner, ermittelt auf Basis des extrahierten Inhalts einen normierten Dateinamen und legt eine Kopie der Datei im konfigurierbaren Zielordner ab. Die Quelldatei bleibt unverändert.

Dieses Dokument beschreibt ausschließlich:

  • technische Architektur
  • technische Regeln und Schnittstellen
  • Persistenz- und Betriebsmodell
  • technische Konkretisierung fachlicher Vorgaben

Nicht Bestandteil dieses Dokuments sind:

  • Meilensteine
  • Projektplanung
  • manuelle Bedienkonzepte

2. Verbindliches Zielbild

2.1 Betriebsmodell

Die Anwendung ist verbindlich:

  • Java 21
  • Maven
  • ausführbares Standalone-JAR
  • Start über Windows Task Scheduler
  • kein Webserver
  • kein Applikationsserver
  • keine Dauerlauf-Anwendung
  • kein interner Scheduler

2.2 Verbindlicher Verarbeitungsausgang

Bei erfolgreicher Verarbeitung entsteht im Zielordner eine neue Datei im Format:

YYYY-MM-DD - Titel.pdf

Bei Namenskollisionen wird am Ende des Titels und direkt vor .pdf ein laufendes Suffix angehängt:

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

Dabei gilt:

  • die 20 Zeichen beziehen sich nur auf den Basistitel
  • das Dubletten-Suffix zählt nicht zu diesen 20 Zeichen
  • die Quelldatei wird nie überschrieben oder verändert

3. Architekturprinzipien

3.1 Strenge hexagonale Architektur

Die Anwendung wird strikt nach Ports and Adapters / Hexagonal Architecture umgesetzt.

Verbindliche Regeln:

  • Der Domain-Kern kennt keine Infrastruktur, keine Datenbank, kein Dateisystem und keine HTTP-Kommunikation.
  • Die Application-Schicht orchestriert Anwendungsfälle und enthält keine technischen Implementierungsdetails.
  • Jeder externe Zugriff erfolgt ausschließlich über Ports.
  • Konkrete technische Implementierungen sind Adapter.
  • Adapter dürfen nicht direkt voneinander abhängen.
  • Die Abhängigkeitsrichtung zeigt immer nach innen.

3.2 Technische Folgen

Es darf keine Vermischung geben zwischen:

  • Dateisystemzugriff
  • PDF-Auslese
  • SQLite-Persistenz
  • KI-HTTP-Kommunikation
  • Konfigurationsladen
  • Logging-Konfiguration
  • Benennungslogik
  • Retry-Entscheidungen

4. Maven- und Modulstruktur

4.1 Zielstruktur

Die Zielstruktur ist ein Maven-Multi-Module-Projekt mit mindestens folgenden Modulen:

  • pdf-umbenenner-domain
  • pdf-umbenenner-application
  • pdf-umbenenner-adapter-in-cli
  • pdf-umbenenner-adapter-out
  • pdf-umbenenner-bootstrap

Diese Struktur ist für das Projekt zweckmäßig, weil sie einerseits die Hexagonal-Architektur sauber abbildet und andererseits für eine kleine Batch-Anwendung noch überschaubar bleibt.

4.2 Modulverantwortung

Domain

Enthält ausschließlich fachliche und fachnah-technische Kernobjekte, zum Beispiel:

  • DocumentFingerprint
  • DocumentText
  • NamingProposal
  • ResolvedDate
  • ProcessingStatus
  • RetryDecision
  • FileNamingRules

Nicht in die Domain gehören:

  • Persistenzmodelle
  • SQLite-Entities
  • HTTP-DTOs
  • Log4j2-spezifische Klassen
  • Dateisystem-Klassen

Application

Enthält Use Cases und Orchestrierung, zum Beispiel:

  • RunBatchProcessingUseCase
  • ProcessSingleDocumentUseCase
  • GenerateFileNameUseCase
  • RecordProcessingAttemptUseCase
  • DetermineRetryDecisionUseCase

Adapter In

Enthält den Batch-/CLI-Einstiegspunkt.

Beispiel:

  • SchedulerBatchCommand

Adapter Out

Enthält technische Implementierungen der Outbound-Ports, insbesondere:

  • Dateisystem
  • PDFBox
  • SQLite
  • OpenAI-kompatibler HTTP-Client
  • Properties-/Umgebungs-Konfiguration
  • Run-Lock
  • Clock

Bootstrap

Verantwortlich für:

  • Laden und Validieren der Konfiguration
  • Erzeugen des Objektgraphen
  • Verdrahtung aller Adapter und Ports
  • Start des CLI-Adapters
  • Setzen des Exit-Codes

4.3 Maven-Basis

Zweckmäßige Maven-Grundlage:

  • Parent-POM mit packaging=pom
  • maven-compiler-plugin mit release=21
  • maven-surefire-plugin für Unit-Tests
  • maven-enforcer-plugin für Java-/Maven-Minimalversionen
  • maven-shade-plugin im Bootstrap-Modul zur Erzeugung des ausführbaren JARs

5. Technologiestack

Verbindlich eingesetzt werden:

  • Java 21
  • Maven
  • Apache PDFBox für PDF-Textauslese
  • SQLite als lokaler Persistenzspeicher
  • SQLite JDBC-Treiber
  • Log4j2 für Logging
  • OpenAI-kompatible HTTP-API für KI-Zugriff
  • Java HTTP Client oder technisch gleichwertige Standard-HTTP-Komponente
  • JSON-Bibliothek für robuste JSON-Serialisierung und -Validierung

Nicht verbindlich festgelegt sind:

  • konkreter KI-Provider
  • konkrete KI-Basis-URL
  • konkreter Modellname

Diese drei Punkte sind reine Konfiguration und ausdrücklich keine Architekturentscheidung.

6. Ports

6.1 Inbound-Port

Mindestens ein Inbound-Port ist verbindlich:

  • RunBatchProcessingUseCase

Optional kann die Application feiner geschnitten werden, zum Beispiel mit:

  • ProcessPendingDocumentsUseCase
  • ProcessSingleDocumentUseCase

6.2 Outbound-Ports

Verbindlich zweckmäßige Outbound-Ports:

  • SourceDocumentPort
  • PdfTextExtractionPort
  • FingerprintPort
  • ProcessedDocumentRepository
  • AiNamingPort
  • ConfigurationPort
  • RunLockPort
  • ClockPort

6.3 Logging

Logging ist kein fachlicher Port. Logging ist technische Infrastruktur.

7. Verarbeitungsmodell

7.1 Batch-Ablauf

Ein Lauf erfolgt in dieser Reihenfolge:

  1. Konfiguration laden
  2. Konfiguration validieren
  3. Run-Lock erwerben
  4. Quellordner lesen
  5. PDF-Dateien ermitteln
  6. Jede Datei einzeln verarbeiten
  7. Run-Lock freigeben
  8. Exit-Code setzen

7.2 Ablauf pro Datei

Die Verarbeitung einer einzelnen Datei erfolgt in dieser Reihenfolge:

  1. Fingerprint der Quelldatei berechnen
  2. Repository prüfen
  3. Erfolgreich verarbeitete Datei überspringen
  4. Final fehlgeschlagene Datei überspringen
  5. PDF-Text extrahieren
  6. Textqualität prüfen
  7. Seitenlimit prüfen
  8. Text für KI-Aufruf begrenzen und vorbereiten
  9. KI aufrufen
  10. KI-Antwort validieren
  11. Datum auflösen
  12. Titel validieren und technisch bereinigen
  13. finalen Dateinamen erzeugen
  14. Dubletten-Suffix bestimmen
  15. Datei in temporäre Zieldatei kopieren
  16. temporäre Zieldatei final verschieben/umbenennen
  17. Erfolg und Versuchshistorie persistent speichern

7.3 Erfolgskriterium

Ein Dokument gilt genau dann als erfolgreich verarbeitet, wenn:

  1. brauchbarer PDF-Text vorliegt,
  2. ein fachlich brauchbarer Titel vorliegt,
  3. ein Datum aufgelöst wurde,
  4. ein zulässiger Zielname erzeugt wurde,
  5. die Zielkopie erfolgreich geschrieben wurde,
  6. Status und Versuchshistorie erfolgreich persistiert wurden.

8. Dateinamensregeln

8.1 Zielformat

Das verbindliche Zielformat lautet:

YYYY-MM-DD - Titel.pdf

8.2 Datum

Die technische Auflösung folgt fachlich dieser Priorität:

  1. Rechnungsdatum
  2. Dokumentdatum
  3. anderes sinnvolles Dokumentdatum
  4. aktuelles Datum als Fallback

8.3 Technische Datumsregel

Die Anwendung setzt den Fallback auf das aktuelle Datum selbst, falls aus dem Dokument kein belastbares Datum ableitbar ist.

Daraus folgt:

  • die KI muss kein unsicheres Datum erfinden
  • ein fehlendes belastbares Dokumentdatum ist kein Fehlerfall
  • die Anwendung verwendet in diesem Fall den Wert aus ClockPort

8.4 Titel

Der Titel muss technisch diese Regeln erfüllen:

  • Deutsch
  • verständlich
  • eindeutig genug für den Dokumentkontext
  • maximal 20 Zeichen als Basistitel
  • keine unzulässigen Windows-Dateinamenzeichen
  • keine generischen Platzhalter wie z. B. Dokument, Datei, Scan, PDF
  • Eigennamen bleiben unverändert
  • Umlaute und ß bleiben erhalten, sofern dateisystemseitig zulässig

8.5 Dubletten

Bei Namenskollisionen wird das Suffix (n) unmittelbar vor .pdf angehängt.

Beispiele:

  • 2026-03-31 - Stromabrechnung.pdf
  • 2026-03-31 - Stromabrechnung(1).pdf
  • 2026-03-31 - Stromabrechnung(2).pdf

8.6 Windows-Kompatibilität

Die Anwendung stellt zusätzlich sicher, dass der Zielname für Windows zulässig ist.

Unzulässige Zeichen sind technisch zu entfernen oder kontrolliert zu ersetzen.

9. Fehlerklassifikation und Retry-Regeln

9.1 Grundsatz

Nur retryable Fehler dürfen in späteren Läufen erneut verarbeitet werden.

Finale Fehler werden in späteren Läufen übersprungen.

9.2 Deterministische Inhaltsfehler

Deterministische Inhaltsfehler sind insbesondere:

  • kein brauchbarer PDF-Text
  • Seitenlimit überschritten
  • Dokument inhaltlich mehrdeutig
  • kein brauchbarer Titel
  • generischer oder unzulässiger Titel
  • von der KI gelieferter Datumswert ist vorhanden, aber unbrauchbar oder nicht interpretierbar

Regel:

  • genau 1 Retry in einem späteren Scheduler-Lauf
  • danach finaler Fehler

9.3 Transiente technische Fehler

Transiente technische Fehler sind insbesondere:

  • KI nicht erreichbar
  • HTTP-Timeout
  • temporäre IO-Fehler
  • temporäre SQLite-Sperre
  • ungültiges oder nicht parsebares KI-JSON
  • sonstige vorübergehende technische Infrastrukturfehler

Regel:

  • Retry in späteren Läufen bis zum konfigurierten Maximalwert

9.4 Technischer Sofort-Wiederholversuch

Zusätzlich zulässig ist genau ein technischer Sofort-Wiederholversuch innerhalb desselben Laufs für den Zielkopiervorgang, wenn das Schreiben der Zieldatei fehlschlägt.

Dieser Mechanismus ist kein fachlicher Retry und wird getrennt vom laufübergreifenden Retry-Modell behandelt.

9.5 Statusmodell

Verbindlich zweckmäßige Statuswerte:

  • SUCCESS
  • FAILED_RETRYABLE
  • FAILED_FINAL
  • SKIPPED_ALREADY_PROCESSED
  • SKIPPED_FINAL_FAILURE

Ein technischer Zwischenstatus PROCESSING ist zusätzlich zulässig und sinnvoll.

10. Idempotenz und Identifikation

10.1 Identifikation

Die Identifikation eines Dokuments erfolgt nicht über den Dateinamen.

Verbindlicher Primärmechanismus:

  • SHA-256 der Quelldatei als stabiler Fingerprint

10.2 Wirkung

Daraus folgt:

  • bereits erfolgreich verarbeitete Dateien werden in späteren Läufen nicht erneut verarbeitet
  • final fehlgeschlagene Dateien werden in späteren Läufen übersprungen
  • geänderter Dateiinhalt erzeugt einen neuen Fingerprint und damit einen neuen fachlichen Vorgang

10.3 Determinismus und Reproduzierbarkeit

Reproduzierbarkeit bedeutet technisch:

  • nach einem erfolgreichen Lauf bleibt das gespeicherte Ergebnis stabil
  • erfolgreiche Dateien werden nicht erneut KI-basiert bewertet
  • KI-Aufrufe werden, soweit die API es zulässt, mit möglichst geringer Varianz konfiguriert
  • Prompt-Version und Modellname werden persistiert

11. KI-Integration

11.1 Schnittstelle

Die KI wird ausschließlich über eine OpenAI-kompatible HTTP-Schnittstelle angebunden.

Basis-URL, Modellname und API-Key sind reine Konfiguration.

11.2 Prompt

Der Prompt wird nicht im Code fest verdrahtet.

Verbindlich:

  • externe Prompt-Datei
  • Prompt-Version oder Prompt-Dateiname wird mitpersistiert
  • der Prompt darf die KI zur Ausgabe eines deutschen Titels anweisen

11.3 Textmenge

Es wird nicht zwingend der komplette extrahierte PDF-Text an die KI gesendet.

Verbindlich:

  • die maximale Zeichenzahl ist konfigurierbar
  • die Begrenzung muss vor dem KI-Aufruf technisch angewendet werden

11.4 Antwortformat

Die KI muss genau ein parsebares JSON-Objekt liefern.

Zweckmäßiges Schema:

{
  "date": "2026-02-11",
  "title": "Stromabrechnung",
  "reasoning": "..."
}

Regeln:

  • title ist verpflichtend
  • reasoning ist verpflichtend
  • date ist optional, wenn kein belastbares Datum ableitbar ist
  • liefert die KI kein date, setzt die Anwendung das aktuelle Datum als Fallback

11.5 Antwortvalidierung

Die Antwort gilt nur dann als technisch brauchbar, wenn:

  • JSON parsebar ist
  • title vorhanden ist
  • reasoning vorhanden ist

Zusätzlich gilt fachlich:

  • title muss validierbar und brauchbar sein
  • ein vorhandenes date muss im Format YYYY-MM-DD interpretierbar sein

12. PDF-Verarbeitung

12.1 Bibliothek

Für die PDF-Textauslese wird Apache PDFBox verwendet.

12.2 Voraussetzung

Die Anwendung setzt voraus, dass die PDFs bereits OCR-verarbeitet und durchsuchbar sind.

12.3 Kein brauchbarer Text

Wenn kein brauchbarer Text extrahiert werden kann:

  • erfolgt kein KI-Aufruf
  • der Fall wird als deterministischer Inhaltsfehler behandelt

12.4 Seitenlimit

Die maximal verarbeitbare Seitenzahl ist konfigurierbar.

Wird das Limit überschritten:

  • erfolgt kein KI-Aufruf
  • der Fall wird als deterministischer Inhaltsfehler behandelt

13. SQLite-Persistenzmodell

13.1 Ziel

SQLite ist der führende lokale Speicher für:

  • Bearbeitungsstatus
  • Retry-Informationen
  • Versuchshistorie
  • KI-Nachvollziehbarkeit
  • Ergebnisnachvollziehbarkeit

13.2 Persistenzmodell

Die Persistenz wird zweckmäßig in zwei Ebenen geführt:

  1. Dokument-Stammsatz pro Fingerprint
  2. Versuchshistorie mit einem Datensatz pro Verarbeitungsversuch

13.3 Dokument-Stammsatz

Mindestens zweckmäßig zu speichern:

  • interne ID
  • Fingerprint
  • letzter bekannter Quellpfad
  • letzter bekannter Quelldateiname
  • aktueller Gesamtstatus
  • letzter Zielpfad
  • letzter Zieldateiname
  • Anzahl bisheriger Inhaltsfehler
  • Anzahl bisheriger transienter Fehler
  • letzter Fehlerzeitpunkt
  • letzter Erfolgzeitpunkt
  • Erstellungszeitpunkt
  • Änderungszeitpunkt

13.4 Versuchshistorie

Für jeden Versuch separat zu speichern:

  • Versuchs-ID
  • Fingerprint-Referenz
  • Lauf-ID
  • Versuchsnummer
  • Startzeitpunkt
  • Endzeitpunkt
  • Ergebnisstatus
  • Fehlerklasse
  • Fehlermeldung
  • Retryable-Flag
  • Modellname
  • Prompt-Identifikator
  • verarbeitete Seitenzahl
  • an KI gesendete Zeichenzahl
  • KI-Rohantwort
  • KI-Reasoning
  • aufgelöstes Datum
  • Datumstyp bzw. Datumsquelle
  • finaler Titel
  • finaler Zieldateiname

13.5 Sensible Inhalte

Die vollständige KI-Rohantwort wird in SQLite gespeichert.

Sie soll standardmäßig nicht vollständig in Logdateien geschrieben werden.

14. Konfiguration

14.1 Format

Die technische Konfiguration erfolgt über .properties.

14.2 Mindestparameter

Verbindlich zweckmäßige Parameter:

  • source.folder
  • target.folder
  • sqlite.file
  • api.baseUrl
  • api.model
  • api.timeoutSeconds
  • max.retries.transient
  • max.pages
  • max.text.characters
  • prompt.template.file

Zusätzlich zweckmäßig:

  • runtime.lock.file
  • log.directory
  • log.level
  • api.key

14.3 API-Key

Der API-Key darf über Umgebungsvariable oder Properties geliefert werden.

Verbindlich:

  • Umgebungsvariable hat Vorrang

14.4 Konfigurationsvalidierung

Beim Start müssen alle Pflichtparameter validiert werden.

Bei ungültiger Startkonfiguration:

  • beginnt kein Verarbeitungslauf
  • wird ein Fehler geloggt
  • wird das Programm mit Exit-Code ungleich 0 beendet

15. Logging

15.1 Framework

Verbindlich ist Log4j2.

15.2 Mindestumfang

Das Logging muss mindestens enthalten:

  • Laufstart
  • Laufende
  • Lauf-ID
  • erkannte Quelldatei
  • Überspringen bereits erfolgreicher Dateien
  • Überspringen final fehlgeschlagener Dateien
  • erzeugter Zielname
  • Retry-Entscheidung
  • Fehler mit Klassifikation

15.3 Sensibilitätsregel

Standardmäßig gilt:

  • vollständige KI-Rohantwort nicht ins Log
  • vollständige KI-Rohantwort in SQLite
  • reasoning darf geloggt werden, sofern dies betrieblich gewünscht ist
  • die Ausgabe sensibler Inhalte muss konfigurierbar sein

15.4 Speicherort

Das Log-Verzeichnis ist konfigurierbar. Ohne explizite Konfiguration ist ein lokales logs/-Verzeichnis im Programmkontext zweckmäßig.

16. Startschutz und Parallelität

16.1 Verbindliche Regel

Wenn bereits eine laufende Instanz existiert:

  • beendet sich die neue Instanz sofort

16.2 Umsetzung

Zweckmäßig ist eine exklusive Lock-Datei über RunLockPort.

Der Pfad der Lock-Datei soll konfigurierbar sein.

16.3 Ziel

Der Startschutz verhindert:

  • konkurrierende SQLite-Zugriffe
  • kollidierende Zieldateikopien
  • inkonsistente Retry-Entscheidungen

17. Exit-Codes

Verbindliche Interpretation:

  • 0: Lauf wurde technisch ordnungsgemäß ausgeführt, auch wenn einzelne Dateien fachlich oder transient fehlgeschlagen sind
  • 1: Lauf konnte wegen hartem Start-/Bootstrap-Fehler nicht ordnungsgemäß beginnen oder fortgesetzt werden

Typische 1-Fälle:

  • ungültige Konfiguration
  • Run-Lock nicht erwerbbar
  • essentielle Ressourcen beim Start nicht verfügbar

18. Nicht-Ziele

Nicht Bestandteil dieser Architektur sind:

  • Web-UI
  • REST-API zur Bedienung
  • DMS-Funktionalität
  • OCR innerhalb der Java-Anwendung
  • automatische Löschung von Quelldateien
  • Verschiebung von Quelldateien statt Kopie
  • menschlicher Review-Workflow
  • interne Scheduler-Logik
  • fachliche Identifikation über Dateinamen

19. Abschlussbewertung

Der technische Zielstand ist mit den hier festgelegten Regeln:

  • konsistent
  • widerspruchsfrei
  • hexagonal sauber geschnitten
  • für einen minimalen produktiven PDF-Umbenenner zweckmäßig

Besonders verbindlich geklärt sind jetzt:

  • Dateinamensformat mit YYYY-MM-DD - Titel.pdf
  • Dublettenregel mit (1), (2), ...
  • Trennung zwischen finalen und retrybaren Fehlern
  • Fallback-Datum durch die Anwendung
  • Zwei-Ebenen-Persistenz mit Versuchshistorie
  • Exit-Code-Regel für harte Startfehler
  • OpenAI-kompatible Schnittstelle ohne fest verdrahteten Provider
  • Verlagerung technischer Persistenzobjekte aus der Domain heraus
View Git Blame Copy Permalink