Arbeitspakete für M4
This commit is contained in:
516
docs/workpackages/M4 - Arbeitspakete.md
Normal file
516
docs/workpackages/M4 - Arbeitspakete.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user