# 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