Remove deprecated ZnsLegacyParsersTest.kt, synchronize database schema with Exposed domain models (migration V010), add license-related fields to Reiter, integrate updated LicenseMatrixService fallback logic, improve ZnsImportService with file archiving, and add ZNS testing runbook.

2026-04-06 01:45:49 +02:00
parent e94dc5a803
commit aa9e2da3a3
13 changed files with 260 additions and 283 deletions
@@ -0,0 +1,104 @@
+# 🐎 ZNS-Importer Test-Anleitung (Runbook)
+
+Diese Anleitung beschreibt den Prozess, um den ZNS-Importer in einer lokalen Entwicklungsumgebung zu starten und mit Postman vollständig zu testen.
+
+## 1. Infrastruktur starten (Docker)
+
+Bevor der Service gestartet werden kann, müssen die Basis-Dienste (Datenbank, Discovery, Auth) laufen.
+
+### 1.1 Docker Container starten
+Öffne ein Terminal im Projekt-Root (`/mocode/Meldestelle`) und führe folgenden Befehl aus:
+
+```bash
+docker compose up -d postgres consul keycloak valkey zipkin
+```
+
+### 1.2 Status prüfen
+Stelle sicher, dass alle Container "healthy" sind:
+* **PostgreSQL:** `localhost:5432`
+* **Consul UI:** [http://localhost:8500](http://localhost:8500) (Hier muss der Status aller Dienste grün sein)
+
+---
+
+## 2. Backend Services starten
+
+Der ZNS-Importer benötigt den `masterdata-service` (für die Datenbank-Tabellen) und den `zns-import-service`.
+
+### 2.1 Masterdata Service (DB-Migrationen)
+Starte den Masterdata-Service, damit die Tabellen (Verein, Reiter, Pferd, Funktionär) angelegt werden:
+```bash
+./gradlew :backend:services:masterdata:masterdata-service:bootRun
+```
+*Warte bis im Log erscheint: `Started MasterdataServiceApplication`*
+
+### 2.2 ZNS-Import Service
+Starte den Import-Service in einem neuen Terminal:
+```bash
+./gradlew :backend:services:zns-import:zns-import-service:bootRun
+```
+*Warte bis im Log erscheint: `Started ZnsImportServiceApplication`*
+
+---
+
+## 3. Postman Test-Ablauf
+
+### 3.1 Health-Check (Optionaler Smoke-Test)
+Prüfe ob der Service erreichbar ist:
+* **Methode:** `GET`
+* **URL:** `http://localhost:8095/actuator/health`
+* **Erwartetes Ergebnis:** `{"status":"UP"}`
+
+### 3.2 ZNS-ZIP Upload (Import starten)
+Dieser Schritt lädt die ZNS-Daten (ZIP-Datei mit .DAT Files) hoch und startet den asynchronen Prozess.
+
+* **Methode:** `POST`
+* **URL:** `http://localhost:8095/api/v1/import/zns`
+* **Body:** `form-data`
+    * Key: `file`
+    * Type: `File`
+    * Value: Wähle deine `ZNS_EXPORT.zip` aus.
+* **Erwartete Antwort (202 Accepted):**
+  ```json
+  {
+    "jobId": "7d3a...-..." 
+  }
+  ```
+  *(Kopiere die `jobId` für den nächsten Schritt!)*
+
+### 3.3 Status Polling
+Da der Import im Hintergrund läuft, musst du den Status abfragen:
+
+* **Methode:** `GET`
+* **URL:** `http://localhost:8095/api/v1/import/zns/{jobId}/status`
+* **Erwartete Antwort (währenddessen):** `status: "VERARBEITUNG"`
+* **Erwartete Antwort (Erfolg):**
+  ```json
+  {
+    "jobId": "...",
+    "status": "ABGESCHLOSSEN",
+    "fortschritt": 100,
+    "meldungen": ["Import erfolgreich: 4 Dateien verarbeitet (150 Reiter, 200 Pferde, ...)"]
+  }
+  ```
+
+---
+
+## 4. Erfolgskontrolle (Nach dem Import)
+
+### 4.1 Datenbank prüfen (pgAdmin / SQL)
+Prüfe in der Tabelle `reiter` oder `horse`, ob Daten vorhanden sind:
+```sql
+SELECT count(*) FROM reiter;
+SELECT * FROM horse LIMIT 10;
+```
+
+### 4.2 Archiv-Ordner
+Prüfe ob die Datei erfolgreich archiviert wurde:
+* Pfad (laut `application.yaml`): `/data/zns/archive` (oder der konfigurierte Pfad)
+* Die Datei sollte `zns_import_YYYYMMDD_HHMMSS.zip` heißen.
+
+## 5. Troubleshooting
+
+* **404 Not Found:** Prüfe ob der Service auf Port 8095 läuft.
+* **500 Internal Server Error:** Prüfe die Konsolenausgabe des `zns-import-service` auf Stacktraces.
+* **Import bleibt bei 0% hängen:** Prüfe ob die ZIP-Datei die richtigen Dateinamen enthält (z.B. `VEREIN01.DAT`, `LIZENZ01.DAT`).