From e9bf9231e3378cd9429ef6b5e49036b8c4b40c0f Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Mon, 6 Apr 2026 08:42:57 +0200 Subject: [PATCH] =?UTF-8?q?Arbeitspakete=20f=C3=BCr=20M5=20angelegt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/workpackages/M5 - Arbeitspakete.md | 669 ++++++++++++++++++++++++ 1 file changed, 669 insertions(+) create mode 100644 docs/workpackages/M5 - Arbeitspakete.md diff --git a/docs/workpackages/M5 - Arbeitspakete.md b/docs/workpackages/M5 - Arbeitspakete.md new file mode 100644 index 0000000..9bd1922 --- /dev/null +++ b/docs/workpackages/M5 - Arbeitspakete.md @@ -0,0 +1,669 @@ +# M5 - Arbeitspakete + +## Geltungsbereich + +Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M5 – KI-Integration, Prompt-Bezug und validierter Benennungsvorschlag**. + +Die Meilensteine **M1**, **M2**, **M3** und **M4** 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 **M6+**. +- Kein Umbau bestehender M1–M4-Strukturen ohne direkten M5-Bezug. +- Neue Typen, Ports, Statuswerte, Migrationen und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind. +- M5 darf bestehende M4-Persistenz **gezielt evolvieren**, aber nicht stillschweigend neu erfinden. +- Jeder positive M5-Zwischenstand muss bereits so modelliert sein, dass **M6 darauf ohne Statusbruch** aufsetzen kann. +- M5 endet fachlich mit einem **persistierten, validierten Benennungsvorschlag**; **nicht** mit einer Zielkopie. + +## Explizit nicht Bestandteil von M5 + +- physische Zielkopie in den Zielordner +- finales Dateinamensformat `YYYY-MM-DD - Titel.pdf` als technische Ausgabeoperation +- Dublettenbehandlung `(1)`, `(2)` im Zielordner +- Windows-Zeichenbereinigung für den finalen Zieldateinamen +- Zielpfad- und Zieldateinamenspersistenz +- atomisches Schreiben oder temporäre Zieldateien +- vollständige End-to-End-Erfolgssemantik des späteren Produktiv-Endstands aus M6 +- Logging-Feinschliff des Endstands aus M7 +- vollständige laufübergreifende Retry-Logik späterer Meilensteine für alle Fehlerarten jenseits des in M5 konkret benötigten Umfangs +- manuelle Nachbearbeitung oder Benutzerinteraktion + +## Verbindliche M5-Regeln für **alle** Arbeitspakete + +### 1. Status- und Übergangssemantik zwischen M4, M5 und M6 + +Die in M4 verwendete positive Zwischenbedeutung von `SUCCESS` reicht ab M5 **nicht mehr aus**, weil M5 einen validierten Benennungsvorschlag erzeugt, M6 aber erst die Zielkopie schreibt. + +Daher gilt ab M5 verbindlich: + +- `SUCCESS` ist ab M5 **für den echten Enderfolg nach M6 reserviert**. +- M5 führt die beiden **nicht-terminalen positiven Statuswerte** ein: + - `READY_FOR_AI` = Dokument ist fachlich bis einschließlich M3 vorbereitet, aber es liegt noch **kein** gültiger M5-Benennungsvorschlag vor. + - `PROPOSAL_READY` = ein gültiger M5-Benennungsvorschlag ist persistent vorhanden; das Dokument ist **für M5 abgeschlossen**, aber **noch nicht** im Sinne von M6 erfolgreich kopiert. +- Bereits vorhandene **M4-Altbestände** mit positivem Status `SUCCESS`, aber **ohne** M5-Benennungsvorschlag, müssen in M5 **kontrolliert in `READY_FOR_AI` überführt** werden. +- Die bestehenden negativen bzw. Skip-Statuswerte bleiben erhalten: + - `FAILED_RETRYABLE` + - `FAILED_FINAL` + - `SKIPPED_ALREADY_PROCESSED` + - `SKIPPED_FINAL_FAILURE` +- Für M5-spezifische Wiederholungsläufe gilt: + - `PROPOSAL_READY` wird **nicht erneut per KI verarbeitet**, + - `SUCCESS` wird **nicht erneut verarbeitet**, + - `FAILED_FINAL` wird **nicht erneut verarbeitet**, + - `READY_FOR_AI` und `FAILED_RETRYABLE` bleiben verarbeitbar. +- Für M6 gilt bereits als verbindliche Übergaberegel: + - `PROPOSAL_READY` ist **kein terminaler Gesamterfolg**, sondern der fachlich korrekte Eingangszustand für Dateinamensbildung und Zielkopie. + +### 2. Externer Prompt-Bezug + +- Der Prompt ist in M5 **nicht** im Code fest verdrahtet. +- Die Anwendung lädt den fachlich verwendeten Prompt aus einer **externen Datei**. +- Der für einen KI-Versuch verwendete Prompt muss über einen **stabilen Prompt-Identifikator** nachvollziehbar sein, mindestens über den Prompt-Dateinamen oder einen gleichwertig stabilen Identifikator. + +### 3. Deterministische KI-Anfragezusammensetzung + +M5 führt **kein frei erfundenes Templating-System** ein. + +Stattdessen gilt: + +- Die Application erzeugt für den KI-Port eine **vollständig deterministische Anfrage-Repräsentation**. +- Diese Repräsentation besteht mindestens aus: + - Prompt-Inhalt, + - Prompt-Identifikator, + - begrenztem Dokumenttext, + - tatsächlich gesendeter Zeichenzahl, + - der verbindlichen JSON-only-Erwartung für `date`, `title`, `reasoning`. +- Die Zusammensetzung von Prompt und Dokumenttext erfolgt über einen **festen, dokumentierten technischen Aufbau**, damit KI 2 dies ohne Interpretationsspielraum umsetzen kann. +- Provider-spezifische Features für strukturiertes Output dürfen **optional intern** verwendet werden, sind aber **nicht** Voraussetzung des M5-Designs. + +### 4. KI-Konfiguration und effektiver API-Key + +Für M5 müssen die bereits im Zielbild vorgesehenen KI-relevanten Konfigurationswerte technisch nutzbar und verdrahtet sein, insbesondere: + +- `api.baseUrl` +- `api.model` +- `api.timeoutSeconds` +- `max.text.characters` +- `prompt.template.file` + +Der API-Key bleibt Konfiguration; die bestehende Prioritätsregel **Umgebungsvariable vor Properties** bleibt verbindlich. + +Zusätzlich gilt für M5: + +- der **effektive** API-Key muss nicht nur aufgelöst, sondern auch **tatsächlich im HTTP-Adapter verwendet** werden, +- die Verwendung muss automatisiert testbar nachgewiesen sein. + +### 5. Begrenzung des an die KI gesendeten Inhalts + +- Die maximale Zeichenzahl des an die KI gegebenen Dokumentinhalts ist konfigurierbar. +- Die Begrenzung muss **vor dem KI-Aufruf** technisch angewendet werden. +- Die tatsächlich an die KI gesendete Zeichenzahl muss verfügbar und persistierbar sein. +- Die Begrenzung verändert **nicht** den extrahierten Originaltext im M3-/M4-Sinne, sondern nur den **für M5 verwendeten KI-Eingabetext**. + +### 6. Vollständige M5-Regel für Titel und Datum + +M5 muss die fachliche Regel **operational vollständig** umsetzen, ohne unzuverlässige Heuristik-Experimente einzuführen. + +Daher gilt kombinatorisch: + +- Der **Prompt-Vertrag** bindet die KI verbindlich an die nicht rein technisch prüfbaren Erwartungen: + - Titel auf Deutsch, + - verständlich, + - hinreichend eindeutig, + - Eigennamen unverändert. +- Die **Application-Validierung** prüft zusätzlich alle in M5 **objektiv prüfbaren** Regeln: + - `title` vorhanden, + - `reasoning` vorhanden, + - Basistitel max. 20 Zeichen, + - keine unzulässigen Sonderzeichen außer Leerzeichen, + - keine generischen Platzhaltertitel, + - vorhandenes `date` ist als `YYYY-MM-DD` interpretierbar. +- M5 führt **keine** spekulative Sprachdetektion, keine unsichere Eigennamen-Normalisierung und keine weichen Heuristiken für „Verständlichkeit“ ein, die fachlich eher neue Fehler erzeugen würden. + +### 7. Technischer Antwortvertrag der KI + +Die KI-Antwort muss in M5 als **genau ein parsebares JSON-Objekt** verarbeitet werden. + +Zweckmäßiges Schema im M5-Sinn: + +```json +{ + "date": "2026-02-11", + "title": "Stromabrechnung", + "reasoning": "..." +} +``` + +Dabei gilt: + +- `title` ist verpflichtend, +- `reasoning` ist verpflichtend, +- `date` ist optional, +- zusätzliche Felder dürfen technisch toleriert werden, sind aber für M5 fachlich irrelevant, +- zusätzlicher Freitext außerhalb des JSON-Objekts macht die Antwort **technisch unbrauchbar**. + +### 8. Technisch unbrauchbare vs. fachlich unbrauchbare KI-Ergebnisse + +Für M5 ist diese Unterscheidung verbindlich: + +**Technisch unbrauchbare KI-Ergebnisse** sind insbesondere: +- KI nicht erreichbar, +- Timeout, +- technisch fehlgeschlagener HTTP-Aufruf, +- nicht parsebare KI-Antwort, +- technisch unvollständige Antwort ohne verpflichtende Strukturbestandteile, +- zusätzlicher Text außerhalb des erwarteten einzelnen JSON-Objekts. + +Diese Fälle sind im M5-Sinn **dokumentbezogene technische Fehler**. + +**Fachlich unbrauchbare KI-Ergebnisse** sind insbesondere: +- unbrauchbarer oder generischer Titel, +- Titel verletzt die technisch prüfbaren Titelregeln des Zielbilds, +- die KI liefert ein `date`, dieses ist aber nicht interpretierbar oder unbrauchbar. + +Diese Fälle sind im M5-Sinn **deterministische Inhaltsfehler**. + +### 9. Datumsauflösung und Datumsquelle + +- Liefert die KI ein gültiges `date`, wird dieses als aufgelöstes Datum verwendet. +- Liefert die KI **kein** `date`, setzt die Anwendung den Fallback über die technische Uhr (`ClockPort`) auf das aktuelle Datum. +- Liefert die KI ein `date`, dieses ist aber unbrauchbar, ist das **kein** Fallback-Fall, sondern ein fachlicher Fehlerfall. +- Die Datumsquelle muss im M5-Stand nachvollziehbar und persistierbar sein. + +### 10. M5-Benennungsvorschlag und führende Quelle für M6 + +Der M5-Benennungsvorschlag besteht mindestens aus: + +- aufgelöstem Datum, +- Datumsquelle, +- validiertem Basistitel, +- KI-Begründung (`reasoning`). + +**Nicht** Bestandteil des M5-Benennungsvorschlags sind: + +- finaler vollständiger Dateiname, +- Dubletten-Suffix, +- Zielpfad, +- physische Zielkopie. + +Für die Übergabe an M6 gilt verbindlich: + +- die **führende Quelle** des gültigen M5-Benennungsvorschlags ist der **neueste Versuchshistorieneintrag mit Ergebnisstatus `PROPOSAL_READY`**, +- M5 führt **keine parallele zweite Wahrheitsquelle** für Datum/Titel/Reasoning im Dokument-Stammsatz ein, +- der Dokument-Stammsatz enthält in M5 weiterhin den Gesamtstatus und die Zähler, nicht aber redundante M6-Zieldaten. + +### 11. Erweiterung der Versuchshistorie in M5 + +Die bereits in M4 vorhandene Versuchshistorie wird in M5 gezielt erweitert. Für jeden dokumentbezogenen, identifizierten M5-Versuch müssen mindestens speicherbar sein: + +- Modellname, +- Prompt-Identifikator oder Prompt-Dateiname, +- verarbeitete Seitenzahl, +- an die KI gesendete Zeichenzahl, +- KI-Rohantwort, +- KI-Reasoning, +- aufgelöstes Datum, +- Datumsquelle, +- validierter Titel. + +Nicht Bestandteil der M5-Versuchshistorie sind Zielpfad oder finaler Zieldateiname. + +### 12. Fehlersemantik und Zählerfortschreibung in M5 + +M5 erweitert die in M4 bereits vorhandene Fehlersemantik: + +- dokumentbezogene **technische** KI-Fehler nach erfolgreicher Fingerprint-Ermittlung bleiben retryable und laufen über den **Transientfehlerzähler**, +- fachlich **deterministische** KI-Ergebnisfehler laufen über den **Inhaltsfehlerzähler**, +- die bestehende M4-Regel „erster deterministischer Inhaltsfehler retryable, zweiter final“ bleibt erhalten und gilt auch für M5-deterministische Inhaltsfehler, +- Skip-Fälle aus M4 bleiben unverändert erhalten, +- Vor-Fingerprint-Fehler bleiben weiterhin **nicht historisierte** Laufereignisse. + +### 13. Kein Vorgriff auf M6 + +M5 endet fachlich mit einem **persistierten, validierten Benennungsvorschlag**. M5 führt **keine** Zielkopie aus und erzeugt **keinen** finalen Zieldateinamen als technische Dateisystemoperation. + +--- + +## AP-001 M5-Kernobjekte, Statusmodell und KI-/Prompt-Port-Verträge präzisieren + +### Voraussetzung +Keine. Dieses Arbeitspaket ist der M5-Startpunkt. + +### Ziel +Die M5-relevanten Typen, positiven Zwischenstatus, KI-/Prompt-Verträge und Ergebnissemantiken werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können. + +### Muss umgesetzt werden +- Neue M5-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für: + - externen Prompt-Bezug, + - Prompt-Identifikator, + - deterministische KI-Anfrage-Repräsentation, + - KI-Rohantwort, + - parsebares KI-Antwortmodell, + - validierten Benennungsvorschlag, + - Datumsquelle, + - KI-bezogene Nachvollziehbarkeitsdaten pro Versuch, + - technische vs. fachliche KI-Fehlerklassifikation. +- Das Statusmodell gezielt um die nicht-terminalen positiven Zwischenstatus erweitern: + - `READY_FOR_AI` + - `PROPOSAL_READY` +- Die Semantik dieser Statuswerte in JavaDoc und ggf. `package-info` so dokumentieren, dass klar ist: + - `READY_FOR_AI` ist **M5-verarbeitbar**, + - `PROPOSAL_READY` ist **für M5 abgeschlossen**, aber **für M6 weiterverarbeitbar**, + - `SUCCESS` bleibt ab M5 dem echten M6-Enderfolg vorbehalten. +- Outbound-Ports definieren für: + - Laden des externen Prompts, + - KI-Aufruf über eine OpenAI-kompatible Schnittstelle. +- Port-Verträge so schneiden, dass **weder `Path`/`File` noch HTTP-/JSON-Bibliothekstypen** in Domain oder Application durchsickern. +- Rückgabemodelle so anlegen, dass spätere Arbeitspakete ohne Zusatzannahmen unterscheiden können zwischen: + - technisch erfolgreichem KI-Aufruf mit Rohantwort, + - technischem KI-Fehler, + - parsebarer Antwort, + - technisch unbrauchbarer Antwort, + - fachlich validiertem Benennungsvorschlag, + - fachlich unbrauchbarem Benennungsvorschlag. +- M5-spezifische Semantik von `date`, `title` und `reasoning` in JavaDoc eindeutig beschreiben. +- Explizit dokumentieren, dass M5 **keinen finalen Zieldateinamen** und **keine Zielkopie** erzeugt. +- Explizit dokumentieren, dass die führende Quelle für M6 **der neueste Versuch mit `PROPOSAL_READY`** ist. + +### Explizit nicht Teil +- Prompt-Datei laden +- HTTP-Adapter +- KI-JSON-Parsing +- fachliche Titel- und Datumsvalidierung +- Persistenzanpassungen +- Batch-Integration + +### Fertig wenn +- die M5-relevanten Typen und Port-Verträge vorhanden sind, +- technische und fachliche M5-Ergebnisarten klar unterscheidbar modelliert sind, +- die positiven Zwischenstatus ohne Widerspruch zu M6 definiert sind, +- Domain und Application frei von Infrastrukturtypen bleiben, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-002 Externen Prompt laden, stabil identifizieren und deterministische KI-Anfrage zusammensetzen + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Der fachlich verwendete Prompt wird aus einer externen Datei geladen, stabil identifizierbar gemacht und gemeinsam mit dem Dokumenttext in eine eindeutig definierte, deterministische KI-Anfrage-Repräsentation überführt. + +### Muss umgesetzt werden +- Adapter-Out für das Laden der externen Prompt-Datei implementieren. +- Aus dem geladenen Prompt einen **stabilen Prompt-Identifikator** ableiten, mindestens über den Prompt-Dateinamen oder einen gleichwertig stabilen Identifikator. +- Sicherstellen, dass leerer oder technisch unbrauchbarer Prompt nicht als gültige M5-Eingabe weitergereicht wird. +- Einen **fest dokumentierten technischen Aufbau** der KI-Anfrage-Repräsentation implementieren, der mindestens enthält: + - Prompt-Inhalt, + - Prompt-Identifikator, + - Dokumenttext als eigener Block, + - die JSON-only-Erwartung für `date`, `title`, `reasoning`. +- Die Zusammensetzung so schneiden, dass KI 2 **ohne implizite Entscheidung** weiß, in welcher Reihenfolge Prompt und Dokumenttext zusammengeführt werden. +- Den Mechanismus so schneiden, dass **kein frei erfundenes Templating-System** eingeführt werden muss. +- JavaDoc für Prompt-Bezug, Identifikator, deterministische Zusammensetzung, JSON-only-Vertrag und M5-Nicht-Ziele ergänzen. + +### Explizit nicht Teil +- HTTP-Aufruf zur KI +- Textbegrenzung +- KI-Antwortvalidierung +- Batch-Integration +- Persistenz der Prompt-Metadaten + +### Fertig wenn +- der Prompt aus einer externen Datei technisch ladbar ist, +- ein stabiler Prompt-Identifikator bereitsteht, +- die KI-Anfrage-Repräsentation deterministisch aufgebaut wird, +- kein freies Ad-hoc-Templating eingeführt wurde, +- der Stand weiterhin fehlerfrei buildbar ist. + +--- + +## AP-003 OpenAI-kompatiblen KI-HTTP-Adapter mit wirksamer Konfiguration und kontrolliertem technischem Fehlerverhalten implementieren + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Ein technisch gekapselter Adapter kann einen M5-KI-Aufruf gegen eine OpenAI-kompatible HTTP-Schnittstelle ausführen, den **effektiven** API-Key tatsächlich verwenden und eine Rohantwort oder einen kontrollierten technischen Fehler liefern. + +### Muss umgesetzt werden +- OpenAI-kompatiblen HTTP-Adapter im Adapter-Out implementieren. +- Basis-URL, Modellname, Timeout und API-Zugriff aus der vorhandenen Konfiguration technisch nutzbar machen. +- Den Adapter so schneiden, dass Domain und Application nur mit dem **abstrakten KI-Port** arbeiten. +- Eine technische Rohantwort liefern, die in späteren Arbeitspaketen geparst und validiert werden kann. +- Kontrolliertes Fehlerverhalten mindestens für folgende Fälle umsetzen: + - Timeout, + - nicht erreichbarer Endpunkt, + - technisch fehlgeschlagener HTTP-Aufruf, + - sonstige technische Kommunikationsfehler. +- Sicherstellen, dass der **effektive API-Key** gemäß bestehender Prioritätsregel im Adapter **real verwendet** wird. +- Sicherstellen, dass keine HTTP-, Authentifizierungs- oder JSON-Implementierungsdetails in Domain oder Application durchsickern. +- JavaDoc für OpenAI-Kompatibilität, technische Fehlergrenzen, Konfigurationsnutzung und M5-Nicht-Ziele ergänzen. + +### Explizit nicht Teil +- fachliche Validierung der KI-Antwort +- Persistenz +- Batch-Orchestrierung +- Textbegrenzung +- Datums-Fallback +- finaler Benennungsvorschlag + +### Fertig wenn +- der KI-Port technisch implementiert ist, +- Konfiguration für Basis-URL, Modellname, Timeout und effektiven API-Key wirksam verwendet wird, +- Rohantwort und technische Fehler kontrolliert über den Port geliefert werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-004 Textbegrenzung, KI-JSON-Parsing, vollständige M5-Validierung und Datumsauflösung umsetzen + +### Voraussetzung +AP-001 bis AP-003 sind abgeschlossen. + +### Ziel +Die Anwendung kann einen begrenzten Dokumenttext für den KI-Aufruf vorbereiten, die KI-Rohantwort als JSON interpretieren und daraus entweder einen validierten Benennungsvorschlag oder einen eindeutig klassifizierten Fehler ableiten. + +### Muss umgesetzt werden +- Konfigurierbare Begrenzung des an die KI zu sendenden Dokumenttexts umsetzen. +- Sicherstellen, dass die Begrenzung **vor dem KI-Aufruf** angewendet wird. +- Tatsächlich gesendete Zeichenzahl technisch erfassen und für spätere Persistenz bereitstellen. +- Parsing der KI-Rohantwort als **genau ein JSON-Objekt** implementieren. +- Technische Antwortvalidierung umsetzen: + - `title` vorhanden und nicht leer, + - `reasoning` vorhanden und nicht leer, + - `date` optional, + - zusätzlicher Freitext außerhalb des JSON-Objekts führt zu technischer Ungültigkeit. +- Fachliche M5-Validierung für die **objektiv prüfbaren** Titel- und Datumsregeln umsetzen, insbesondere: + - Basistitel max. 20 Zeichen, + - keine unzulässigen Sonderzeichen außer Leerzeichen, + - keine generischen Platzhaltertitel, + - ein vorhandenes `date` muss als `YYYY-MM-DD` interpretierbar sein. +- Den nicht rein technisch prüfbaren Teil der fachlichen Titelregel explizit über den **Prompt-Vertrag** absichern und dies im Code/JavaDoc sauber dokumentieren: + - Deutsch, + - verständlich, + - hinreichend eindeutig, + - Eigennamen unverändert. +- Explizit umsetzen: + - fehlendes `date` → Fallback über `ClockPort`, + - vorhandenes, aber unbrauchbares `date` → fachlicher Fehler, + - parsebare, aber fachlich unbrauchbare Titel → fachlicher Fehler. +- Einen validierten M5-Benennungsvorschlag bereitstellen, der mindestens enthält: + - aufgelöstes Datum, + - Datumsquelle, + - validierten Titel, + - KI-Reasoning. +- JavaDoc für Begrenzungsregel, Antwortvalidierung, Datums-Fallback und operative Vollständigkeit der Titelregel ergänzen. + +### Explizit nicht Teil +- HTTP-Adapter +- SQLite-Schemaerweiterung +- Batch-Integration +- Status- und Zählerfortschreibung +- finale Dateinamensbildung +- Zielkopie + +### Fertig wenn +- Dokumenttext begrenzt werden kann, +- parsebare und unparsebare KI-Antworten sauber unterscheidbar sind, +- fehlendes Datum korrekt auf den Clock-Fallback läuft, +- fachlich unbrauchbare Titel und Datumswerte sauber erkannt werden, +- ein validierter M5-Benennungsvorschlag technisch verfügbar ist, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-005 SQLite-Schema von M4 nach M5 evolvieren, Altbestände migrieren und Versuchshistorie um M5-Nachvollziehbarkeit erweitern + +### Voraussetzung +AP-001 bis AP-004 sind abgeschlossen. + +### Ziel +Die bestehende M4-Persistenz wird kontrolliert auf den M5-Stand erweitert, inklusive der **idempotenten Migration positiver M4-Altbestände** und der Erweiterung der Versuchshistorie um die M5-Nachvollziehbarkeit. + +### Muss umgesetzt werden +- Das bestehende SQLite-Schema **evolvieren**, nicht neu erfinden. +- Die Schema-Initialisierung so erweitern, dass ein vorhandenes M4-Schema kontrolliert auf den M5-Stand gebracht werden kann. +- Die Versuchshistorie um die für M5 benötigten Felder erweitern, insbesondere für: + - Modellname, + - Prompt-Identifikator oder Prompt-Dateiname, + - verarbeitete Seitenzahl, + - an die KI gesendete Zeichenzahl, + - KI-Rohantwort, + - KI-Reasoning, + - aufgelöstes Datum, + - Datumsquelle, + - validierten Titel. +- Die Persistenz so erweitern, dass die neuen nicht-terminalen positiven Statuswerte fachlich konsistent speicherbar sind: + - `READY_FOR_AI` + - `PROPOSAL_READY` +- Eine **idempotente M4→M5-Altbestandsmigration** vorsehen, die mindestens sicherstellt: + - M4-Dokumente mit positivem Altstatus `SUCCESS`, aber ohne M5-Benennungsvorschlag, werden kontrolliert nach `READY_FOR_AI` überführt, + - diese Migration ist mehrfach ausführbar, ohne Daten zu beschädigen, + - bestehende negative und terminale Fehlerzustände bleiben unangetastet. +- Sicherstellen, dass: + - bestehende M4-Daten weiterhin lesbar bleiben, + - die M5-Erweiterung idempotent initialisierbar ist, + - keine M6+-Felder für Zielpfad oder finalen Zieldateinamen angelegt werden. +- Repository-Mapping der Versuchshistorie auf die neuen M5-Felder erweitern. +- Falls für Tests oder Use-Case-Integration nötig, passende Lesefähigkeiten ergänzen, ohne spätere Reporting-Funktionalität vorwegzunehmen. +- JavaDoc für Schemaevolution, Altbestandsmigration, Rückwärtsverträglichkeit und M5-Nachvollziehbarkeit ergänzen. + +### Explizit nicht Teil +- Batch-Use-Case-Integration +- KI-Aufruf +- Status- und Zählerentscheidungen im laufenden Batch +- Zielpfad- oder Dateinamenspersistenz +- M6-Dateisystemfunktionalität + +### Fertig wenn +- das M4-Schema kontrolliert auf M5 erweitert werden kann, +- M4-Altbestände mit positivem Zwischenstatus idempotent auf die M5-Semantik überführt werden, +- die neuen M5-Felder in der Versuchshistorie technisch schreib- und lesbar sind, +- bestehende M4-Daten nicht unbrauchbar werden, +- keine M6+-Persistenzfelder eingeführt wurden, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-006 M5-Entscheidungslogik und Batch-Integration für KI-Aufruf, Fehlerklassifikation, Statusfortschreibung und persistierten Benennungsvorschlag umsetzen + +### Voraussetzung +AP-001 bis AP-005 sind abgeschlossen. + +### Ziel +Der bestehende M4-Lauf wird zu einem echten M5-Lauf erweitert, der nach erfolgreicher M3-Vorprüfung per KI einen validierten Benennungsvorschlag erzeugt, KI-bezogene Versuchsdaten persistiert und die positive Statussemantik so fortschreibt, dass M6 ohne Statusbruch anknüpfen kann. + +### Muss umgesetzt werden +- Den bestehenden Batch-Use-Case so erweitern, dass pro geeignetem Dokument nach M4-Identifikation und nach bestandener M3-Vorprüfung zusätzlich gilt: + 1. Prompt laden, + 2. Dokumenttext begrenzen, + 3. deterministische KI-Anfrage erzeugen, + 4. KI-Aufruf durchführen, + 5. KI-Rohantwort technisch verarbeiten, + 6. Benennungsvorschlag validieren, + 7. Versuchshistorie mit M5-Nachvollziehbarkeit fortschreiben, + 8. Status und Zähler im vorhandenen Rahmen konsistent fortschreiben. +- Sicherstellen, dass **kein KI-Aufruf** erfolgt bei: + - Vor-Fingerprint-Fehlern, + - terminalen Skip-Fällen aus M4, + - M3-Inhaltsfehlern, + - sonstigen Fällen, die den Dokumentlauf bereits vor der KI sauber beendet haben. +- Die positiven Dokumentzustände explizit wie folgt behandeln: + - M4-Altbestand `SUCCESS` ohne M5-Benennungsvorschlag wird **nicht** als terminal erfolgreich übersprungen, sondern gilt nach Migration bzw. Normalisierung als `READY_FOR_AI`, + - gültiger M5-Benennungsvorschlag führt zu `PROPOSAL_READY`, **nicht** zu `SUCCESS`, + - bestehendes `PROPOSAL_READY` führt in M5 zu **keinem erneuten KI-Aufruf**. +- M5-Fehlerfälle explizit wie folgt in den bestehenden Status- und Zählerrahmen überführen: + - technischer KI-Fehler oder technisch unbrauchbare KI-Antwort → dokumentbezogener technischer Fehler, retryable, **Transientfehlerzähler +1**, + - parsebare, aber fachlich unbrauchbare KI-Antwort → deterministischer Inhaltsfehler, **Inhaltsfehlerzähler** nach bestehender Regel fortschreiben, + - gültiger Benennungsvorschlag → `PROPOSAL_READY`, Fehlerzähler unverändert. +- Sicherstellen, dass bei dokumentbezogenen KI-Fehlern der Batch-Lauf für andere Dokumente kontrolliert weiterläuft. +- Für identifizierte Dokumente sicherstellen, dass Versuchshistorie und Stammsatz konsistent fortgeschrieben werden und kein teilpersistierter Zustand zurückbleibt. +- Sicherstellen, dass die führende Quelle für M6 **der neueste Versuch mit `PROPOSAL_READY`** bleibt und nicht implizit aus anderen Daten rekonstruiert werden muss. +- Sicherstellen, dass KI-Rohantwort standardmäßig **in SQLite**, aber nicht als M6-/M7-Funktionalität fehlmodelliert wird. +- JavaDoc für M5-Laufreihenfolge, KI-Grenze, Fehlerklassifikation, positive Statusfortschreibung und Persistenzkonsistenz ergänzen. + +### Explizit nicht Teil +- physische Zielkopie +- finale Dateinamensbildung +- Dublettenbehandlung +- Zielpfad- und Zieldateinamenspersistenz +- M6- oder M7-Feinschliff + +### Fertig wenn +- der Batch-Lauf für geeignete Dokumente tatsächlich einen KI-basierten Benennungsvorschlag erzeugt, +- M4-Altbestände mit positivem Zwischenstatus korrekt in die M5-Verarbeitung überführt werden, +- gültige M5-Ergebnisse als `PROPOSAL_READY` und **nicht** als `SUCCESS` persistiert werden, +- M5-spezifische technische und fachliche KI-Fehler sauber unterschieden werden, +- der validierte Benennungsvorschlag persistiert wird, +- KI-Aufrufe nur an den fachlich zulässigen Stellen erfolgen, +- der Lauf trotz dokumentbezogener KI-Fehler kontrolliert weiterarbeitet, +- weiterhin keine M6+-Funktionalität enthalten ist. + +--- + +## AP-007 Bootstrap- und CLI-Anpassungen für M5-Konfiguration, Startvalidierung, Schemaevolution und vollständige Verdrahtung durchführen + +### Voraussetzung +AP-001 bis AP-006 sind abgeschlossen. + +### Ziel +Der Programmeinstieg ist sauber an den M5-Lauf angepasst; die KI-relevante Konfiguration wird validiert, die M5-Schemaevolution einschließlich Altbestandsmigration wird beim Start wirksam, alle M5-Bausteine sind verdrahtet und harte Startfehler führen weiterhin kontrolliert zu Exit-Code 1. + +### Muss umgesetzt werden +- Bootstrap-Verdrahtung auf die neuen M5-Ports, Adapter, Validierungs- und Persistenzbausteine erweitern. +- M5-relevante Konfiguration ergänzen bzw. verdrahten, insbesondere für: + - `api.baseUrl` + - `api.model` + - `api.timeoutSeconds` + - `max.text.characters` + - `prompt.template.file` +- Startvalidierung so ergänzen, dass mindestens geprüft wird: + - Prompt-Datei ist vorhanden und technisch lesbar, + - `max.text.characters` ist gültig und technisch nutzbar, + - Timeout ist gültig, + - KI-Basis-URL und Modellname sind vorhanden, + - ein effektiver API-Key gemäß bestehender Prioritätsregel verfügbar ist. +- Die bestehende M4-Schema-Initialisierung mit der M5-Schemaevolution und der M4→M5-Altbestandsmigration sauber kombinieren. +- Sicherstellen, dass harte Start-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen. +- Sicherstellen, dass dokumentbezogene KI-Fehler **nicht** als Startfehler fehlmodelliert werden. +- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration, Schemaevolution und Modulgrenzen ergänzen. + +### Explizit nicht Teil +- Logging-Feinschliff des Endstands +- M6-Dateisystemverdrahtung +- Zielkopie +- Dublettenlogik +- spätere Betriebsoptimierungen + +### Fertig wenn +- das Programm im M5-Stand vollständig startbar ist, +- alle M5-Bausteine korrekt verdrahtet sind, +- die M5-Startvalidierung greift, +- die M5-Schemaevolution einschließlich Altbestandsmigration beim Start wirksam wird, +- harte Startfehler weiterhin kontrolliert zu Exit-Code 1 führen, +- der Build fehlerfrei bleibt. + +--- + +## AP-008 Tests für Prompt-Bezug, KI-Adapter, Validierung, Altbestandsmigration, Statussemantik, Schemaevolution und M5-Ablauf vervollständigen + +### Voraussetzung +AP-001 bis AP-007 sind abgeschlossen. + +### Ziel +Der vollständige M5-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen. + +### Muss umgesetzt werden +- Unit-Tests für den externen Prompt-Bezug implementieren, insbesondere für: + - Prompt-Datei wird geladen, + - leerer oder technisch ungültiger Prompt wird abgelehnt, + - stabiler Prompt-Identifikator wird geliefert, + - deterministische Zusammensetzung der KI-Anfrage bleibt reproduzierbar. +- Tests für Textbegrenzung und tatsächlich gesendete Zeichenzahl implementieren. +- Tests für KI-JSON-Parsing und technische Antwortvalidierung implementieren, insbesondere für: + - gültiges JSON, + - ungültiges JSON, + - fehlendes `title`, + - fehlendes `reasoning`, + - optionales `date`, + - zusätzlicher Text außerhalb des JSON-Objekts. +- Tests für fachliche M5-Validierung implementieren, insbesondere für: + - gültigen Titel, + - generischen Titel, + - Titel mit unzulässigen Sonderzeichen, + - Titel über 20 Zeichen, + - gültiges KI-Datum, + - fehlendes Datum mit Clock-Fallback, + - unbrauchbares vorhandenes Datum. +- Adapter-Tests für den KI-Port ergänzen, insbesondere für: + - erfolgreiche Rohantwort, + - Timeout, + - technisch fehlgeschlagenen HTTP-Aufruf, + - Verwendung des **effektiven API-Keys** im tatsächlichen HTTP-Request, + - Vorrang der Umgebungsvariable vor `api.key` aus Properties im real genutzten Adapterpfad. +- Repository- und Schema-Tests gegen SQLite ergänzen, insbesondere für: + - Evolution eines M4-Schemas auf M5, + - Persistenz und Auslesen der neuen M5-Versuchshistorienfelder, + - Rückwärtsverträglichkeit bestehender M4-Daten, + - idempotente Migration von M4-Altbeständen `SUCCESS` nach `READY_FOR_AI`. +- Integrationstests für den M5-Ablauf ergänzen, insbesondere: + - gültiger M5-Happy-Path mit persistiertem Benennungsvorschlag endet in `PROPOSAL_READY`, **nicht** in `SUCCESS`, + - technisch unbrauchbare KI-Antwort führt zu retryablem technischem Fehler, + - fachlich unbrauchbare KI-Antwort führt zu deterministischem Inhaltsfehler, + - bei fehlendem `date` wird der Clock-Fallback verwendet, + - bei M3-Inhaltsfehlern erfolgt kein KI-Aufruf, + - bestehendes `PROPOSAL_READY` wird im M5-Wiederholungslauf nicht erneut per KI verarbeitet, + - M4-Altbestände mit positivem Zwischenstatus werden im M5-Lauf nicht fälschlich als final erfolgreich übersprungen, + - die führende Quelle für M6 ist der neueste Versuch mit `PROPOSAL_READY`, + - es erfolgt weiterhin **keine Zielkopie**. +- Tests für Bootstrap- und Startverhalten ergänzen, insbesondere: + - ungültige M5-Konfiguration führt zu Exit-Code 1, + - M5-Schemaevolution einschließlich Altbestandsmigration wird beim Start wirksam, + - dokumentbezogene KI-Fehler führen **nicht** zu Exit-Code 1. +- Den M5-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M6+ prüfen. + +### Explizit nicht Teil +- Tests für Zielkopie +- Tests für Dublettenbehandlung im Zielordner +- Tests für finalen Zieldateinamen +- Tests für M6-/M7-Endverhalten + +### Fertig wenn +- die Test-Suite für den M5-Umfang grün ist, +- die wichtigsten M5-Randfälle automatisiert abgesichert sind, +- die positive Statussemantik M4→M5→M6 ohne Lücke nachgewiesen ist, +- der definierte M5-Zielzustand vollständig erreicht ist, +- ein fehlerfreier, übergabefähiger Stand vorliegt. + +--- + +## Abschlussbewertung + +Die Arbeitspakete decken den vollständigen M5-Zielumfang aus den verbindlichen Spezifikationen ab und schließen zusätzlich die zuvor offene **Status- und Übergangssemantik zwischen M4, M5 und M6** sauber: + +- externer Prompt-Bezug +- deterministische KI-Anfrage-Zusammensetzung +- OpenAI-kompatibler KI-Aufruf +- konfigurierbarer KI-Zugriff einschließlich wirksam genutztem effektivem API-Key +- Begrenzung des an die KI gesendeten Inhalts +- technische und fachliche Validierung der KI-Antwort +- Datums-Fallback durch die Anwendung +- persistierter, validierter Benennungsvorschlag +- Erweiterung der Versuchshistorie um M5-Nachvollziehbarkeit +- idempotente M4→M5-Altbestandsmigration +- positive Zwischenstatus `READY_FOR_AI` und `PROPOSAL_READY` als saubere Brücke zu M6 +- Tests für Prompt, KI-Adapter, Validierung, Datumsauflösung, Schemaevolution, Altbestandsmigration und M5-Ablauf + +Gleichzeitig bleiben die Grenzen zu M1–M4 sowie zu M6+ gewahrt. Insbesondere werden **keine** Zielkopie, **keine** Dublettenbehandlung im Zielordner und **keine** finale Dateinamensbildung vorweggenommen.