pdf-umbenenner/docs/specs/meilensteine.md

# Meilensteine – KI-gestützte Umbenennung OCR-verarbeiteter PDFs

## Grundsätze für alle Meilensteine

- Jeder Meilenstein liefert einen **in sich geschlossenen, lauffähigen Entwicklungsstand**.
- Jeder Meilenstein umfasst **Implementierung, Konfiguration, JavaDoc und Tests**, soweit für den jeweiligen Stand sinnvoll.
- Die Lösung wird von Beginn an in **strenger hexagonaler Architektur** umgesetzt.
- Jeder Meilenstein baut auf dem vorherigen Stand auf, ohne Architekturbrüche oder provisorische Seiteneffekte zu erzeugen.
- Die Meilensteine bilden zusammen vollständig die fachlichen Anforderungen sowie das technische Zielbild ab.
- Fachliche Entscheidungen werden nicht in technische Adapter verschoben, technische Infrastruktur nicht in die Domain.

---

## M1 – Vollständiges Maven-Projekt und technisches Grundgerüst

### Ziel
Erstellung eines vollständig lauffähigen Multi-Modul-Maven-Projekts als stabile Basis der Gesamtentwicklung.

### Inhalt
- vollständige Maven-Projektstruktur in strenger Hexagonal-Architektur erstellen:
  - `domain`
  - `application`
  - `adapter-in`
  - `adapter-out`
  - `bootstrap`
- Parent-POM mit `packaging=pom` anlegen
- Modul-POMs vollständig konfigurieren
- alle benötigten Dependencies fest einbinden, insbesondere für:
  - Log4j2
  - Apache PDFBox
  - SQLite JDBC
  - OpenAI-kompatiblen HTTP-Zugriff
  - JSON-Verarbeitung
  - Test-Frameworks
- benötigte Maven-Plugins vollständig konfigurieren, insbesondere für:
  - Compiler
  - Surefire
  - Enforcer
  - Shade im Bootstrap-Modul
- Logging-Konfiguration mit Log4j2 anlegen
- lauffähigen Bootstrap-Einstiegspunkt bereitstellen
- `.properties`-Konfiguration grundlegend laden
- Grundvalidierung der Startkonfiguration vorsehen
- Build-, Start- und Testfähigkeit herstellen

### Lauffähiger Stand
- das Projekt baut vollständig mit Maven
- das ausführbare JAR startet erfolgreich
- Logging funktioniert
- Konfiguration wird geladen oder sauber validiert
- das Programm beendet sich kontrolliert ohne fachliche Verarbeitung

### Tests
- Build-/Smoke-Test für Programmstart
- Tests für Konfigurationsladen und Grundvalidierung
- Tests für Logging-/Bootstrap-Grundverhalten, soweit sinnvoll

---

## M2 – Hexagonaler Kern, Batch-Startfall und Startschutz

### Ziel
Der fachliche Kern, der Batch-Einstieg und der technische Startschutz sind sauber modelliert, jedoch noch ohne vollständige Dokumentverarbeitung.

### Inhalt
- Domain-Objekte und Statusmodell anlegen
- zentrale Ports definieren
- zentralen Inbound-Use-Case für den Batch-Lauf implementieren
- CLI-/Batch-Adapter implementieren
- Bootstrap-Verdrahtung vervollständigen
- Run-Lock-Port und erste Lock-Implementierung einführen
- Lauf-ID-Konzept einführen
- Exit-Code-Grundverhalten vorbereiten:
  - `0` für technisch ordnungsgemäß ausgeführten Lauf
  - `1` für harte Start-/Bootstrap-Fehler
- JavaDoc für Architekturgrenzen, Ports und zentrale Typen ergänzen

### Lauffähiger Stand
- das Programm startet als Batch-Prozess
- Lauf-Sperre wird gesetzt und freigegeben
- eine zweite Instanz beendet sich kontrolliert sofort
- der Use-Case wird über den Inbound-Adapter erreicht
- Architekturgrenzen sind technisch sichtbar und eingehalten
- noch keine echte PDF-Verarbeitung, aber kontrollierter Batch-Ablauf vorhanden

### Tests
- Unit-Tests für Domain-Objekte und Statusmodell
- Tests für Lock-Verhalten
- Tests für Bootstrap- und Use-Case-Verdrahtung
- Tests für Exit-Code-Verhalten bei Startschutz- und Bootstrap-Fehlern, soweit in diesem Stand sinnvoll

