From 69b68b25acc2031c7cf479bceeef28e8b5362814 Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Thu, 2 Apr 2026 19:04:55 +0200 Subject: [PATCH] =?UTF-8?q?Arbeitspakete=20f=C3=BCr=20M4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/workpackages/M4 - Arbeitspakete.md | 516 ++++++++++++++++++++++++ 1 file changed, 516 insertions(+) create mode 100644 docs/workpackages/M4 - Arbeitspakete.md diff --git a/docs/workpackages/M4 - Arbeitspakete.md b/docs/workpackages/M4 - Arbeitspakete.md new file mode 100644 index 0000000..372ea7f --- /dev/null +++ b/docs/workpackages/M4 - Arbeitspakete.md @@ -0,0 +1,516 @@ +# M4 - Arbeitspakete + +## Geltungsbereich + +Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M4 – Fingerprint, SQLite-Persistenz und Idempotenz**. + +Die Meilensteine **M1**, **M2** und **M3** werden als vollständig umgesetzt vorausgesetzt. + +Die Arbeitspakete sind bewusst so geschnitten, dass: + +- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann, +- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann, +- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt. + +Die Reihenfolge der Arbeitspakete ist verbindlich. + +## Zusätzliche Schnittregeln für die KI-Bearbeitung + +- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter und Bootstrap ändern. +- Keine Annahmen treffen, die nicht durch dieses Dokument oder die verbindlichen Spezifikationen gedeckt sind. +- Kein Vorgriff auf **M5+**. +- Kein Umbau bestehender M1–M3-Strukturen ohne direkten M4-Bezug. +- Neue Typen, Ports und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind. + +## Explizit nicht Bestandteil von M4 + +- KI-Anbindung +- Prompt-Laden oder Prompt-Verarbeitung +- Validierung von KI-Antworten +- Dateinamensbildung +- Zielkopie in den Zielordner +- Windows-Zeichenbereinigung für Zieldateinamen +- physische Dublettenbehandlung im Zielordner +- M5+-Persistenzfelder wie Modellname, Prompt-Identifikator, KI-Rohantwort, KI-Reasoning, Datumsquelle, finaler Titel oder finaler Zieldateiname +- vollständige laufübergreifende Retry-Logik späterer Meilensteine für KI- und Zielkopie-Fehler +- Logging-Feinschliff des Endstands + +## Verbindliche M4-Regeln für **alle** Arbeitspakete + +### 1. Identifikation +- Die Identifikation eines Dokuments erfolgt in M4 **ausschließlich über den SHA-256-Fingerprint des Dateiinhalts**. +- Dateiname und Pfad dienen **nicht** als Identifikator. +- Gleicher Inhalt unter anderem Dateinamen oder anderem Pfad ist **dasselbe Dokument**. +- Geänderter Inhalt ist **ein neuer fachlicher Vorgang**. + +### 2. Persistenzmodell +M4 führt die Persistenz verbindlich in **zwei Ebenen**: + +1. **Dokument-Stammsatz** pro Fingerprint +2. **Versuchshistorie** mit einem Datensatz pro historisiertem dokumentbezogenem Verarbeitungsversuch + +### 3. Minimale Pflichtdaten im Dokument-Stammsatz für M4 +Im Dokument-Stammsatz müssen in M4 mindestens speicherbar sein: + +- interne ID +- Fingerprint +- letzter bekannter Quellpfad +- letzter bekannter Quelldateiname +- aktueller Gesamtstatus +- Anzahl bisheriger Inhaltsfehler +- Anzahl bisheriger transienter Fehler +- letzter Fehlerzeitpunkt +- letzter Erfolgzeitpunkt +- Erstellungszeitpunkt +- Änderungszeitpunkt + +**Nicht** Bestandteil von M4-Stammsatzfeldern sind Zielpfad, Zieldateiname oder KI-bezogene Felder. + +### 4. Minimale Pflichtdaten der Versuchshistorie für M4 +Für jeden in M4 zu historisierenden Versuch müssen mindestens speicherbar sein: + +- Versuchs-ID +- Fingerprint-Referenz +- Lauf-ID +- Versuchsnummer +- Startzeitpunkt +- Endzeitpunkt +- Ergebnisstatus +- Fehlerklasse +- Fehlermeldung bzw. Begründung +- Retryable-Flag + +### 5. Statusmodell für M4 +Für M4 müssen folgende Statuswerte fachlich klar verwendbar sein: + +- `SUCCESS` +- `FAILED_RETRYABLE` +- `FAILED_FINAL` +- `SKIPPED_ALREADY_PROCESSED` +- `SKIPPED_FINAL_FAILURE` + +Ein technischer Zwischenstatus `PROCESSING` ist zusätzlich zulässig, aber für M4 nicht verpflichtend. + +### 6. Verbindliche M4-Minimalregeln für Status und Zähler +Für M4 gelten **genau** diese Minimalregeln: + +- Bereits erfolgreich verarbeitete Dokumente werden in späteren Läufen übersprungen. +- Bereits final fehlgeschlagene Dokumente werden in späteren Läufen übersprungen. +- Ein **deterministischer Inhaltsfehler aus M3** + - beim **ersten** historisierten Auftreten führt zu `FAILED_RETRYABLE`, erhöht den **Inhaltsfehlerzähler** auf 1 und setzt `retryable = true`, + - beim **zweiten** historisierten Auftreten in einem späteren Lauf führt zu `FAILED_FINAL`, erhöht den **Inhaltsfehlerzähler** auf 2 und setzt `retryable = false`. +- In M4 sind die deterministischen Inhaltsfehler ausschließlich die bereits aus M3 bekannten Fälle: + - kein brauchbarer Text + - Seitenlimit überschritten +- Dokumentbezogene **technische** Fehler nach erfolgreicher Fingerprint-Ermittlung bleiben in M4 `FAILED_RETRYABLE`, erhöhen den **Transientfehlerzähler** und setzen `retryable = true`. +- Skip-Ereignisse ändern **keinen** Fehlerzähler. + +### 7. Historisierung in M4 +- Jeder **identifizierte** dokumentbezogene Verarbeitungsversuch wird separat historisiert. +- Die Versuchsnummer beginnt pro Fingerprint bei **1** und steigt pro historisiertem Versuch monoton um **1**. +- Auch Skip-Fälle werden historisiert: + - `SKIPPED_ALREADY_PROCESSED` + - `SKIPPED_FINAL_FAILURE` +- Ein in M4 historisierter Versuch setzt einen **erfolgreich ermittelten Fingerprint** voraus. +- Technische Fehler **vor** erfolgreicher Fingerprint-Ermittlung sind in M4 **keine** SQLite-historisierten Versuche; sie werden nur kontrolliert als dokumentbezogene Laufereignisse behandelt. + +### 8. Reihenfolge pro Dokument in M4 +Die Verarbeitung eines einzelnen Kandidaten erfolgt in M4 verbindlich in dieser Reihenfolge: + +1. Fingerprint berechnen +2. Dokument-Stammsatz laden +3. bei `SUCCESS` Skip-Entscheidung treffen und Skip-Versuch historisieren +4. bei `FAILED_FINAL` Skip-Entscheidung treffen und Skip-Versuch historisieren +5. sonst bestehenden M3-Ablauf ausführen +6. M3-Ergebnis in M4-Status, Zähler und Retryable-Flag überführen +7. Versuch historisieren +8. Dokument-Stammsatz fortschreiben + +### 9. Konsistenz pro identifiziertem Dokument +- Für jeden identifizierten dokumentbezogenen Versuch müssen **Versuchshistorie und Stammsatz konsistent** fortgeschrieben werden. +- Teilaktualisierungen zwischen Historie und Stammsatz sind zu vermeiden. +- Wenn die Persistenz eines dokumentbezogenen Versuchs technisch scheitert, darf **kein inkonsistenter Teilzustand** zurückbleiben. + +### 10. Schema-Initialisierung +- Die Initialisierung des SQLite-Schemas erfolgt in M4 **beim Programmstart**, bevor der Batch-Lauf mit der Dokumentverarbeitung beginnt. +- Eine nur implizite oder ausschließlich lazy Initialisierung während des laufenden Dokumentdurchsatzes ist **nicht** Ziel von M4. + +--- + +## AP-001 M4-Kernobjekte, Statussemantik und Port-Verträge präzisieren + +### Voraussetzung +Keine. Dieses Arbeitspaket ist der M4-Startpunkt. + +### Ziel +Die M4-relevanten Typen, Statusbedeutungen und Port-Verträge werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können. + +### Muss umgesetzt werden +- Neue M4-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für: + - Dokument-Fingerprint + - Dokument-Stammsatz + - Verarbeitungsversuch + - Fehlerzählerstände + - dokumentbezogene Persistenzentscheidung bzw. Lookup-Ergebnis + - technische Fehlerklassifikation für dokumentbezogene M4-Verarbeitung +- Statusmodell so vervollständigen oder schärfen, dass die verbindlichen M4-Statuswerte fachlich eindeutig abbildbar sind. +- Eindeutige Semantik für folgende Fälle im Typmodell bzw. in JavaDoc festlegen: + - unbekanntes Dokument + - bekanntes, noch nicht terminales Dokument + - bereits erfolgreiches Dokument + - bereits final fehlgeschlagenes Dokument + - historisierbarer dokumentbezogener Versuch + - nicht historisierbarer Vor-Fingerprint-Fehler +- Outbound-Ports definieren für: + - Erzeugung eines Fingerprints für genau einen Verarbeitungskandidaten + - Lesen und Schreiben des Dokument-Stammsatzes + - Schreiben und Lesen der Versuchshistorie + - technische Initialisierung des SQLite-Schemas +- Port-Verträge so schneiden, dass **weder `Path`/`File` noch JDBC-/SQLite-Typen** in Domain oder Application durchsickern. +- Port-Rückgaben so modellieren, dass spätere Arbeitspakete ohne zusätzliche Annahmen unterscheiden können: + - Dokument unbekannt + - Dokument bekannt und aktiv weiter zu verarbeiten + - Dokument terminal erfolgreich + - Dokument terminal final fehlgeschlagen + - technischer Persistenzfehler +- JavaDoc und `package-info` für: + - Statusbedeutungen + - Zählersemantik + - Historisierungsgrenzen + - Architekturgrenzen + ergänzen. + +### Explizit nicht Teil +- SHA-256-Implementierung +- SQLite-Implementierung +- konkrete SQL-Tabellen +- Batch-Integration +- Repository-Code + +### Fertig wenn +- die M4-relevanten Typen und Port-Verträge vorhanden sind, +- die M4-Statussemantik eindeutig dokumentiert ist, +- Historisierung vs. Vor-Fingerprint-Fehler klar abgegrenzt ist, +- Domain und Application frei von Infrastrukturtypen bleiben, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-002 SHA-256-Fingerprint-Adapter für Verarbeitungskandidaten implementieren + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Für jeden Verarbeitungskandidaten kann ein stabiler, deterministischer SHA-256-Fingerprint erzeugt werden; technische Probleme werden kontrolliert in den Port-Vertrag überführt. + +### Muss umgesetzt werden +- Fingerprint-Port technisch im Adapter-Out implementieren. +- SHA-256-basierte Fingerprint-Erzeugung für genau einen Verarbeitungskandidaten umsetzen. +- Sicherstellen, dass der Fingerprint ausschließlich aus dem **Dateiinhalt** abgeleitet wird. +- Kontrolliertes technisches Fehlerverhalten für mindestens folgende Fälle abbilden: + - Datei nicht lesbar + - Datei zwischen Kandidatenermittlung und Fingerprint-Erzeugung nicht mehr vorhanden + - sonstige technische IO-Probleme +- Sicherstellen, dass Dateisystem- und Hashing-Details ausschließlich im Adapter-Out verbleiben. +- JavaDoc für Determinismus, Fehlerverhalten und M4-Grenze ergänzen, dass Vor-Fingerprint-Fehler **nicht** als SQLite-historisierte Versuche gelten. + +### Explizit nicht Teil +- SQLite-Persistenz +- Batch-Orchestrierung +- Versuchshistorie +- Skip-Logik +- Zählerfortschreibung + +### Fertig wenn +- für denselben Dateiinhalt stabil derselbe SHA-256-Fingerprint erzeugt wird, +- Fingerprint und Fehler kontrolliert über den Port geliefert werden, +- keine Hashing- oder Dateisystemdetails in Domain oder Application durchsickern, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-003 SQLite-Schema, Start-Initialisierung und Persistenzbasis im Adapter-Out einführen + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Die SQLite-basierte Persistenzgrundlage für M4 wird technisch sauber eingeführt und beim Programmstart kontrolliert initialisiert. + +### Muss umgesetzt werden +- SQLite-Dateizugriff im Adapter-Out technisch einführen. +- Technischen Initialisierungsbaustein für SQLite-Schema anlegen und über den dafür vorgesehenen Port anbinden. +- M4-Schema explizit in **zwei Ebenen** anlegen: + - Dokument-Stammsatz + - Versuchshistorie +- Tabellen, Primärschlüssel, Fremdschlüssel, Unique-Regeln und sinnvolle Indizes für den M4-Stand definieren. +- Dokument-Stammsatz so anlegen, dass die in diesem Dokument festgelegten M4-Pflichtfelder speicherbar sind. +- Versuchshistorie so anlegen, dass die in diesem Dokument festgelegten M4-Pflichtfelder speicherbar sind. +- Sicherstellen, dass: + - Versuchsnummer pro Fingerprint eindeutig ist, + - Skip-Versuche speicherbar sind, + - keine M5+-Spalten angelegt werden. +- Die Schema-Initialisierung so vorbereiten, dass sie **beim Programmstart** explizit aufgerufen werden kann. +- JavaDoc für Schema-Zweck, Zwei-Ebenen-Modell und Initialisierungszeitpunkt ergänzen. + +### Explizit nicht Teil +- Repository-Fachlogik +- Use-Case-Integration +- Statusübergänge im Batch-Lauf +- KI-bezogene Persistenzfelder +- Zielpfad- oder Dateinamenspersistenz + +### Fertig wenn +- die SQLite-Datei und das M4-Schema technisch anlegbar sind, +- beide Persistenzebenen den M4-Pflichtumfang abbilden, +- die Start-Initialisierung technisch vorbereitet ist, +- keine M5+-Felder im Schema enthalten sind, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-004 Repository für Dokument-Stammsatz mit vollständigem M4-Minimalumfang implementieren + +### Voraussetzung +AP-003 ist abgeschlossen. + +### Ziel +Der Dokument-Stammsatz kann pro Fingerprint zuverlässig gelesen, angelegt und fortgeschrieben werden, ohne fachliche Entscheidungslogik in den Adapter-Out zu verlagern. + +### Muss umgesetzt werden +- Repository-Adapter für den Dokument-Stammsatz implementieren. +- Folgende technischen Fähigkeiten bereitstellen: + - Suche eines Stammsatzes über Fingerprint + - Neuanlage eines Stammsatzes für bisher unbekannte Dokumente + - Fortschreibung von: + - letztem bekanntem Quellpfad + - letztem bekanntem Quelldateinamen + - Gesamtstatus + - Inhaltsfehlerzähler + - Transientfehlerzähler + - letztem Fehlerzeitpunkt + - letztem Erfolgzeitpunkt + - Änderungszeitpunkt +- Sicherstellen, dass die Repository-Operationen **keine** fachlichen Entscheidungen über Retry-Regeln oder Skip-Logik treffen. +- Mapping zwischen Application-Typen und SQLite-Struktur explizit und nachvollziehbar halten. +- Upsert-/Neuanlageverhalten für den M4-Einzelprozess reproduzierbar modellieren. +- JavaDoc für Verantwortlichkeit und Mapping ergänzen. + +### Explizit nicht Teil +- Versuchshistorie +- Batch-Skip-Logik +- Versuchsnummernvergabe +- konkrete Statusentscheidungen im Use-Case +- KI- oder Zielkopie-bezogene Persistenz + +### Fertig wenn +- der Dokument-Stammsatz pro Fingerprint zuverlässig gelesen und geschrieben werden kann, +- alle M4-Pflichtfelder des Stammsatzes technisch fortschreibbar sind, +- fachliche Entscheidungen nicht in das Repository abgerutscht sind, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-005 Repository für Versuchshistorie mit monotoner Versuchsnummer implementieren + +### Voraussetzung +AP-003 ist abgeschlossen. + +### Ziel +Jeder historisierbare dokumentbezogene M4-Versuch kann separat und nachvollziehbar persistiert werden. + +### Muss umgesetzt werden +- Repository-Adapter für die Versuchshistorie implementieren. +- Schreiben genau eines Versuchseintrags pro historisiertem dokumentbezogenem M4-Versuch umsetzen. +- Lesefähigkeiten bereitstellen, soweit sie für M4-Use-Case und Tests benötigt werden. +- Versuchsnummern pro Fingerprint reproduzierbar ableiten oder fortschreiben. +- Sicherstellen, dass die Versuchsnummer: + - bei **1** beginnt, + - pro Fingerprint monoton steigt, + - auch bei Skip-Versuchen mitgezählt wird. +- M4-relevante Historisierungsdaten persistieren: + - Fingerprint-Referenz + - Lauf-ID + - Versuchsnummer + - Startzeitpunkt + - Endzeitpunkt + - Ergebnisstatus + - Fehlerklasse + - Fehlermeldung bzw. Begründung + - Retryable-Flag +- Sicherstellen, dass nur **identifizierte** Dokumente historisiert werden. +- JavaDoc für Historisierungszweck, Versuchsnummernlogik und M4-Grenzen ergänzen. + +### Explizit nicht Teil +- Dokument-Stammsatz +- fachliche Zählerlogik +- Batch-Orchestrierung +- KI-Rohantwort, Modellname oder Prompt-Identifikator +- Zielname, Zielpfad oder Zielkopie + +### Fertig wenn +- pro historisiertem dokumentbezogenem Verarbeitungsvorgang ein separater Versuchseintrag gespeichert werden kann, +- die Versuchsnummern pro Fingerprint reproduzierbar und monoton sind, +- Skip-Versuche historisierbar sind, +- Vor-Fingerprint-Fehler nicht fälschlich historisiert werden, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-006 M4-Entscheidungslogik und Batch-Integration für Idempotenz, Zähler und konsistente Persistenz umsetzen + +### Voraussetzung +AP-001 bis AP-005 sind abgeschlossen. + +### Ziel +Der bestehende M3-Verarbeitungslauf wird zu einem echten M4-Lauf erweitert, der Dokumente über Fingerprint wiedererkennt, Status und Zähler korrekt fortschreibt, Skip-Fälle historisiert und dabei keinen inkonsistenten Persistenzzustand hinterlässt. + +### Muss umgesetzt werden +- Den bestehenden Batch-Use-Case so erweitern, dass pro Verarbeitungskandidat verbindlich diese Reihenfolge gilt: + 1. Fingerprint erzeugen + 2. Dokument-Stammsatz laden + 3. terminale Fälle entscheiden + 4. gegebenenfalls bestehenden M3-Ablauf ausführen + 5. Ergebnis in M4-Status, Zähler und Retryable-Flag überführen + 6. Versuch historisieren + 7. Dokument-Stammsatz fortschreiben +- Folgende M4-Regeln explizit umsetzen: + - vorhandener Gesamtstatus `SUCCESS` → Dokument wird nicht erneut fachlich verarbeitet, sondern mit `SKIPPED_ALREADY_PROCESSED` historisiert + - vorhandener Gesamtstatus `FAILED_FINAL` → Dokument wird nicht erneut fachlich verarbeitet, sondern mit `SKIPPED_FINAL_FAILURE` historisiert + - unbekanntes oder noch nicht terminales Dokument wird regulär weiterverarbeitet +- M3-Ergebnisse exakt wie folgt in M4 überführen: + - M3 erfolgreich abgeschlossen → `SUCCESS`, keine Fehlerzähler erhöhen, `retryable = false` + - M3-Inhaltsfehler „kein brauchbarer Text“ oder „Seitenlimit überschritten“ beim ersten historisierten Auftreten → `FAILED_RETRYABLE`, Inhaltsfehlerzähler +1, `retryable = true` + - derselbe Dokumenttyp eines bereits identifizierten Dokuments mit erneutem deterministischen Inhaltsfehler in einem späteren Lauf → `FAILED_FINAL`, Inhaltsfehlerzähler +1, `retryable = false` + - dokumentbezogener technischer Fehler nach erfolgreicher Fingerprint-Ermittlung → `FAILED_RETRYABLE`, Transientfehlerzähler +1, `retryable = true` +- Skip-Fälle so behandeln, dass: + - ein eigener Versuchseintrag geschrieben wird, + - kein Fehlerzähler verändert wird, + - der Gesamtstatus des Stammsatzes terminal bestehen bleibt. +- Vor-Fingerprint-Fehler ausdrücklich **nicht** als SQLite-Versuch historisieren. +- Für identifizierte Dokumente sicherstellen, dass **Historie und Stammsatz konsistent** fortgeschrieben werden und keine inkonsistenten Teilzustände entstehen. +- Falls eine dokumentbezogene Persistenzoperation technisch scheitert: + - darf kein teilaktualisierter Zustand zurückbleiben, + - bleibt der Batch-Lauf für andere Dokumente kontrolliert weiter lauffähig, + - wird kein M5+-Verhalten vorweggenommen. +- JavaDoc für Idempotenz, Zählerfortschreibung, Skip-Semantik und Persistenzkonsistenz ergänzen. + +### Explizit nicht Teil +- KI-Aufruf +- Dateinamensbildung +- Zielkopie +- M5+-Retry-Regeln für KI- oder Zielkopiefehler +- M5+-Persistenzfelder +- spätere Reporting- oder Auswertungslogik + +### Fertig wenn +- der Batch-Lauf identische Inhalte über Fingerprint wiedererkennt, +- `SUCCESS`- und `FAILED_FINAL`-Dokumente in späteren Läufen historisiert übersprungen werden, +- die Minimalregel „erster deterministischer Inhaltsfehler retryable, zweiter final“ explizit umgesetzt ist, +- technische dokumentbezogene Fehler nach Fingerprint als retryable behandelt werden, +- Historie und Stammsatz pro identifiziertem Dokument konsistent fortgeschrieben werden, +- weiterhin keine M5+-Funktionalität enthalten ist. + +--- + +## AP-007 Bootstrap- und CLI-Anpassungen für SQLite-Konfiguration, Start-Initialisierung und M4-Verdrahtung durchführen + +### Voraussetzung +AP-001 bis AP-006 sind abgeschlossen. + +### Ziel +Der Programmeinstieg ist sauber an den M4-Lauf angepasst; die Persistenz wird beim Start initialisiert und die neuen M4-Bausteine sind vollständig verdrahtet. + +### Muss umgesetzt werden +- Bootstrap-Verdrahtung auf die neuen M4-Ports, Adapter und Persistenzbausteine erweitern. +- M4-relevante Konfiguration ergänzen bzw. verdrahten, insbesondere für: + - `sqlite.file` +- Startvalidierung so ergänzen, dass mindestens geprüft wird: + - SQLite-Dateipfad ist vorhanden oder technisch anlegbar + - Persistenzkonfiguration ist nutzbar +- Technische Schema-Initialisierung **beim Programmstart** ausführen, bevor der eigentliche Dokumentlauf beginnt. +- CLI-/Batch-Startpfad auf den realen M4-Ablauf ausrichten. +- Sicherstellen, dass harte Start-, Verdrahtungs- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen. +- Sicherstellen, dass dokumentbezogene Fehler im späteren Lauf **nicht** als Startfehler fehlmodelliert werden. +- M1–M3-Grundverhalten erhalten und sauber mit den M4-Bausteinen kombinieren. +- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration und Modulgrenzen ergänzen. + +### Explizit nicht Teil +- neue Exit-Code-Semantik späterer Meilensteine +- KI-Verdrahtung +- Zielordner- oder Dateinamensverdrahtung +- Logging-Feinschliff + +### Fertig wenn +- das Programm im M4-Stand vollständig startbar ist, +- das SQLite-Schema beim Start kontrolliert initialisiert wird, +- die neuen Adapter korrekt verdrahtet sind, +- harte Persistenz-Startfehler kontrolliert zu Exit-Code 1 führen, +- der Build fehlerfrei bleibt. + +--- + +## AP-008 Tests für Fingerprint, SQLite-Repositories, M4-Statusfortschreibung, Historie und Skip-Logik vervollständigen + +### Voraussetzung +AP-001 bis AP-007 sind abgeschlossen. + +### Ziel +Der vollständige M4-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen. + +### Muss umgesetzt werden +- Unit-Tests für die SHA-256-Fingerprint-Erzeugung implementieren. +- Repository-Tests gegen SQLite implementieren, insbesondere für: + - Schema-Initialisierung + - Anlegen und Lesen eines Dokument-Stammsatzes + - Fortschreiben aller M4-Pflichtfelder des Stammsatzes + - Anlegen und Lesen von Versuchshistorie + - stabile Versuchsnummern pro Fingerprint +- Tests für M4-Statusfortschreibung und Zähler ergänzen, insbesondere: + - unbekanntes Dokument mit erfolgreichem M4-Ende wird als `SUCCESS` persistiert + - erster deterministischer Inhaltsfehler führt zu `FAILED_RETRYABLE` + - zweiter deterministischer Inhaltsfehler in einem späteren Lauf führt zu `FAILED_FINAL` + - technischer dokumentbezogener Fehler nach erfolgreicher Fingerprint-Ermittlung erhöht den Transientfehlerzähler und bleibt `FAILED_RETRYABLE` + - Skip-Fälle verändern keine Fehlerzähler +- Tests für Idempotenz- und Skip-Logik ergänzen, insbesondere: + - bereits erfolgreiches Dokument wird historisiert übersprungen + - final fehlgeschlagenes Dokument wird historisiert übersprungen + - gleicher Inhalt unter anderem Dateinamen wird über denselben Fingerprint erkannt +- Tests ergänzen, die belegen: + - pro identifiziertem dokumentbezogenem Verarbeitungsvorgang entsteht genau **ein** Historieneintrag + - Skip-Ereignisse werden historisiert + - Vor-Fingerprint-Fehler nicht in SQLite-Historie auftauchen +- Tests für Bootstrap- und Startverhalten ergänzen, insbesondere: + - Schema-Initialisierung beim Start + - harter Persistenz-Startfehler führt zu Exit-Code 1 +- Den M4-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M5+ prüfen. + +### Explizit nicht Teil +- Tests für KI, Prompt-Laden oder KI-JSON +- Tests für Zielkopie oder Dateinamensbildung +- Tests für M5+-Persistenzfelder +- Tests für vollständige Retry-Logik späterer Meilensteine + +### Fertig wenn +- die Test-Suite für den M4-Umfang grün ist, +- die wichtigsten M4-Randfälle automatisiert abgesichert sind, +- der definierte M4-Zielzustand vollständig erreicht ist, +- ein fehlerfreier, übergabefähiger Stand vorliegt. + +--- + +## Abschlussbewertung + +Die Arbeitspakete decken den vollständigen M4-Zielumfang aus den verbindlichen Spezifikationen ab: + +- Fingerprint über SHA-256 +- SQLite-Persistenz in zwei Ebenen +- Dokument-Stammsatz mit M4-Minimalumfang +- Versuchshistorie pro identifiziertem dokumentbezogenem Versuch +- Idempotenz über Fingerprint +- Skip-Regeln für bereits erfolgreiche und final fehlgeschlagene Dokumente +- explizite Minimalregel für deterministische Inhaltsfehler in M4 +- Tests für Fingerprint, Persistenz, Statusfortschreibung, Historie und Skip-Logik + +Gleichzeitig bleiben die Grenzen zu M1–M3 sowie zu M5+ gewahrt. Insbesondere werden **keine** KI-Funktionalitäten, **keine** Dateinamensbildung und **keine** Zielkopie vorweggenommen.