meldestelle/docs/07_Infrastructure/runbooks/ZNS_Importer_Test_Manual.md

🐎 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:

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 (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:

./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:

./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):

  {
    "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):

  {
    "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:

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).