Umsetzung von M1

docs/arbeitspakete/m1/AP08-minimalbericht.md

@@ -1,8 +1,16 @@
+---
+model: sonnet
+---
 # AP08 – Minimalbericht bei Bedienfehlern (Exit-Code 2)
 
+> **Meilenstein:** M1
+> **Vorgänger:** AP06, AP07 ✅ erforderlich
+> **Nachfolger:** AP10, AP11
+> **Grundlage:** `docs/specs/technik-und-architektur.md` v5, §§ „Gültigkeitsentscheidung und Exit-Codes", „Laufzeit- und Betriebsmodell"
+
 ## Ziel
 
-Auch bei **Bedien- oder Zugriffsfehlern** (Exit-Code `2`) soll ein **Minimalbericht** entstehen, der den Fehler nachvollziehbar beschreibt. Das verlangt `technik-und-architektur.md` ausdrücklich: „Auch bei Exit-Code 2 soll, soweit technisch möglich, ein Minimalbericht erzeugt werden, der den Bedien- oder Zugriffsfehler nachvollziehbar beschreibt."
+Auch bei **Bedien- oder Zugriffsfehlern** (Exit-Code `2`) entsteht ein **Minimalbericht**, der den Fehler nachvollziehbar beschreibt. `technik-und-architektur.md` verlangt das ausdrücklich: „Auch bei Exit-Code 2 soll, soweit technisch möglich, ein Minimalbericht erzeugt werden."
 
 ## Voraussetzungen
 
@@ -10,71 +18,69 @@ Auch bei **Bedien- oder Zugriffsfehlern** (Exit-Code `2`) soll ein **Minimalberi
 
 ## Scope IN
 
-### Bedienfehler-Fälle
-Alle diese Fälle müssen in Exit-Code `2` mit Minimalbericht resultieren:
+### Bedienfehler-Fälle (alle müssen Exit-Code `2` + Minimalbericht ergeben)
 
-1. **Kein Argument übergeben** → Minimalbericht auf Konsole (Eingabeverzeichnis unbekannt, also keine Dateiausgabe möglich)
-2. **Mehr als ein Argument** → Minimalbericht auf Konsole
-3. **Eingabedatei existiert nicht** → Minimalbericht auf Konsole und falls möglich in das übergeordnete Verzeichnis (dort wo die Datei hätte liegen sollen), sonst nur Konsole
-4. **Eingabepfad ist kein regulärer Dateityp** (z.B. Verzeichnis) → Minimalbericht auf Konsole, keine Dateiausgabe
-5. **Eingabedatei ist nicht lesbar** (Permissions) → Minimalbericht auf Konsole, Dateiausgabe wird versucht wenn Zielverzeichnis schreibbar ist, sonst nur Konsole
+1. **Kein Argument** → nur Konsolenausgabe (Eingabeverzeichnis unbekannt)
+2. **Mehr als ein Argument** → nur Konsolenausgabe
+3. **Eingabedatei existiert nicht** → Konsolenausgabe + Berichtdatei im übergeordneten Verzeichnis, sofern dieses schreibbar ist
+4. **Eingabepfad ist kein regulärer Dateityp** (z.B. Verzeichnis) → nur Konsolenausgabe
+5. **Eingabedatei ist nicht lesbar** (Berechtigungen) → Konsolenausgabe + Berichtdatei sofern Zielverzeichnis schreibbar
 
 ### Minimalbericht-Inhalt
-Der Minimalbericht ist ein **`ValidationReport`** (aus AP05) mit:
-- `fileName` = übergebener Pfad (oder Platzhalter `<kein Argument>` bzw. `<mehrere Argumente>`)
+
+Ein `ValidationReport` (AP05) via `ValidationReport.operationalError(...)` mit:
+- `fileName` = übergebener Pfad (oder `<kein Argument>` / `<mehrere Argumente>`)
 - `timestamp` = jetzt
-- genau ein `Finding`:
-  - `kind = SPEC`
+- Genau ein `Finding`:
+  - `kind = SPEC` → Verdict wird `OPERATIONAL_ERROR`
   - `severity = ERROR`
   - `layer = ARTIFACT`
