83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
# AP07 – Ausgabeartefakte: Berichtdatei und Log-Datei mit Suffix-Logik
|
||
|
||
## Ziel
|
||
|
||
Pro Lauf werden **zwei Ausgabedateien** im **Verzeichnis der Eingabedatei** erzeugt:
|
||
- eine **Berichtdatei** `<basename>.txt`
|
||
- eine **Log-Datei** `<basename>.log`
|
||
|
||
Beide in **UTF-8**. Zusätzlich wird der Bericht weiterhin in die **Konsole** geschrieben. Wenn bereits gleichnamige Dateien existieren, werden neue mit laufendem Suffix `_v1`, `_v2`, … erzeugt, **pro Eingabedatei-Basisname**.
|
||
|
||
## Voraussetzungen
|
||
|
||
- AP04 (Logging-Adapter), AP05 (Befundmodell), AP06 (Bootstrap/CLI)
|
||
|
||
## Scope IN
|
||
|
||
### Berichtdatei
|
||
- Klasse `ReportFileWriter` oder ähnlich im Paket `adapter.out.reporting`
|
||
- Eingabe: `ValidationReport` (aus AP05) und Eingabedatei-Pfad
|
||
- Ausgabe: eine UTF-8-Textdatei im **selben Verzeichnis** wie die Eingabedatei
|
||
- Dateiname: `<basename-der-eingabedatei>.txt`, bei Konflikt `<basename>_v1.txt`, `<basename>_v2.txt`, …
|
||
- Inhalt für M1: **einfach gehalten**. Pro `Finding` eine Zeile mit den wichtigsten Metadaten (Severity, Kind, Layer, Feld-ID, deutsche Nachricht). Kopfzeile mit Dateiname, Zeitstempel, Verdict. Die fein strukturierte hierarchische Darstellung kommt erst in M9.
|
||
|
||
### Log-Datei
|
||
- Wiederverwendung des `LoggingConfigurator` aus AP04
|
||
- Methode `configureLogFile(Path logFile)` wird im Bootstrap **vor** dem CLI-Runner aufgerufen
|
||
- Log-Datei liegt im **selben Verzeichnis** wie die Eingabedatei
|
||
- Dateiname: `<basename>.log`, Suffix-Logik analog zur Berichtdatei
|
||
- Log4j2 wird programmatisch umkonfiguriert: der File-Appender schreibt nach dem neuen Pfad. Die statische `log4j2.xml` aus AP04 ist nur der Fallback für „kein Eingabeargument".
|
||
|
||
### Suffix-Logik
|
||
- eigene kleine Utility-Klasse `SuffixResolver` im Paket `adapter.out.filesystem`
|
||
- Methode `Path resolveNextFreePath(Path baseDirectory, String baseName, String extension)`:
|
||
- probiert `<baseName>.<ext>`, dann `<baseName>_v1.<ext>`, `<baseName>_v2.<ext>`, …
|
||
- gibt den ersten freien Pfad zurück
|
||
- wird sowohl für die Berichtdatei als auch für die Log-Datei verwendet
|
||
- **Hinweis:** Die Zählung ist pro Basisname unabhängig. Wenn für `test.auf.txt` schon `test.auf_v1.txt` existiert, aber für `test.auf.log` noch keine `_v1`, kann das vorkommen — die Suffixe müssen **nicht synchron** sein.
|
||
|
||
### Konsolenausgabe
|
||
- bleibt erhalten, schreibt denselben Bericht-Text wie die Berichtdatei
|
||
- Konsolenausgabe erfolgt **nach** der Berichtdatei-Erstellung, damit ein IO-Fehler beim Schreiben der Berichtdatei nicht die Konsolenausgabe verhindert
|
||
|
||
## Scope OUT
|
||
|
||
- hierarchische Berichtsgliederung (M9)
|
||
- Einfärbung / ANSI-Codes in der Konsole
|
||
- Log-Rotation
|
||
- Minimalbericht bei Exit-Code 2 (AP08)
|
||
|
||
## Schritte
|
||
|
||
1. Branch `m1/ap07-ausgabeartefakte`
|
||
2. `SuffixResolver` implementieren inkl. Unit-Tests für: keine Datei vorhanden, `.txt` vorhanden, `.txt` + `_v1` vorhanden, mehrere Lücken
|
||
3. `ReportFileWriter` implementieren mit einfachem Zeilenformat für M1
|
||
4. `LoggingConfigurator.configureLogFile(Path)` implementieren (programmatische Log4j2-Reconfiguration)
|
||
5. Bootstrap erweitern: vor CLI-Lauf → Log-Datei-Pfad bestimmen → `LoggingConfigurator` aufrufen
|
||
6. CLI-Runner erweitert: nach Lauf → Berichtdatei schreiben → Konsolenausgabe erzeugen
|
||
7. End-to-End-Test mit Dummy-Eingabedatei: beide Ausgabedateien entstehen, Suffix-Logik funktioniert
|
||
8. `mvn clean verify` grün
|
||
9. Commit `M1-AP07: Berichtdatei und Log-Datei im Eingabeverzeichnis mit Suffix-Logik`
|
||
10. Abschlussbericht schreiben
|
||
|
||
## Abnahmekriterien
|
||
|
||
- nach einem Lauf mit Eingabedatei `foo/bar.auf` existieren `foo/bar.auf.txt` und `foo/bar.auf.log`
|
||
- zweiter Lauf mit derselben Eingabedatei erzeugt `foo/bar.auf_v1.txt` und `foo/bar.auf_v1.log`
|
||
- dritter Lauf → `_v2` usw.
|
||
- beide Ausgabedateien sind UTF-8
|
||
- Konsolenausgabe ist identisch zum Inhalt der Berichtdatei
|
||
- `SuffixResolver` hat mindestens vier Unit-Tests
|
||
- `mvn clean verify` ist grün
|
||
- Abschlussbericht liegt vor
|
||
|
||
## Rest-Risiken und offene Punkte
|
||
|
||
- **Race Conditions** bei gleichzeitigen Läufen auf derselben Eingabedatei: laut `technik-und-architektur.md` bewusst nicht behandelt (kein Mehrbenutzerbetrieb in V1).
|
||
- Die programmatische Log4j2-Reconfiguration ist technisch nicht ganz ohne. Falls sie sich als zu instabil erweist, ist eine **sys-property-basierte** Konfiguration der Log-Datei (`-Dasv.log.file=...`) ein zulässiger Fallback. Entscheidung im Bericht dokumentieren.
|
||
- Das Bericht-Dateiformat ist in M1 absichtlich primitiv. In M9 wird es durch die finale hierarchische Struktur ersetzt.
|
||
|
||
## Bericht
|
||
|
||
`docs/arbeitspakete/m1/berichte/AP07-bericht.md` nach `templates/ap-bericht.md`.
|