703 lines
24 KiB
Markdown
703 lines
24 KiB
Markdown
# 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 **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:
|
||
|
||
```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 **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:
|
||
|
||
```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`
|
||
- `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
|