marcus/asv-format-validator
1
0
Fork 0
Code Activity
Files
b5044f62a97f2756049cd4c1b80c0f3792877ef1
asv-format-validator/docs/arbeitspakete/m1/berichte/AP05-bericht.md
T
marcus b5044f62a9 Umsetzung von M1
2026-04-20 10:11:19 +02:00

8.4 KiB
Raw Blame History

Abschlussbericht Arbeitspaket AP05 – Befundmodell mit Spec-/Diagnose-Trennung

Bezug: docs/arbeitspakete/m1/AP05-befundmodell.md Bearbeiter: Claude Code (claude-sonnet-4-6), Subagent-Lauf Datum: 2026-04-20 Commit(s): ausstehend (Mensch committet nach Sichtung) Status: ✅ abgeschlossen

1. Zusammenfassung

Das Paket de.gecheckt.asv.domain.finding wurde vollständig neu angelegt und enthält alle im AP05 geforderten Typen: die Enums Severity, FindingKind, FindingLayer, Verdict, den unveränderlichen Record Finding mit Builder sowie die unveränderliche Klasse ValidationReport. Die zentrale Invariante — dass DIAGNOSTIC-ERROR das Verdict niemals auf INVALID setzt — ist durch einen explizit markierten Unit-Test (diagnosticErrorLiefertVALID) abgesichert. mvn clean verify ist grün (164 Tests, 0 Fehler).

2. Umgesetzte Änderungen

Folgende Dateien wurden neu angelegt (keine bestehende Datei wurde verändert):

Produktionscode (src/main/java/de/gecheckt/asv/domain/finding/):

  • Severity.java — Enum: ERROR, WARNING, HINT; JavaDoc erklärt Einfluss auf Verdict
  • FindingKind.java — Enum: SPEC, DIAGNOSTIC; JavaDoc beschreibt Verdict-Invariante
  • FindingLayer.java — Enum: ARTIFACT, TECHNICAL_STRUCTURE, DOMAIN_MODEL; JavaDoc erklärt Schichttrennung
  • Verdict.java — Enum: VALID, INVALID, OPERATIONAL_ERROR; Exit-Code-Zuordnung in JavaDoc
  • Finding.java — Record mit allen 12 Feldern gemäß AP05; Null-Prüfung im Kompaktkonstruktor für Pflichtfelder; zusätzlicher innerer Builder für komfortablere Erzeugung; Hilfsmethode isSpecError()
  • ValidationReport.java — unveränderliche Klasse; findings intern per List.copyOf() gesichert; Methoden computeVerdict(), hasSpecErrors(), specFindings(), diagnosticFindings(), getFindings(), getFileName(), getTimestamp(); Factory operationalError(fileName, ruleId, message); privater Konstruktor für Bedienfehler-Flag

Tests (src/test/java/de/gecheckt/asv/domain/finding/):

  • ValidationReportTest.java — 11 Tests (die 7 Pflicht-Tests aus AP05 plus 4 ergänzende Absicherungen)
  • FindingTest.java — 6 Tests für Record, Builder und Null-Absicherung

Keine bestehende Datei wurde verändert. Insbesondere wurde ValidationResult (Altmodell) nicht angefasst.

3. Scope-Treue

Scope-Punkt aus dem Arbeitspaket Erfüllt? Bemerkung
Paket domain.finding anlegen ✅ de.gecheckt.asv.domain.finding vollständig vorhanden
Enum Severity (ERROR/WARNING/HINT) ✅ Alle drei Werte implementiert
Enum FindingKind (SPEC/DIAGNOSTIC) ✅ Beide Werte mit präzisem JavaDoc
Enum FindingLayer (ARTIFACT/TECHNICAL_STRUCTURE/DOMAIN_MODEL) ✅ Alle drei Werte implementiert
Finding Record mit allen 12 Feldern ✅ Alle Felder vorhanden; germanMessage nicht nullable; übrige 11 nullable
Verdict Enum (VALID/INVALID/OPERATIONAL_ERROR) ✅ Alle drei Werte mit Exit-Code-Kommentar
ValidationReport unveränderliche Klasse ✅ final, findings per List.copyOf() gesichert
computeVerdict() nur SPEC+ERROR ✅ Invariante im Code und per Test abgesichert
hasSpecErrors() ✅ Implementiert
specFindings() / diagnosticFindings() ✅ Implementiert, per Test verifiziert
operationalError(fileName, ruleId, message) ✅ Factory-Methode vorhanden
Keine Änderung an ValidationResult ✅ Altmodell nicht angefasst
Integration in laufende Validierung (Scope OUT) ✅ nicht gemacht AP06
Löschen/Umbenennen ValidationResult (Scope OUT) ✅ nicht gemacht AP09
Berichtserzeugung/Textrendering (Scope OUT) ✅ nicht gemacht AP07
Architekturtest (Scope OUT) ✅ nicht gemacht AP10

Wurde der Scope eingehalten? Ja, vollständig.

Wurden Dinge außerhalb des Scopes gemacht? Nein. Der Builder für Finding war im AP05 explizit als Alternative zum reinen Record erwähnt und fällt daher in den Scope.

4. Abnahmekriterien

