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