Dokumentation und Arbeitspakete angelegt

2026-04-09 06:27:29 +02:00
parent fa36297e32
commit 79109594aa
13 changed files with 1069 additions and 0 deletions
--- a/docs/arbeitspakete/m1/AP10-architekturtest.md
+++ b/docs/arbeitspakete/m1/AP10-architekturtest.md
@@ -0,0 +1,110 @@
+# AP10 – Architekturtest
+
+## Ziel
+
+Ein **automatisierter Architekturtest** stellt sicher, dass die in M1 etablierten Strukturregeln auch in Zukunft eingehalten werden. Insbesondere darf:
+
+1. die **Log4j2-Bindung** nur in `adapter.out.logging` und `bootstrap` sichtbar sein
+2. das `domain`-Paket **nichts** aus Adaptern oder Infrastruktur importieren
+3. das `application`-Paket **nichts** aus konkreten Adaptern importieren, sondern nur aus `domain` und eigenen Ports
+4. **Preview-Code** nicht aus dem aktiven Code (Bootstrap, CLI-Adapter, Application) referenziert werden
+
+## Voraussetzungen
+
+- AP04 (Logging-Adapter), AP09 (Preview eingefroren)
+
+## Scope IN
+
+### Technische Umsetzung
+- **ArchUnit** (`com.tngtech.archunit:archunit-junit5`) als Test-Dependency aufnehmen
+- neue Test-Klasse `ArchitectureTest` im Paket `de.gecheckt.asv` im Testbereich
+- vier Tests:
+
+### Test 1: Log4j2-Sichtbarkeit
+```java
+@ArchTest
+static final ArchRule log4j2_nur_in_logging_adapter_und_bootstrap =
+    noClasses()
+        .that().resideOutsideOfPackages(
+            "de.gecheckt.asv.adapter.out.logging..",
+            "de.gecheckt.asv.bootstrap..")
+        .should().dependOnClassesThat()
+        .resideInAPackage("org.apache.logging.log4j..")
+        .because("Log4j2 darf nur im Logging-Adapter und im Bootstrap sichtbar sein.");
+```
+
+### Test 2: Domain ist frei
+```java
+@ArchTest
+static final ArchRule domain_hat_keine_adapter_abhaengigkeit =
+    noClasses()
+        .that().resideInAPackage("de.gecheckt.asv.domain..")
+        .should().dependOnClassesThat()
+        .resideInAnyPackage(
+            "de.gecheckt.asv.adapter..",
+            "de.gecheckt.asv.bootstrap..",
+            "de.gecheckt.asv.preview..");
+```
+
+### Test 3: Application ist frei von konkreten Adaptern
+```java
+@ArchTest
+static final ArchRule application_kennt_keine_adapter_implementierungen =
+    noClasses()
+        .that().resideInAPackage("de.gecheckt.asv.application..")
+        .should().dependOnClassesThat()
+        .resideInAnyPackage(
+            "de.gecheckt.asv.adapter..",
+            "de.gecheckt.asv.bootstrap..");
+```
+
+### Test 4: Preview wird nicht referenziert
+```java
+@ArchTest
+static final ArchRule preview_wird_nicht_aus_aktivem_code_referenziert =
+    noClasses()
+        .that().resideInAnyPackage(
+            "de.gecheckt.asv.adapter..",
+            "de.gecheckt.asv.application..",
+            "de.gecheckt.asv.bootstrap..",
+            "de.gecheckt.asv.domain..")
+        .should().dependOnClassesThat()
+        .resideInAPackage("de.gecheckt.asv.preview..")
+        .because("Preview-Code ist aus M1-Sicht eingefroren und wird erst ab M3 aktiv verwendet.");
+```
+
+### Zusätzlich: Paketstruktur-Check
+- Prüfen, dass die Soll-Pakete aus `technik-und-architektur.md` tatsächlich existieren (als ArchUnit-Regel oder einfacher Dateisystem-Test)
+
+## Scope OUT
+
+- komplexere Regeln wie „keine zyklischen Abhängigkeiten zwischen Paketen" — wäre schön, ist aber für M1 zu weitgehend
+- Regeln zu Klassenbenennung
+- Regeln zu `public`-Sichtbarkeit
+- Tests für Preview-internen Aufbau
+
+## Schritte
+
+1. Branch `m1/ap10-architekturtest`
+2. ArchUnit in `pom.xml` als Test-Dependency aufnehmen
+3. `ArchitectureTest`-Klasse im Testbereich anlegen
+4. Die vier Regeln implementieren
+5. `mvn clean verify` laufen lassen — die Tests müssen **grün** sein. Falls rot: **das heißt, eine frühere M1-Phase hat die Regel verletzt**. Die Verletzung muss gefunden und behoben werden (kein Entschärfen der Regel!).
+6. Commit `M1-AP10: Architekturtest für Log4j2-Sichtbarkeit, Paketabhängigkeiten, Preview-Isolation`
+7. Abschlussbericht schreiben
+
+## Abnahmekriterien
+
+- ArchUnit ist als Test-Dependency eingebunden
+- vier Architektur-Regeln sind implementiert und grün
+- `mvn clean verify` ist grün
+- Abschlussbericht liegt vor und dokumentiert, ob beim ersten Lauf Regeln rot waren und wenn ja, wie sie behoben wurden
+
+## Rest-Risiken und offene Punkte
+
+- ArchUnit hat beim ersten Einsatz manchmal Überraschungen mit transitiven Abhängigkeiten (Regel greift auch auf Framework-Klassen, die nicht gemeint waren). In dem Fall: Regel präzisieren, **nicht** ausschalten.
+- Die Regel „Log4j2-Sichtbarkeit" schließt auch den Bootstrap mit ein. Wenn der Bootstrap später (M8) Krypto-Typen referenziert, müssen analoge Regeln ergänzt werden — aber das ist M8-Thema.
+
+## Bericht
+
+`docs/arbeitspakete/m1/berichte/AP10-bericht.md` nach `templates/ap-bericht.md`.