pdf-umbenenner/docs/specs/technik-und-architektur.md

Technik und Architektur – PDF-Umbenenner mit KI

Versionshinweis v2 Diese Fassung erweitert die KI-Anbindung um einen zweiten, gleichwertig unterstützten Provider. Geändert wurden ausschließlich die Abschnitte, die für die Mehrprovider-Fähigkeit erforderlich sind: Technologiestack (Abschnitt 5), KI-Integration (Abschnitt 11), Konfiguration (Abschnitt 14) sowie die Abschlussbewertung (Abschnitt 19). Alle übrigen Abschnitte bleiben inhaltlich unverändert.

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
• KI-HTTP-Clients (eine Implementierung je unterstütztem Provider, siehe Abschnitt 11)
• Properties-/Umgebungs-Konfiguration
• Run-Lock
• Clock

Bootstrap

Verantwortlich für:

• Laden und Validieren der Konfiguration
• Erzeugen des Objektgraphen
• Auswahl und Verdrahtung der einen aktiven KI-Provider-Implementierung
• Verdrahtung aller übrigen 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
• Java HTTP Client oder technisch gleichwertige Standard-HTTP-Komponente
• JSON-Bibliothek für robuste JSON-Serialisierung und -Validierung

Für die KI-Anbindung werden zwei gleichwertig unterstützte Provider-Familien technisch zugelassen:

• OpenAI-kompatible HTTP-Schnittstelle (Chat-Completions-Stil)
• native Anthropic Messages API für Claude-Modelle

Pro Lauf ist genau eine dieser Provider-Implementierungen aktiv. Die Auswahl erfolgt ausschließlich über Konfiguration (siehe Abschnitt 14).

Nicht verbindlich festgelegt sind:

• konkreter KI-Provider innerhalb einer Provider-Familie
• konkrete 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

Der AiNamingPort bleibt provider-neutral. Er kennt weder OpenAI- noch Anthropic-spezifische Typen, Header, URLs oder Antwortformate. Provider-spezifische Details (Endpunkt, Authentifizierung, Request-/Response-Format) leben ausschließlich in den jeweiligen Adapter-Out-Implementierungen.

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

Die Verarbeitungsschritte sind provider-unabhängig. Welcher konkrete KI-Adapter Schritt 9 ausführt, ist außerhalb der Application nicht sichtbar.

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

---

9. Retry- und Fehlersemantik

Inhaltlich unverändert gegenüber der Vorgängerfassung. Nur die Erkenntnis, dass technische KI-Fehler unabhängig vom konkreten Provider als transient klassifiziert werden, gilt jetzt für beide Provider-Familien gleichermaßen.

---

10. Identifikation und Reproduzierbarkeit

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 jeweilige API es zulässt, mit möglichst geringer Varianz konfiguriert
• Prompt-Version, Modellname und der Name des aktiven Providers werden persistiert

---

11. KI-Integration

11.1 Unterstützte Provider-Familien

Die KI wird über genau eine der folgenden Provider-Familien angebunden:

1. OpenAI-kompatible HTTP-Schnittstelle Chat-Completions-Stil. Geeignet für OpenAI selbst und für jeden API-kompatiblen Drittanbieter.
2. Native Anthropic Messages API Die offizielle Anthropic-Schnittstelle zur Nutzung von Claude-Modellen.

Pro Lauf ist genau ein Provider aktiv. Es gibt:

• keine automatische Fallback-Umschaltung
• keine parallele Nutzung mehrerer Provider in einem Lauf
• keine Profilverwaltung mit mehreren Konfigurationen je Provider-Familie

Die Auswahl erfolgt ausschließlich über Konfiguration. Ein Fehler des aktiven Providers ist und bleibt ein Fehler dieses einen Pfads und folgt der bestehenden Retry- und Fehlersemantik.

11.2 Architekturelle Einbettung