---

## M3 – Dateisystemzugriff, Kandidatenermittlung und PDF-Textauslese

### Ziel
Der Batch-Prozess kann PDFs im Quellordner finden, fachlich als Verarbeitungskandidaten behandeln sowie Text und Seitenzahl extrahieren.

### Inhalt
- Dateisystem-Adapter für Quellordnerzugriff implementieren
- PDF-Dateifilter gemäß fachlicher Regeln umsetzen
- PDFBox-Adapter zur Textauslese implementieren
- Seitenzahlermittlung integrieren
- Prüfung auf „brauchbaren Text“ umsetzen
- konfigurierbares Seitenlimit einführen
- erste Dateiobjekte und Metadatenfluss im Use-Case herstellen
- sicherstellen, dass bei fehlendem brauchbarem Text oder überschrittenem Seitenlimit **kein KI-Aufruf** erfolgt
- JavaDoc für Adapter, Fehlerfälle und Kandidatenbegriff ergänzen

### Lauffähiger Stand
- das Programm scannt den Quellordner
- passende PDFs werden erkannt
- Text und Seitenzahl werden extrahiert
- Dateien ohne brauchbaren Text oder oberhalb des Seitenlimits werden erkannt und protokolliert
- diese Fälle werden als deterministische Inhaltsfehler behandelt
- noch keine KI-Anbindung und noch keine Ergebnisdatei

### Tests
- Unit-Tests für PDF-Filterlogik
- Tests für Textauslese und Seitenzahlerkennung
- Tests für Fehlerfälle „kein brauchbarer Text“ und „Seitenlimit überschritten“
- Tests dafür, dass in diesen Fehlerfällen kein KI-Aufruf stattfindet

---

## M4 – Fingerprint, SQLite-Persistenz und Idempotenz

### Ziel
Die Anwendung kann verarbeitete Dateien stabil wiedererkennen, Bearbeitungszustände dauerhaft speichern und jeden Verarbeitungsversuch nachvollziehbar historisieren.

### Inhalt
- Fingerprint-Port und SHA-256-basierte Implementierung einführen
- SQLite-Schema vollständig implementieren
- Persistenzmodell explizit in **zwei Ebenen** umsetzen:
  - Dokument-Stammsatz pro Fingerprint
  - Versuchshistorie mit einem Datensatz pro Verarbeitungsversuch
- Statusmodell persistent nutzbar machen
- Retry-Zähler und Fehlstatus speichern
- Regeln für „bereits erfolgreich verarbeitet“ und „final fehlgeschlagen“ umsetzen
- Versuchshistorie explizit mit mindestens folgenden technischen Metadaten anlegen:
  - Lauf-ID
  - Versuchsnummer
  - Start- und Endzeitpunkt
  - Ergebnisstatus
  - Fehlerklasse
  - Fehlermeldung bzw. fachliche/systemische Begründung
  - Retryable-Flag
- JavaDoc für Persistenzmodell, Statusübergänge und Idempotenz ergänzen

### Lauffähiger Stand
- das Programm erkennt identische Quelldateien über Fingerprint wieder
- erfolgreich verarbeitete Dateien werden in späteren Läufen übersprungen
- final fehlgeschlagene Dateien werden in späteren Läufen übersprungen
- Bearbeitungsstände werden in SQLite gespeichert
- jeder Verarbeitungsversuch wird separat historisiert
- der Batch-Lauf ist idempotent gegenüber Wiederholungen
- noch keine KI-Anbindung und noch keine Zielkopie

### Tests
- Unit-Tests für Fingerprint-Erzeugung
- Repository-Tests gegen SQLite
- Tests für Statusübergänge, Retry-Zähler und Skip-Logik
- Tests für Versuchshistorie pro Lauf und pro Versuch

---

## M5 – KI-Integration, Prompt-Bezug und validierter Benennungsvorschlag

### Ziel
Die Anwendung kann aus extrahiertem PDF-Text per KI einen validierten Benennungsvorschlag erzeugen und alle KI-bezogenen Nachvollziehbarkeitsdaten persistent festhalten.

