81 lines
5.2 KiB
Markdown
81 lines
5.2 KiB
Markdown
# 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`.
|