670 lines
32 KiB
Markdown
670 lines
32 KiB
Markdown
# 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.
|