MET-07: Sidecar-Beschreibung, Betriebsprobe

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

deploy/kosit/README.md

@@ -0,0 +1,57 @@
+# KoSIT-Validator als Sidecar (MET-07)
+
+Prüft E-Rechnungen (XRechnung, ZUGFeRD/Factur-X) gegen XSD und Schematron. Läuft als
+eigener Dienst, nur auf `127.0.0.1:8610` (DMS-Portbereich 8600-8699, `deploy/ports.tsv`).
+Der DMS-Worker spricht ihn über `NEXARCH_DMS_WORKER_KOSIT_ADDR` an. Ohne diese Variable
+ist das Ergebnis immer `not_checked`.
+
+## Bestandteile (feste Versionen, Prüfsummen SHA-256)
+
+| Datei | Version | SHA-256 |
+|---|---|---|
+| Temurin JRE (Linux x64) | 21.0.12.1 | `2413149700df0f7d440500a84a8f764c535f21e5a5e87d38328b64eec2c5b500` |
+| `validator-1.6.3-standalone.jar` | 1.6.3 | `799e64befca97d4080e03608c80b85dd5a5ecc5f4ae4f35d1116ec2855b9a7c9` |
+| `xrechnung-3.0.2-validator-configuration-2026-08-31.zip` | XRechnung 3.0.2, Regelwerk 2026-08-31 | `2530cd107c414511c5d0462ec10f886910395abfca820db82e83d70bf01221a8` |
+
+Quellen: `github.com/adoptium/temurin21-binaries`, `github.com/itplr-kosit/validator`,
+`github.com/itplr-kosit/validator-configuration-xrechnung`. Versionen unter 1.6.3 nicht
+verwenden (Lücke bei der URI-Auflösung im STRICT_LOCAL-Modus).
+
+## Installation (nur unter /opt/nexarch-kosit, nichts am System ändern)
+
+```
+useradd --system --no-create-home --home-dir /opt/nexarch-kosit --shell /usr/sbin/nologin nexarch-kosit
+mkdir -p /opt/nexarch-kosit/{dl,jre,validator,config}
+# Downloads nach dl/, Prüfsummen mit sha256sum -c prüfen, dann:
+tar xzf dl/jre.tgz -C /opt/nexarch-kosit/jre --strip-components=1
+cp dl/validator-standalone.jar /opt/nexarch-kosit/validator/
+unzip -q dl/config.zip -d /opt/nexarch-kosit/config
+chown -R root:root /opt/nexarch-kosit && chmod -R go-w /opt/nexarch-kosit
+cp nexarch-dms-kosit.service /etc/systemd/system/
+systemctl daemon-reload && systemctl enable --now nexarch-dms-kosit
+```
+
+Der Start dauert etwa 20 Sekunden (Laden der Szenarien). Der Dienst hat `MemoryMax=768M`,
+`-Xmx384m` und läuft ohne Rechte außerhalb von `/opt/nexarch-kosit`.
+
+## Betrieb
+
+- Worker: `NEXARCH_DMS_WORKER_KOSIT_ADDR=http://127.0.0.1:8610`,
+  `NEXARCH_DMS_WORKER_KOSIT_RULESET=xrechnung-3.0.2-2026-08-31` (Bezeichnung des installierten
+  Regelwerks, wird im Ergebnis gespeichert), optional `NEXARCH_DMS_WORKER_KOSIT_TIMEOUT_SECONDS`.
+- Regelwerk-Update: Konfigurationspaket austauschen, Dienst neu starten, `..._RULESET` ändern,
+  Worker neu starten. Der Worker reiht beim Start die Neuprüfung aller Rechnungen ein, deren
+  letztes Ergebnis nicht zum neuen Regelwerk passt oder `not_checked` ist. Alte Ergebnisse bleiben.
+- Der Daemon hat keine Zugriffskontrolle: nie an eine andere Adresse als Loopback binden.
+
+## Rückbau
+
+```
+systemctl disable --now nexarch-dms-kosit
+rm /etc/systemd/system/nexarch-dms-kosit.service && systemctl daemon-reload
+rm -rf /opt/nexarch-kosit
+userdel nexarch-kosit
+```
+
+Bereits abgelegte Ergebnisse (`revision_einvoice_conformance`) bleiben erhalten; ohne Validator
+entstehen neue Ergebnisse mit `not_checked`.

deploy/ports.tsv

@@ -11,3 +11,4 @@ mail	8700	8799
 workflow	8800	8899
 ai	8900	8999
 connect	9500	9599
+# dms-Port 8610: KoSIT-Validator (MET-07, nur 127.0.0.1), siehe deploy/kosit/README.md

dms/internal/einvoice/conformance_test.go

@@ -364,3 +364,21 @@ func ublInvoiceID(t *testing.T, data []byte) string {
 	}
 	return string(m[1])
 }
+
+// Betriebsprobe (Pruefung 2): der Aufrufer stoppt, blockiert oder startet den
+// Validator und gibt das erwartete Ergebnis in TEST_KOSIT_EXPECT vor.
+func TestKoSIT_LiveOutcomeMatchesExpectation(t *testing.T) {
+	want := os.Getenv("TEST_KOSIT_EXPECT")
+	if want == "" {
+		t.Skip("TEST_KOSIT_EXPECT nicht gesetzt")
+	}
+	v, err := NewValidator(os.Getenv("TEST_KOSIT_ADDR"), "probe", 3*time.Second)
+	if err != nil || v == nil {
+		t.Fatalf("validator: %v", err)
+	}
+	out := v.Validate(context.Background(), kositFixture(t, "01.01a-INVOICE_ubl.xml"))
+	t.Logf("status=%s grund=%q", out.Status, out.Reason)
+	if out.Status != want {
+		t.Fatalf("status %q, erwartet %q", out.Status, want)
+	}
+}