# AP05 – Befundmodell mit Spec-/Diagnose-Trennung

## Ziel

Im Paket `domain` ein **stabiles Befundmodell** einführen, das von Anfang an zwischen **Spec-Urteil** (verbindliches Prüfurteil gemäß Spezifikation) und **diagnostischer Weiteranalyse** (zusätzliche, das Spec-Urteil nicht verändernde Hinweise) unterscheidet. Dieses Modell ist das **Herzstück** für alle nachfolgenden Meilensteine.

Der bestehende Typ `de.gecheckt.asv.validation.model.ValidationResult` wird nicht einfach gelöscht, sondern **ersetzt** durch ein sauber geschnittenes Domain-Modell. Der alte Typ wird im Rahmen von AP09 eingefroren.

## Voraussetzungen

- AP03 (Paketstruktur)

## Scope IN

Folgende Typen im Paket `de.gecheckt.asv.domain.finding` (oder ähnliches Unterpaket von `domain`):

### `Severity` (Enum)
- `ERROR`
- `WARNING`
- `HINT`

### `FindingKind` (Enum)
- `SPEC` — Befund ist Teil des Spec-Urteils, beeinflusst `Verdict`
- `DIAGNOSTIC` — zusätzliche Weiteranalyse, beeinflusst `Verdict` **nicht**

### `FindingLayer` (Enum)
- `ARTIFACT` — äußeres Artefakt / Dateiebene
- `TECHNICAL_STRUCTURE` — Service-Segmente, KKS, Transport
- `DOMAIN_MODEL` — kanonisches Fachmodell (ASVREC/ASVFEH)

### `Finding` (Record)
```java
public record Finding(
    FindingKind kind,           // SPEC oder DIAGNOSTIC
    Severity severity,          // ERROR/WARNING/HINT
    FindingLayer layer,         // ARTIFACT/TECHNICAL_STRUCTURE/DOMAIN_MODEL
    String ruleId,              // interne Regel-ID, optional null
    String officialErrorCode,   // offizieller Fehlercode, optional null
    String segmentType,         // z.B. "UNB", optional
    Integer segmentIndex,       // optional
    String fieldId,             // z.B. "UNB_0020", optional
    String rawValue,            // Rohwert, optional
    Integer position,           // Byte-/Zeichenposition, optional
    String messageReference,    // UNH 0062 bei Nachrichtenbezug, optional
    String germanMessage        // deutscher Befundtext
) {}
```
Records mit vielen optionalen Feldern sind unschön — als Alternative ist eine reguläre Klasse mit Builder erlaubt, solange sie unveränderlich (`final`) ist und die gleichen Felder trägt. **Wichtig ist: unveränderlich und mit allen Metadaten aus `technik-und-architektur.md` Abschnitt „Befundarten".**

### `Verdict` (Enum)
- `VALID` — keine Spec-ERROR-Befunde
- `INVALID` — mindestens ein Spec-ERROR-Befund
- `OPERATIONAL_ERROR` — Bedienfehler (Exit-Code 2)

### `ValidationReport` (Klasse)
- unveränderlich
- enthält:
  - `List<Finding> findings` (alle Befunde, SPEC und DIAGNOSTIC gemischt, Reihenfolge erhalten)
  - Methode `Verdict computeVerdict()` — berücksichtigt **nur** `kind == SPEC` und `severity == ERROR`
  - Methode `List<Finding> specFindings()` — filtert auf `kind == SPEC`
  - Methode `List<Finding> diagnosticFindings()` — filtert auf `kind == DIAGNOSTIC`
  - Methode `boolean hasSpecErrors()`
  - Metadaten: `String fileName`, `Instant timestamp`
- **invariant:** eine `DIAGNOSTIC`-Severity `ERROR` darf das Verdict **niemals** auf `INVALID` setzen. Dies ist per Unit-Test abzusichern.

### Unit-Tests
- `ValidationReport` ohne Befunde → `Verdict.VALID`
- `ValidationReport` mit einem SPEC-ERROR → `Verdict.INVALID`
- `ValidationReport` mit einem DIAGNOSTIC-ERROR → `Verdict.VALID` (dieser Test ist kritisch!)
- `ValidationReport` mit SPEC-WARNING → `Verdict.VALID` (nur ERROR zählt)
- `specFindings()` / `diagnosticFindings()` filtern korrekt
- Unveränderlichkeit: `findings`-Liste ist nicht modifizierbar

## Scope OUT

- Integration des neuen Modells in den bestehenden Lauf (kommt in AP06)
- Löschen oder Umbenennen der alten `validation.model.ValidationResult`-Klasse (das ist Teil von AP09)
- Berichtserzeugung (Text-Rendering), Bericht-Format, Konsolenausgabe (kommt in AP07)
- Architekturtest (kommt in AP10)

## Schritte

1. Branch `m1/ap05-befundmodell`
2. Paket `de.gecheckt.asv.domain.finding` anlegen
3. Enums und Klassen implementieren
4. Unit-Tests schreiben, mindestens die sechs oben genannten
5. `mvn clean verify` grün bekommen
6. Commit `M1-AP05: Befundmodell mit Spec-/Diagnose-Trennung`
7. Abschlussbericht schreiben

## Abnahmekriterien

- Paket `domain.finding` enthält alle oben genannten Typen
- **Der Test „DIAGNOSTIC-ERROR ergibt VALID" ist grün** und wird im Bericht explizit genannt
- `ValidationReport.findings` ist unveränderlich (Test vorhanden)
- alle Metadaten-Felder aus `technik-und-architektur.md` Abschnitt „Befundarten" sind im `Finding`-Typ vorhanden
- `mvn clean verify` ist grün
- keine Änderung an `validation.model.ValidationResult` (Altmodell)
- Abschlussbericht liegt vor

## Rest-Risiken und offene Punkte

- Wir haben jetzt zwei parallele Ergebnis-Typen: den alten `ValidationResult` und den neuen `ValidationReport`. Das ist **Absicht** bis AP09, wo die alte Logik sauber eingefroren wird.
- Das Befundmodell ist bewusst **keine** Hierarchie (Datei → Schicht → Nachricht → Befund), sondern eine flache Liste mit Metadaten. Die hierarchische Berichtserzeugung passiert später auf Basis dieser Metadaten in M9. Für M1 genügt die flache Struktur.

## Bericht

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