asv-format-validator/docs/arbeitspakete/m1/AP07-ausgabeartefakte.md

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.