Dokumentation und Arbeitspakete angelegt

docs/arbeitspakete/m1/AP07-ausgabeartefakte.md

@@ -0,0 +1,82 @@
+# 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`.