From f4a1bce9ae28536e004b9ab1bb7220b34f95f7cd Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Thu, 23 Apr 2026 10:14:54 +0200 Subject: [PATCH] =?UTF-8?q?Spezifikation=20f=C3=BCr=20V2.8=20hinzugef?= =?UTF-8?q?=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/specs/V2_8_-_Spezifikation.md | 193 +++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 docs/specs/V2_8_-_Spezifikation.md diff --git a/docs/specs/V2_8_-_Spezifikation.md b/docs/specs/V2_8_-_Spezifikation.md new file mode 100644 index 0000000..e9f21c7 --- /dev/null +++ b/docs/specs/V2_8_-_Spezifikation.md @@ -0,0 +1,193 @@ +# V2.8 – Selektive Wiederverarbeitung und Status-Reset in der Ergebnisliste + +**Status:** Freigegeben +**Erstellt:** 2026-04-23 +**Überarbeitet:** 2026-04-23 (nach zwei Reviews, finale Version) +**Autor:** Marcus (mit Claude als Mentor) + +--- + +## Ziel + +V2.8 erweitert den Tab „Verarbeitungslauf" um die Möglichkeit, einzelne oder mehrere Dateien +aus der Ergebnisliste gezielt erneut verarbeiten zu lassen oder deren DB-Status zurückzusetzen – +ohne die gesamte Datenbank löschen zu müssen. + +--- + +## Hintergrund + +### Bisheriger Zustand +- Nach einem abgeschlossenen Lauf sind alle Ergebnisse in der Ergebnisliste sichtbar +- Dateien mit Status `FAILED_FINAL` oder `DONE` können nur durch manuelles Löschen der + SQLite-Datenbank erneut verarbeitet werden +- Es gibt keine Möglichkeit, einzelne Dateien selektiv zurückzusetzen oder neu zu starten + +### Motivation +- Nach Anpassung des Prompts oder Wechsel des KI-Modells sollen bereits verarbeitete Dateien + erneut verarbeitet werden können – ohne Datenverlust für andere Dokumente +- Permanent fehlgeschlagene Dateien sollen nach Behebung der Ursache gezielt neu gestartet + werden können +- Zwei klar getrennte Aktionen decken unterschiedliche Anwendungsfälle ab: + sofortige Wiederverarbeitung vs. Reset für den nächsten regulären Lauf + +--- + +## Zielbild + +Nach Abschluss von V2.8 kann der Benutzer: + +1. Eine oder mehrere Dateien in der Ergebnisliste selektieren +2. Per „Erneut verarbeiten" einen sofortigen Mini-Lauf nur für die selektierten Dateien starten +3. Per „Status zurücksetzen" den DB-Status zurücksetzen ohne sofortige Verarbeitung – + die Dateien werden beim nächsten regulären Lauf automatisch mitgenommen + +--- + +## Fachliche Anforderungen + +### Selektion in der Ergebnisliste + +- Es gibt genau **eine fachliche Selektion** je Ergebniszeile +- Checkbox, Zeilenklick, Shift/Strg und „Alle auswählen" wirken immer auf **dieselbe Selektionsmenge** +- Jede Zeile erhält eine **Checkbox** am linken Rand +- **Shift/Strg-Mehrfachselektion** wie im Windows Explorer ist möglich +- Eine Checkbox **„Alle auswählen"** oberhalb der Liste selektiert/deselektiert alle Einträge +- Alle Status sind selektierbar: ✔ erfolgreich, ⚠ retryable, ✘ permanent, ► übersprungen +- Die Selektion bleibt erhalten bis ein neuer Lauf gestartet wird +- Während eines laufenden Mini-Laufs ist die Selektion **gesperrt** – + Änderungen der Selektion nach Laufstart haben keinen Einfluss auf den laufenden Batch + +--- + +### Button „Erneut verarbeiten" + +- **Aktion:** DB-Status der selektierten Dateien zurücksetzen + sofortiger Mini-Lauf + nur für diese Dateien +- **Aktiv wenn:** Kein Lauf aktiv UND mindestens 1 Eintrag selektiert +- **Inaktiv wenn:** Lauf läuft ODER keine Selektion +- **Verhalten:** + - Der Mini-Lauf arbeitet auf einem **Snapshot** der beim Klick selektierten Einträge + - DB-Status aller selektierten Einträge wird zurückgesetzt + - Sofort danach startet ein Mini-Lauf ausschließlich für diese Dateien + - Die Ergebnisliste wird für die selektierten Einträge live aktualisiert + - Nicht selektierte Einträge bleiben unverändert in der Liste + - Der Mini-Lauf verhält sich fachlich wie ein regulärer Lauf – + gleiche Anwendungslogik, gleicher Use Case, nur eingeschränkte Dateimenge + +--- + +### Button „Status zurücksetzen" + +- **Aktion:** Nur DB-Status der selektierten Dateien zurücksetzen, keine sofortige Verarbeitung +- **Aktiv wenn:** Kein Lauf aktiv UND mindestens 1 Eintrag selektiert +- **Inaktiv wenn:** Lauf läuft ODER keine Selektion +- **Verhalten:** + - DB-Status aller selektierten Einträge wird zurückgesetzt + - Kein sofortiger Lauf + - Betroffene Zeilen bleiben in der Ergebnisliste sichtbar und erhalten die + Kennzeichnung **„Zurückgesetzt – wartet auf nächsten Lauf"** + - Beim nächsten regulären Lauf werden die zurückgesetzten Dateien automatisch mitgenommen +- **Fehlerbehandlung:** Reset läuft nach **Best-effort**-Prinzip – + erfolgreich zurückgesetzte Einträge werden zurückgesetzt, fehlgeschlagene bleiben + im alten Status; der Meldungs- und Zusammenfassungsbereich zeigt: + - Anzahl ausgewählter Einträge + - Anzahl erfolgreich zurückgesetzt + - Anzahl fehlgeschlagen + - Bei Fehlern: betroffene Dateinamen im Meldungsbereich + +--- + +### Welche Status können zurückgesetzt werden + +Alle Status sind zurücksetzbar: + +| UI-Status | DB-Status | Zurücksetzbar | Verhalten im nächsten regulären Lauf | +|---|---|---|---| +| ✔ Erfolgreich | `DONE` | Ja | Wird erneut verarbeitet | +| ⚠ Fehlgeschlagen retryable | `FAILED_RETRYABLE` | Ja | Wird erneut verarbeitet | +| ✘ Fehlgeschlagen permanent | `FAILED_FINAL` | Ja | Wird erneut verarbeitet | +| ► Übersprungen | `DONE` | Ja | DB-Eintrag `DONE` wird zurückgesetzt, wird erneut verarbeitet | + +--- + +### Verhalten bei vorhandener Zieldatei (Re-Run von DONE) + +Wird eine bereits erfolgreich verarbeitete Datei erneut verarbeitet: + +- **KI schlägt identischen Zieldateinamen vor** und Zieldatei ist bereits vorhanden: + Datei gilt als **✔ erfolgreich** – kein neuer Eintrag im Zielordner, kein Fehler +- **KI schlägt anderen Namen vor:** Normale Verarbeitung – + Dubletten-Suffix `(1)`, `(2)` wie im regulären Betrieb wenn nötig + +--- + +### Verhalten bei fehlender oder verschobener Quelldatei + +Ist die Quelldatei zum Zeitpunkt des Mini-Laufs nicht mehr vorhanden: + +- Eintrag erhält Status **✘ permanent fehlgeschlagen** +- Meldung: „Quelldatei nicht gefunden: {Dateiname}" +- Kein weiterer Retry + +--- + +### Verhalten während eines Mini-Laufs + +- Der **Abbrechen-Button** (Soft-Stop aus V2.7) gilt auch für den Mini-Lauf +- Bei Soft-Stop: + - Bereits erfolgreich verarbeitete Einträge behalten ihren neuen Endstatus + - Noch nicht gestartete, aber bereits zurückgesetzte Einträge behalten den Status + „Zurückgesetzt – wartet auf nächsten Lauf" und werden beim nächsten regulären Lauf mitgenommen + - Der Mini-Lauf endet im UI-Zustand „abgebrochen" mit Zusammenfassung +- Tab 1 „Konfiguration" wird während des Mini-Laufs gesperrt +- Fortschrittsbalken zeigt den Fortschritt des Mini-Laufs – + Nenner entspricht der Anzahl der selektierten Dateien +- Während eines Mini-Laufs sind „Erneut verarbeiten" und „Status zurücksetzen" deaktiviert +- Kein zweiter paralleler Lauf ist startbar + +--- + +### Scope dieser Funktion + +Die Funktion gilt ausschließlich für Einträge der **sichtbaren Ergebnisliste der aktuellen Sitzung**. +Beim Programmstart erfolgt keine Rekonstruktion der Ergebnisliste aus der DB. + +--- + +## Nicht in V2.8 enthalten + +- Historien-Tab / SQLite-Ansicht (V3.0) +- Bearbeitung des KI-Titels in der GUI +- Manuelles Überschreiben eines Ergebnisses +- Massenoperationen außerhalb der Ergebnisliste +- Automatischer Re-Run nach Konfigurationsänderung +- Rekonstruktion der Ergebnisliste beim Programmstart + +--- + +## Abnahmekriterien + +- [ ] Jede Zeile der Ergebnisliste hat eine Checkbox +- [ ] Checkbox und Zeilenklick repräsentieren dieselbe Selektionsmenge +- [ ] Shift/Strg-Mehrfachselektion funktioniert wie im Windows Explorer +- [ ] „Alle auswählen"-Checkbox selektiert/deselektiert alle Einträge +- [ ] Alle vier Status sind selektierbar +- [ ] Während eines laufenden Mini-Laufs kann die Selektion nicht verändert werden +- [ ] Button „Erneut verarbeiten" ist nur aktiv wenn kein Lauf läuft und mindestens 1 Eintrag selektiert ist +- [ ] Button „Status zurücksetzen" ist nur aktiv wenn kein Lauf läuft und mindestens 1 Eintrag selektiert ist +- [ ] „Erneut verarbeiten" setzt DB-Status zurück und startet sofortigen Mini-Lauf nur für selektierte Dateien +- [ ] Der Mini-Lauf verarbeitet genau die beim Start selektierten Einträge – spätere Selektionsänderungen haben keinen Einfluss +- [ ] „Status zurücksetzen" setzt nur den DB-Status zurück, betroffene Zeilen erhalten Kennzeichnung „Zurückgesetzt – wartet auf nächsten Lauf" +- [ ] Reset-Ergebnis zeigt Anzahl ausgewählter, erfolgreich zurückgesetzter und fehlgeschlagener Einträge +- [ ] Bei identischem Zieldateinamen gilt der Eintrag nach Re-Run als ✔ erfolgreich +- [ ] Fehlende Quelldatei führt zu ✘ permanent fehlgeschlagen mit Meldung +- [ ] Mini-Lauf zeigt korrekten Fortschrittsbalken für die selektierte Dateimenge +- [ ] Abbrechen-Button (Soft-Stop) funktioniert auch während eines Mini-Laufs +- [ ] Nach Soft-Stop: bereits verarbeitete Einträge behalten neuen Status, nicht gestartete bleiben „Zurückgesetzt" +- [ ] Tab 1 ist während des Mini-Laufs gesperrt +- [ ] Nicht selektierte Einträge bleiben nach „Erneut verarbeiten" unverändert in der Liste +- [ ] Beim nächsten regulären Lauf nach „Status zurücksetzen" werden zurückgesetzte Dateien mitgenommen +- [ ] Während eines Mini-Laufs sind beide Buttons deaktiviert +- [ ] headless-Betrieb ist unverändert funktionsfähig +- [ ] `mvn clean verify` ist grün