### Inhalt
- externe Prompt-Datei laden und versionierbar anbinden
- OpenAI-kompatiblen HTTP-Adapter implementieren
- Basis-URL, Modellname, Timeout und API-Zugriff vollständig konfigurierbar machen
- Priorität Umgebungsvariable vor Properties für API-Key umsetzen
- Begrenzung des an die KI gesendeten Inhalts umsetzen
- parsebares JSON-Ergebnis mit `date`, `title`, `reasoning` verarbeiten
- Validierung umsetzen:
  - `title` ist verpflichtend
  - `reasoning` ist verpflichtend
  - `date` ist optional
- fachliche Validierung für Datum und Titel umsetzen
- falls die KI **kein** belastbares Datum liefert, den Fallback **durch die Anwendung** über die technische Uhr/Clock vorsehen
- unbrauchbare KI-Antworten als Fehlerfälle behandeln
- Versuchshistorie um KI-Nachvollziehbarkeit explizit erweitern, insbesondere um:
  - Modellname
  - Prompt-Identifikator oder Prompt-Dateiname
  - verarbeitete Seitenzahl
  - an KI gesendete Zeichenzahl
  - KI-Rohantwort
  - KI-Reasoning
  - aufgelöstes Datum
  - Datumsquelle
- JavaDoc für KI-Port, Antwortvalidierung und Datumsauflösung ergänzen

### Lauffähiger Stand
- das Programm kann für verarbeitbare PDFs einen gültigen Benennungsvorschlag erzeugen
- gültige und ungültige KI-Antworten werden korrekt unterschieden
- bei fehlendem belastbarem KI-Datum wird das Datum durch die Anwendung als Fallback aufgelöst
- KI-Nachvollziehbarkeit ist persistent gespeichert
- noch keine physische Zielkopie, aber der vollständige Benennungsvorschlag ist verfügbar und gespeichert

### Tests
- Unit-Tests für Response-Validierung
- Tests für Prompt-Laden und Konfigurationsauflösung
- Tests für Fehlerfälle wie Timeout, ungültiges JSON und unbrauchbaren Titel
- Tests für Datums-Fallback durch die Anwendung
- Mock-/Adapter-Tests für den KI-Port

---

## M6 – Dateinamensbildung, Dublettenbehandlung und Zielkopie

### Ziel
Der vollständige Erfolgspfad wird umgesetzt: Aus KI-Ergebnis und technischer Datumsauflösung wird ein zulässiger Zielname erzeugt und eine Kopie im Zielordner abgelegt.

### Inhalt
- technische Dateinamensbildung implementieren
- verbindliches Zielformat umsetzen: `YYYY-MM-DD - Titel.pdf`
- Windows-Zeichenbereinigung ergänzen
- Titellängenregel für den **Basistitel** umsetzen
- feste deutsche Titelregeln technisch absichern
- fachliche Titelregel „keine Sonderzeichen außer Leerzeichen“ technisch absichern
- Dubletten-Suffix `(1)`, `(2)` usw. implementieren
- Zielordnerprüfung und Zielpfadbildung vervollständigen
- Kopierlogik in den Zielordner implementieren
- temporäre Zieldatei mit finalem Rename bzw. atomisches Schreiben umsetzen, soweit möglich
- Erfolgsstatus erst nach erfolgreichem Schreiben **und** erfolgreicher Persistenz setzen
- finalen Zieldateinamen und Zielpfad persistent speichern
- JavaDoc für Dateinamensregeln, Dubletten und Zielerzeugung ergänzen

### Lauffähiger Stand
- das Programm verarbeitet PDFs Ende-zu-Ende erfolgreich
- bei Erfolg entsteht eine korrekt benannte Kopie im Zielordner
- die Quelldatei bleibt unverändert erhalten
- Dubletten werden korrekt ab `(1)` behandelt
- Erfolgsstatus, Zieldateiname und Zielpfad werden konsistent gespeichert

### Tests
- Unit-Tests für Dateinamensbildung und Dubletten-Suffixe
- Tests für technische Zeichenbereinigung
- Tests für Basistitel-Längenregel und Zielformat
- integrationsnahe Tests für Zielkopie und Erfolgsstatus

---

## M7 – Fehlerbehandlung, Retry-Logik, Logging und betriebliche Robustheit

### Ziel
Die Lösung wird robust gegen typische Fehlerfälle und verhält sich in wiederholten Task-Scheduler-Läufen stabil, nachvollziehbar und konsistent.