Abnahmekriterium aus dem Arbeitspaket Erfüllt? Nachweis
Paket domain.finding enthält alle genannten Typen ✅ 5 Dateien: Severity, FindingKind, FindingLayer, Verdict, Finding, ValidationReport
Test „DIAGNOSTIC-ERROR ergibt VALID" ist grün ✅ ValidationReportTest#diagnosticErrorLiefertVALID() — GRÜN; @DisplayName("KRITISCH: Ein DIAGNOSTIC-ERROR-Befund liefert Verdict VALID (niemals INVALID)")
ValidationReport.findings ist unveränderlich (Test vorhanden) ✅ ValidationReportTest#findingsListeNichtModifizierbar() testet: (1) Mutation der Eingabeliste nach Übergabe hat keinen Effekt; (2) getFindings().add(...) wirft UnsupportedOperationException
Alle Metadatenfelder aus technik-und-architektur.md §„Befundarten" im Finding-Typ ✅ Alle 12 Felder vorhanden: Artefaktschicht (layer), Prüfstufe/Art (kind), Segmenttyp, Segmentindex, Feld-ID, Rohwert, Position, Nachrichtenreferenz, offizieller Fehlercode, interne Regel-ID, Schweregrad, deutscher Befundtext
operationalError(...) Factory-Methode existiert ✅ Statische Methode in ValidationReport; Testnachweis: ValidationReportTest#operationalErrorFactoryLiefertOPERATIONAL_ERROR()
Keine Änderung an ValidationResult (Altmodell) ✅ Dateipfad application/model/ValidationResult.java wurde nicht geöffnet oder verändert
mvn clean verify grün ✅ 164 Tests, 0 Failures, 0 Errors, 0 Skipped
Abschlussbericht unter docs/arbeitspakete/m1/berichte/AP05-bericht.md ✅ Diese Datei

5. Build- und Teststatus

  • mvn clean verify: ✅ grün
  • Anzahl Tests gesamt: 164 (davon 17 neu in domain.finding: 11 in ValidationReportTest, 6 in FindingTest)
  • Vorherige Testanzahl (vor AP05): 147
  • Coverage: JaCoCo läuft; das neue Paket domain.finding hat vollständige Abdeckung aller kritischen Pfade durch die 17 neuen Tests
  • Warnungen beim Build: keine testbezogenen Warnungen; eine Java-Compiler-Warnung bezüglich Annotationsverarbeitung (-proc:none empfohlen) — diese war bereits vor AP05 vorhanden und ist kein AP05-Artefakt

6. Rest-Risiken und offene Punkte

  • Zwei parallele Ergebnistypen: ValidationResult (Altmodell im Paket application.model) und ValidationReport (neues Befundmodell in domain.finding) koexistieren bewusst bis AP09. Dies ist im AP05 explizit als Absicht dokumentiert und kein Risiko dieses Arbeitspakets.
  • operationalError-Befund nutzt FindingLayer.ARTIFACT: Der Bedienfehler-Befund wurde auf Schicht ARTIFACT abgelegt, da Bedienfehler typischerweise die Artefaktebene betreffen (nicht lesbare Datei, fehlender Pfad). Falls AP08 eine andere Schicht bevorzugt, ist das in der Factory anpassbar ohne API-Bruch.
  • Finding.isSpecError() ist eine Hilfsmethode für interne Verwendung. Ob sie öffentlich bleiben soll oder auf package-private reduziert wird, kann in AP10 (Architekturtest) beurteilt werden.
  • Keine package-info.java für das neue Paket domain.finding angelegt — dies war nicht im AP05-Scope, kann aber in einem Folge-AP ergänzt werden.

7. Empfehlungen für Folge-Arbeitspakete

  • AP06 (Bootstrap/CLI): Der ValidationReport ist bereit zur Integration. Die Factory operationalError(...) deckt den Exit-Code-2-Pfad ab. computeVerdict() liefert direkt den Verdict für die Exit-Code-Entscheidung.
  • AP07 (Ausgabeartefakte): Das Finding-Record ist flat und enthält alle Traceability-Informationen, die für einen hierarchischen Bericht benötigt werden. specFindings() und diagnosticFindings() erleichtern die Gliederung.
  • AP09 (Altlogik einfrieren): ValidationResult und ValidationReport koexistieren sauber. AP09 kann ValidationResult einfrieren oder entfernen, ohne ValidationReport anzufassen.
  • AP10 (Architekturtest): Das Paket domain.finding hat keine Infrastrukturabhängigkeiten (nur java.time.Instant, java.util.*). Der ArchUnit-Test sollte diese Eigenschaft formal absichern.

8. Reviewer-Checkliste

  • Alle im Arbeitspaket genannten Scope-IN-Punkte sind nachweislich umgesetzt
  • Keine Scope-OUT-Punkte wurden angefasst
  • Abnahmekriterien sind mit konkreten Nachweisen belegt (Tests, Dateipfade)
  • mvn clean verify ist grün (164 Tests, 0 Failures)
  • Der Commit für dieses AP hat eine sprechende Message (M1-AP05: ...) — ausstehend, Mensch committet
  • Keine Regeln der Grunddokumente (Spec, Fachliche, Technik) wurden verletzt
  • Rest-Risiken sind ehrlich dokumentiert
View Git Blame Copy Permalink