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

model

model
sonnet

AP07 – Ausgabeartefakte: Berichtdatei und Log-Datei mit Suffix-Logik

Meilenstein: M1 Vorgänger: AP04, AP05, AP06 ✅ erforderlich Nachfolger: AP08, AP10 Grundlage: docs/specs/technik-und-architektur.md v5, §§ „Ausgabeartefakte", „Zeichensätze", „Logging und Berichtserzeugung" Entscheidungsprotokoll: docs/arbeitspakete/m1/E00-entscheidungsprotokoll.md (E-04 logs/-Verzeichnis)

Ziel

Pro Lauf werden zwei Ausgabedateien im Verzeichnis der Eingabedatei erzeugt:

• eine Berichtdatei <basename>.txt
• eine Log-Datei <basename>.log

Beide in UTF-8. Der Bericht wird zusätzlich in die Konsole geschrieben. Bei bereits vorhandenen Dateien gleichen Namens werden neue mit laufendem Suffix _v1, _v2, … erzeugt.

Voraussetzungen

• AP04 (Logging-Adapter), AP05 (Befundmodell), AP06 (Bootstrap/CLI)

Scope IN

SuffixResolver im Paket adapter.out.filesystem

public class SuffixResolver {
    /**
     * Ermittelt den ersten freien Dateipfad für den gegebenen Basisnamen
     * und die gegebene Extension im Zielverzeichnis.
     * Probiert: <baseName>.<ext>, dann <baseName>_v1.<ext>, <baseName>_v2.<ext>, ...
     */
    public Path resolveNextFreePath(Path directory, String baseName, String extension) { ... }
}

• Suffix-Zählung ist pro Extension unabhängig — .txt und .log haben getrennte Zähler
• Unit-Tests mindestens für: keine Datei vorhanden, .txt vorhanden, .txt + _v1 vorhanden

ReportFileWriter im Paket adapter.out.reporting

• Eingabe: ValidationReport (AP05) + Eingabedatei-Pfad
• Ausgabe: UTF-8-Textdatei im Verzeichnis der Eingabedatei
• Dateiname via SuffixResolver
• Berichtinhalt für M1 (absichtlich minimal, wird in M9 ausgebaut):
  • Kopfzeile: Zeitstempel, Eingabedatei, Verdict
  • Pro Finding: eine Zeile mit Severity, Kind, Layer, Feld-ID, deutscher Meldung
  • Fußzeile: Hinweis auf bewusst nicht geprüfte Bereiche

Alle Texte auf Deutsch, Encoding UTF-8 explizit — kein Plattform-Default.

LoggingConfigurator.configureLogFile(Path) in adapter.out.logging

• Methode wird im Bootstrap vor dem ersten fachlichen Log-Aufruf aufgerufen
• Konfiguriert Log4j2-File-Appender programmatisch auf den gewünschten Pfad
• Dateiname via SuffixResolver (analog zur Berichtdatei, eigene Zählung)
• Log4j2-Typen (LoggerContext, Appender etc.) bleiben ausschließlich in adapter.out.logging und bootstrap
• Statischer logs/-Pfad aus log4j2.xml (AP04) wird entfernt oder auf Fallback-Default gesetzt, der nur greift wenn configureLogFile nicht aufgerufen wurde (z.B. für Testläufe)
• Fallback: Falls programmatische Log4j2-Umkonfiguration sich als instabil erweist, ist eine System-Property-basierte Konfiguration (-Dasv.log.file=...) ein zulässiger Ausweg — Entscheidung im Bericht dokumentieren

Integration in bootstrap.Main

Reihenfolge vor dem Validierungslauf:

1. Eingabedatei-Pfad bestimmen
2. Basisnamen und Zielverzeichnis ableiten
3. SuffixResolver für .log aufrufen
4. LoggingConfigurator.configureLogFile(logPath) aufrufen → ab jetzt gehen Logs in die Datei
5. Validierungslauf starten
6. ReportFileWriter schreiben
7. Konsolenausgabe (identisch zum Berichtinhalt)

Konsolenausgabe

• Schreibt denselben Text wie die Berichtdatei
• Erfolgt nach der Berichtdatei-Erstellung, damit ein IO-Fehler beim Schreiben die Konsolenausgabe nicht verhindert

Scope OUT

• Hierarchische Berichtsgliederung (M9)
• ANSI-Farben / Einfärbung in der Konsole
• Log-Rotation
• Minimalbericht bei Exit-Code 2 (AP08)

Schritte

1. SuffixResolver implementieren inkl. Unit-Tests
2. ReportFileWriter implementieren mit einfachem Zeilenformat für M1
3. LoggingConfigurator.configureLogFile(Path) implementieren
4. Bootstrap erweitern: Log-Datei-Pfad bestimmen → LoggingConfigurator aufrufen
5. CliRunner erweitern: nach Lauf → Berichtdatei schreiben → Konsolenausgabe
6. End-to-End-Test: beide Ausgabedateien entstehen, Suffix-Logik funktioniert, UTF-8
7. mvn clean verify grün bekommen
8. Abschlussbericht schreiben

Abnahmekriterien

• Nach Lauf mit foo/bar.auf entstehen foo/bar.auf.txt und foo/bar.auf.log
• Zweiter Lauf mit derselben Datei → 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 drei Unit-Tests
• Log4j2-Typen sind außerhalb von adapter.out.logging und bootstrap nicht sichtbar
• Statischer logs/-Pfad aus log4j2.xml entfernt oder auf Fallback-Default gesetzt
• mvn clean verify grün
• Abschlussbericht unter docs/arbeitspakete/m1/berichte/AP07-bericht.md

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).
• Das Bericht-Dateiformat ist in M1 absichtlich primitiv. In M9 wird es durch die finale hierarchische Struktur ersetzt.
• Fallback bei instabiler programmatischer Log4j2-Umkonfiguration im Bericht dokumentieren.

Bericht

docs/arbeitspakete/m1/berichte/AP07-bericht.md nach docs/arbeitspakete/m1/templates/ap-bericht.md.