### Inhalt
- fachliche Retry-Logik über spätere Läufe vollständig umsetzen
- deterministische Inhaltsfehler mit genau **1 Retry** in späterem Lauf umsetzen
- transiente technische Fehler mit Retry bis zum konfigurierten Maximalwert umsetzen
- finalen Fehlerstatus nach Ausschöpfen der jeweiligen Retry-Regeln umsetzen
- Sofort-Wiederholversuch nur für Schreibfehler der Zielkopie implementieren
- Skip-Logik für bereits erfolgreich verarbeitete und final fehlgeschlagene Dateien vervollständigen
- Logging auf den final geforderten Mindestumfang bringen, insbesondere mit:
  - Laufstart
  - Laufende
  - Lauf-ID
  - erkannte Quelldatei
  - Überspringen bereits erfolgreicher Dateien
  - Überspringen final fehlgeschlagener Dateien
  - erzeugter Zielname
  - Retry-Entscheidung
  - Fehler mit Klassifikation
- Sensibilitätsregel für Logs umsetzen:
  - vollständige KI-Rohantwort standardmäßig **nicht** ins Log
  - vollständige KI-Rohantwort **in SQLite**
  - Ausgabe sensibler Inhalte konfigurierbar
- Exit-Code-Verhalten finalisieren:
  - `0` auch bei Teilfehlern einzelner Dateien, solange der Lauf technisch ordnungsgemäß ausgeführt wurde
  - `1` nur bei harten Start-/Bootstrap-Fehlern
- Konfigurationsvalidierung vervollständigen
- Fehlernachvollziehbarkeit in Logs und SQLite konsistent machen
- JavaDoc zu Fehlersemantik, Retry-Regeln, Exit-Codes und Logging ergänzen

### Lauffähiger Stand
- die Anwendung verhält sich in Erfolg, Teilfehlern und Endfehlern stabil
- wiederholte Scheduler-Läufe führen zu keinem inkonsistenten Verhalten
- Fehler einzelner Dateien blockieren nicht den Gesamtlauf
- Retry-Zähler, Endstatus und Überspringen funktionieren konsistent
- Exit-Code und Logging entsprechen dem definierten Betriebsmodell

### Tests
- Tests für Retry-Abläufe über mehrere Läufe
- Tests für finale Fehlerzustände
- Tests für Skip-Logik bei bereits verarbeiteten Dateien
- Tests für Sofort-Wiederholversuch bei Zielkopierfehlern
- Tests für Logging-Sensibilitätsregel, soweit automatisierbar
- Tests für Konfigurationsfehler und finales Exit-Code-Verhalten

---

## M8 – Abschlussmeilenstein: Qualitätssicherung, Feinschliff und vollständige Entwicklungsfreigabe

### Ziel
Die Entwicklung wird vollständig abgeschlossen und der Gesamtstand auf Produktionsreife innerhalb des definierten Projektumfangs gebracht.

### Inhalt
- Review aller Architekturgrenzen und Sicherstellung der strengen Hexagonal-Architektur
- Abgleich aller Meilenstein-Ergebnisse mit Fachlichkeit sowie Technik/Architektur
- letzte technische und fachliche Restlücken schließen
- JavaDoc vervollständigen
- Testabdeckung gezielt vervollständigen
- Konfigurationsbeispiel und Startdokumentation konsolidieren
- Logging- und Fehlermeldungen sprachlich und inhaltlich schärfen
- letzte Inkonsistenzen in Statusmodell, Persistenz und Adapterverhalten bereinigen
- End-to-End-Gesamtprüfung des vollständigen Soll-Ablaufs durchführen

### Lauffähiger Stand
- die Lösung ist innerhalb des definierten Umfangs vollständig implementiert
- alle Kernanforderungen aus Fachlichkeit sowie Technik/Architektur sind umgesetzt
- der Stand ist stabil, testbar, dokumentiert und für den geplanten Betrieb bereit

### Tests
- vollständige End-to-End-Tests, soweit im Projekt sinnvoll automatisierbar
- Regressionstests für Kernregeln
- Konsistenztests für Persistenz, Dateinamensbildung, Retry-Logik und Skip-Verhalten
- abschließende Smoke-Tests für Build, Start und Batch-Lauf

---

## Abschlussbewertung

Die Meilensteine sind mit diesem Stand:

- vollständig auf das fachliche Zielbild ausgerichtet
- mit dem technischen Architekturziel konsistent
- widerspruchsfrei und logisch aufeinander aufbauend
- für eine schrittweise produktive Umsetzung geeignet