-  - `ruleId = "OPERATIONAL-<fallkennung>"` (z.B. `OPERATIONAL-MISSING-ARG`, `OPERATIONAL-FILE-NOT-FOUND`, `OPERATIONAL-NOT-READABLE`, `OPERATIONAL-NOT-REGULAR`, `OPERATIONAL-TOO-MANY-ARGS`)
-  - `germanMessage` = kurzer, verständlicher deutscher Text
-- **wichtig:** das Verdict dieses Reports ist **nicht** `INVALID`, sondern `OPERATIONAL_ERROR`. Die `Verdict`-Ableitungslogik muss in AP05 bereits den Fall „nur OPERATIONAL-Findings" erkennen können — falls das in AP05 noch nicht vorgesehen wurde, muss `ValidationReport` hier minimal erweitert werden.
-- Alternative, sauberere Modellierung: ein zusätzlicher Konstruktor oder Factory-Methode `ValidationReport.operationalError(String fileName, String ruleId, String message)`, der den Verdict-Status explizit auf `OPERATIONAL_ERROR` setzt.
+  - `ruleId` = z.B. `OPERATIONAL-MISSING-ARG`, `OPERATIONAL-FILE-NOT-FOUND`, `OPERATIONAL-NOT-READABLE`, `OPERATIONAL-NOT-REGULAR`, `OPERATIONAL-TOO-MANY-ARGS`
+  - `germanMessage` = kurzer verständlicher deutscher Text
 
