87 lines
4.1 KiB
Markdown
87 lines
4.1 KiB
Markdown
---
|
||
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`.
|