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

```text
YYYY-MM-DD - Titel.pdf
```

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

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

Dabei gilt:
- die **konfigurierte maximale Titellänge** bezieht sich nur auf den **Basistitel**
- das Dubletten-Suffix zählt **nicht** zur konfigurierten Titellänge
- 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 (inkl. `FilesystemTargetFileRenameAdapter` für atomare Zieldatei-Umbenennung)
- PDFBox (Textauslese sowie direktes Seitenrendering für die GUI-Vorschau via `PDFRenderer.renderImageWithDPI`)
- 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`
- `TargetFileRenamePort`
- `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.

Der `TargetFileRenamePort` kapselt die atomare Umbenennung einer bereits kopierten Zieldatei.
Er wird vom Use Case `ManualFileRenameUseCase` genutzt und ist durch
`FilesystemTargetFileRenameAdapter` implementiert. Der Port-Vertrag enthält keine
`Path`- oder NIO-Typen in öffentlichen Signaturen; er arbeitet ausschließlich mit
Domain-Typen und String-basierten Dateinamen.

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

```text
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 die **konfigurierte Titellänge** als Basistitel (Default 60, gültiger Bereich 10..120)
- 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:

```json
{
  "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`
- `max.title.length`
- `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):

```properties
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