-### Dateiausgabe bei Exit-Code 2
-- wenn das Zielverzeichnis ermittelbar und schreibbar ist: Berichtdatei wird gemäß AP07-Logik erzeugt
-- wenn nicht: **nur Konsolenausgabe**, keine Fehlermeldung („Bericht konnte nicht geschrieben werden"), weil das den Benutzer doppelt verunsichert
-- eine kurze Hinweiszeile auf der Konsole ist okay: „Bericht konnte nicht in das Verzeichnis geschrieben werden, siehe Konsolenausgabe oben."
+### Wichtige Regeln
 
-### Logging
-- der Minimalbericht wird zusätzlich **geloggt** (`logger.error(...)`) — damit in der Log-Datei (sofern erzeugt) dokumentiert ist, was schiefging
-- bei Fall 1 und 2 (keine Dateipfadinformation) ist die Log-Datei nicht sinnvoll zu platzieren → Fallback auf `log4j2.xml`-Default aus AP04
+- **Kein Stack-Trace für den Nutzer** — technische Details gehören ins Log, nicht in den Bericht
+- Wenn Zielverzeichnis nicht schreibbar: **nur Konsolenausgabe**, kein Fehler-auf-Fehler
+- Eine kurze Hinweiszeile auf Konsole ist okay: „Bericht konnte nicht in das Verzeichnis geschrieben werden."
+- Der Bedienfehler wird zusätzlich geloggt (`logger.error(...)`)
+
+### Tests
+
+- Unit-Test für alle fünf Fälle: Exit-Code `2` + korrekter `ruleId`-Wert
+- Negativ-Test: kein Stack-Trace in der Ausgabe
+- Test: Fall 3 (Datei nicht vorhanden) → Berichtdatei im übergeordneten Verzeichnis, wenn schreibbar
 
 ## Scope OUT
 
-- Unterscheidung zwischen verschiedenen IO-Exceptions im Detail (`FileSystemException`, `AccessDeniedException`, …) — ein einheitlicher Fall „nicht lesbar" reicht
+- Unterscheidung feingranularer IO-Exceptions (`AccessDeniedException`, `FileSystemException` etc.) — ein einheitlicher Fall „nicht lesbar" reicht
 - Internationalisierung
 - Exit-Codes jenseits von `0/1/2`
-- Behandlung von `OutOfMemoryError`, `StackOverflowError` etc.
 
 ## Schritte
 
-1. Branch `m1/ap08-minimalbericht`
-2. Factory-Methode `ValidationReport.operationalError(...)` in AP05-Modell ergänzen (falls noch nicht vorhanden)
-3. `CliRunner` um die fünf Bedienfehler-Fälle erweitern; pro Fall wird der passende Minimalbericht erzeugt
-4. `ReportFileWriter`: im OPERATIONAL-Fall weichere IO-Fehlerbehandlung (keine `RuntimeException`, stattdessen Konsolenhinweis)
-5. Unit-Tests für alle fünf Fälle
-6. End-to-End-Test: `java -jar ... /pfad/zu/nichtvorhandener/datei.auf` erzeugt auf Konsole einen Minimalbericht und Exit-Code `2`
-7. `mvn clean verify` grün
-8. Commit `M1-AP08: Minimalbericht bei Exit-Code 2`
-9. Abschlussbericht schreiben
+1. `ValidationReport.operationalError(...)` prüfen — falls noch nicht vollständig in AP05 implementiert, hier ergänzen
+2. `CliRunner` um alle fünf Bedienfehler-Fälle erweitern
+3. `ReportFileWriter`: im `OPERATIONAL_ERROR`-Fall weichere IO-Fehlerbehandlung (kein `RuntimeException`, stattdessen Konsolenhinweis)
+4. Unit-Tests für alle fünf Fälle
+5. `mvn clean verify` grün bekommen
+6. Abschlussbericht schreiben
 
 ## Abnahmekriterien
 
-- alle fünf Bedienfehler-Fälle erzeugen einen Minimalbericht (per Unit-Test belegt)
-- Exit-Code in allen fünf Fällen ist `2`
-- Im Fall „Eingabedatei existiert nicht" wird der Minimalbericht in das übergeordnete Verzeichnis geschrieben, sofern dieses schreibbar ist
-- Im Fall „kein Argument" wird der Minimalbericht **nur** auf Konsole ausgegeben (keine Dateiausgabe)
-- `Verdict.OPERATIONAL_ERROR` ist in mindestens einem Test verifiziert
-- `mvn clean verify` ist grün
-- Abschlussbericht liegt vor
+- [ ] Alle fünf Bedienfehler-Fälle erzeugen Exit-Code `2` (per Unit-Test belegt)
+- [ ] Fall „kein Argument" → **nur** Konsolenausgabe, keine Dateiausgabe
+- [ ] Fall „Datei nicht vorhanden" → Berichtdatei im übergeordneten Verzeichnis, sofern schreibbar
+- [ ] `Verdict.OPERATIONAL_ERROR` ist in mindestens einem Test verifiziert
+- [ ] Kein Stack-Trace in STDERR (Negativ-Test vorhanden)
+- [ ] `mvn clean verify` grün
+- [ ] Abschlussbericht unter `docs/arbeitspakete/m1/berichte/AP08-bericht.md`
 
 ## Rest-Risiken und offene Punkte
 
-- Im Fall „Eingabedatei existiert nicht, Zielverzeichnis aber schon" ist der Bericht-Basisname der **angegebene** Dateiname (obwohl die Datei nicht existiert). Das ist okay — der Benutzer findet den Bericht dort, wo er die Datei erwartet hätte.
-- Die Unterscheidung zwischen `OPERATIONAL_ERROR` und `INVALID` im Verdict ist wichtig für spätere Reporting-Logik. Falls sich herausstellt, dass `OPERATIONAL_ERROR` als separater Verdict-Wert zu Komplikationen führt, kann alternativ ein Boolean-Flag `isOperational` auf dem Report verwendet werden. Entscheidung im Bericht dokumentieren.
+- Im Fall „Datei nicht vorhanden, Zielverzeichnis aber existiert" ist der Basisname der **angegebene** Dateiname — der Nutzer findet den Bericht dort, wo er die Datei erwartet hätte.
+- Falls `Verdict.OPERATIONAL_ERROR` als separater Wert zu Komplikationen führt: Boolean-Flag `isOperational` auf dem Report ist zulässiger Ausweg — Entscheidung im Bericht dokumentieren.
 
 ## Bericht
 
-`docs/arbeitspakete/m1/berichte/AP08-bericht.md` nach `templates/ap-bericht.md`.
+`docs/arbeitspakete/m1/berichte/AP08-bericht.md` nach `docs/arbeitspakete/m1/templates/ap-bericht.md`.