M1-Fix: Exit-Code für ungültige Konfiguration auf 1 geändert

docs/specs/technik-und-architektur.md

@@ -0,0 +1,638 @@
+# 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:
+
+```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
+- 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:
+
+```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`
+
+### 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:
+
+```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
+
+### 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