• Pro Provider-Familie existiert genau eine Implementierung des AiNamingPort im Modul pdf-umbenenner-adapter-out.
• Provider-spezifische Endpunkte, Header, Authentifizierungsverfahren, Request- und Response-Strukturen leben ausschließlich in der jeweiligen Adapter-Implementierung.
• Application und Domain bleiben provider-neutral. Sie kennen weder den Begriff „OpenAI" noch „Claude".
• Das Bootstrap-Modul wählt anhand der Konfiguration die eine aktive Implementierung aus und verdrahtet sie als AiNamingPort.
• Adapter dürfen nicht voneinander abhängen. Es gibt keinen gemeinsamen „abstrakten KI-Adapter" als Infrastrukturschicht zwischen Port und konkreten Adaptern.

11.3 Einheitlicher fachlicher Vertrag

Unabhängig vom aktiven Provider gilt derselbe fachliche Vertrag:

• gleicher fachlicher Input (Prompt, Textausschnitt, Modellbezug)
• gleicher fachlicher Output (Domain-Typ NamingProposal)
• gleiche Validierungs- und Folgeprozesse in der Application
• keine provider-spezifische Verzweigung im fachlichen Kern

Jede provider-spezifische Antwort wird im Adapter auf denselben Domain-Typ abgebildet. Eine Sonderbehandlung im Use-Case oder in der Domain ist unzulässig.

11.4 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
• derselbe Prompt wird providerübergreifend verwendet; provider-spezifische Anpassungen finden ausschließlich in der Adapter-Implementierung statt

11.5 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
• die Begrenzung gilt providerunabhängig

11.6 Antwortformat

Die KI muss – unabhängig vom aktiven Provider – fachlich 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

Wie der Adapter dieses Schema aus der jeweiligen Provider-Antwort extrahiert (z. B. aus choices[].message.content bei OpenAI-kompatiblen Schnittstellen oder aus dem Content-Block-Array der Anthropic Messages API), ist eine reine Adapter-Implementierungsfrage.

11.7 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

Diese Validierung ist provider-unabhängig und liegt in Application/Domain.

11.8 Fehlerklassifikation

Technische Fehler des aktiven Providers (HTTP-Fehler, Timeouts, ungültige Antwortstrukturen, Authentifizierungsfehler) werden im Adapter erkannt und auf die bestehende technische Fehlersemantik des Projekts abgebildet (transient vs. deterministisch). Es entsteht keine neue Fehlerkategorie. Der inaktive Provider wird in keiner Fehlersituation als Backup verwendet.

---

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

Das bestehende Schema bleibt erhalten. Es wird ausschließlich um die Information erweitert, welcher Provider den jeweiligen Versuch erzeugt hat (siehe 13.4). Eine neue Wahrheitsquelle entsteht nicht.

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
• Provider-Identifikator des aktiven KI-Providers für diesen Versuch
• Modellname
• Prompt-Identifikator
• verarbeitete Seitenzahl
• an KI gesendete Zeichenzahl
• KI-Rohantwort
• KI-Reasoning
• aufgelöstes Datum
• Datumstyp bzw. Datumsquelle
• finaler Titel
• finaler Zieldateiname

Der Provider-Identifikator macht jeden Versuch eindeutig nachvollziehbar einer Provider-Familie zuordenbar, ohne den fachlichen Vertrag zu verändern.

13.5 Sensible Inhalte

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

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

13.6 Rückwärtsverträglichkeit

Bestehende Datenbestände aus dem Stand vor v2 müssen weiterhin lesbar, fortschreibbar und korrekt interpretierbar bleiben. Schema-Erweiterungen erfolgen additiv und mit definierten Defaultwerten für historische Versuche ohne Provider-Identifikator.

---

14. Konfiguration

14.1 Format

Die technische Konfiguration erfolgt über .properties.

14.2 Provider-Auswahl

Genau ein Provider ist aktiv. Die Auswahl erfolgt über einen einzigen Pflichtparameter, der den aktiven Provider benennt. Zulässige Werte sind die Bezeichner der unterstützten Provider-Familien aus Abschnitt 11.1.

14.3 Mindestparameter

Verbindlich zweckmäßige Parameter:

• source.folder
• target.folder
• sqlite.file
• ai.provider.active – Auswahl des aktiven Providers (Pflicht)
• max.retries.transient
• max.pages
• max.text.characters
• prompt.template.file

Pro unterstützter Provider-Familie existiert ein eigener Parameter-Namensraum mit zweckmäßig mindestens:

• Modellname
• API-Schlüssel
• Timeout
• Basis-URL (optional, wo betrieblich sinnvoll)

Konkretes Schema (zweckmäßig, frei wählbare Bezeichner):

ai.provider.active=openai-compatible

ai.provider.openai-compatible.baseUrl=...
ai.provider.openai-compatible.model=...
ai.provider.openai-compatible.timeoutSeconds=...
ai.provider.openai-compatible.apiKey=...

ai.provider.claude.baseUrl=...
ai.provider.claude.model=...
ai.provider.claude.timeoutSeconds=...
ai.provider.claude.apiKey=...

Zusätzlich zweckmäßig:

• runtime.lock.file
• log.directory
• log.level
• log.ai.sensitive

14.4 API-Schlüssel

API-Schlüssel dürfen über Umgebungsvariable oder Properties geliefert werden.

Verbindlich:

• pro Provider-Familie existiert eine eigene definierte Umgebungsvariable
• die Umgebungsvariable hat Vorrang vor dem Properties-Wert derselben Provider-Familie
• Schlüssel verschiedener Provider-Familien werden niemals vermischt

14.5 Migration historischer Konfigurationen

Bestehende Properties-Dateien aus dem Stand vor v2 (mit flachen Schlüsseln wie api.baseUrl, api.model, api.timeoutSeconds, api.key) sind eine eindeutig erkennbare Legacy-Form.

Beim ersten Start mit erkannter Legacy-Form gilt verbindlich:

1. Legacy-Form erkennen
2. .bak-Sicherung der Originaldatei anlegen
3. Inhalt in das neue Schema überführen
   • die Legacy-Werte werden in den Namensraum der Provider-Familie openai-compatible überführt
   • ai.provider.active wird auf openai-compatible gesetzt
4. neue Datei schreiben (In-Place-Update)
5. Datei erneut laden und validieren
6. erst danach den normalen Lauf fortsetzen

Es ist kein Ziel, alte und neue Struktur dauerhaft gleichrangig als Endformat zu pflegen.

14.6 Konfigurationsvalidierung

Beim Start müssen alle Pflichtparameter validiert werden, insbesondere:

• ai.provider.active ist gesetzt und benennt einen unterstützten Provider
• für den aktiven Provider sind alle Pflichtwerte vorhanden und technisch konsistent
• für den inaktiven Provider werden keine Pflichtwerte erzwungen

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
• aktiver KI-Provider für den Lauf
• 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
• die Sensibilitätsregel gilt provider-unabhängig

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 (einschließlich fehlender oder unbekannter ai.provider.active)
• 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
• automatische Fallback-Umschaltung zwischen KI-Providern
• parallele Nutzung mehrerer KI-Provider in einem Lauf
• mehrere konkurrierende Konfigurationen je Provider-Familie (Profilverwaltung)
• Provider-Familien jenseits der in Abschnitt 11.1 explizit genannten

---

19. Abschlussbewertung

Der technische Zielstand ist mit den in dieser Fassung festgelegten Regeln:

• konsistent
• widerspruchsfrei
• hexagonal sauber geschnitten
• für einen minimalen produktiven PDF-Umbenenner zweckmäßig
• offen für genau zwei gleichwertig unterstützte KI-Provider-Familien, ohne den fachlichen Kern zu verändern

Besonders verbindlich geklärt sind:

• 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 inkl. Provider-Identifikator
• Exit-Code-Regel für harte Startfehler
• Unterstützung von OpenAI-kompatibler Schnittstelle und nativer Anthropic Messages API
• genau ein aktiver Provider pro Lauf, ohne Fallback
• Verlagerung technischer Persistenzobjekte aus der Domain heraus
• Migration historischer flacher Properties-Konfiguration mit .bak-Sicherung