Spezifikation für V2.8 hinzugefügt

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