---
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`) 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

- AP06 (CLI), AP07 (Ausgabeartefakte)

## Scope IN

### Bedienfehler-Fälle (alle müssen Exit-Code `2` + Minimalbericht ergeben)

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

Ein `ValidationReport` (AP05) via `ValidationReport.operationalError(...)` mit:
- `fileName` = übergebener Pfad (oder `<kein Argument>` / `<mehrere Argumente>`)
- `timestamp` = jetzt
- Genau ein `Finding`:
  - `kind = SPEC` → Verdict wird `OPERATIONAL_ERROR`
  - `severity = ERROR`
  - `layer = ARTIFACT`
  - `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

### Wichtige Regeln

- **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 feingranularer IO-Exceptions (`AccessDeniedException`, `FileSystemException` etc.) — ein einheitlicher Fall „nicht lesbar" reicht
- Internationalisierung
- Exit-Codes jenseits von `0/1/2`

## Schritte

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 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 „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 `docs/arbeitspakete/m1/templates/ap-bericht.md`.