Dokumentation und Arbeitspakete angelegt

docs/arbeitspakete/m1/AP08-minimalbericht.md

@@ -0,0 +1,80 @@
+# AP08 – Minimalbericht bei Bedienfehlern (Exit-Code 2)
+
+## 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."
+
+## Voraussetzungen
+
+- AP06 (CLI), AP07 (Ausgabeartefakte)
+
+## Scope IN
+
+### Bedienfehler-Fälle
+Alle diese Fälle müssen in Exit-Code `2` mit Minimalbericht resultieren:
+
+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
+
+### Minimalbericht-Inhalt
+Der Minimalbericht ist ein **`ValidationReport`** (aus AP05) mit:
+- `fileName` = übergebener Pfad (oder Platzhalter `<kein Argument>` bzw. `<mehrere Argumente>`)
+- `timestamp` = jetzt
+- genau ein `Finding`:
+  - `kind = SPEC`
+  - `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.
+
+### 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."
+
+### 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
+
+## Scope OUT
+
+- Unterscheidung zwischen verschiedenen IO-Exceptions im Detail (`FileSystemException`, `AccessDeniedException`, …) — 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
+
+## 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
+
+## 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.
+
+## Bericht
+
+`docs/arbeitspakete/m1/berichte/AP08-bericht.md` nach `templates/ap-bericht.md`.