---
type: ADR
status: AKZEPTIERT
owner: Lead Architect
date: 2026-03-30
---

# ADR-0017: Einbettung des ZNS-Importers als Worker im Masterdata-SCS

## Status

Akzeptiert

## Kontext

Das Zentrale Nennungs-System (ZNS) liefert Stammdaten (Reiter, Pferde, Vereine, Funktionäre) in Form von ASCII-Dateien (
CP850). Diese Daten müssen regelmäßig importiert und aktualisiert werden.
Bisher gab es die Überlegung, den Importer als eigenständigen Dienst oder als Teil des Backends zu betreiben. Da die
Stammdaten jedoch das primäre Domänenmodell des `masterdata`-SCS sind, stellt sich die Frage nach der optimalen
architektonischen Einbettung.

## Entscheidung

Der ZNS-Importer wird als **dedizierter Worker-Thread/Service innerhalb des Masterdata-SCS** implementiert.

Details:

1. **Modul-Struktur**: Der `core:zns-parser` bleibt ein KMP-Modul für die reine Dateianalyse. Die Import-Logik (Mapping
   auf Domänen-Entitäten, Upserts in die DB) wird im `masterdata`-SCS angesiedelt.
2. **Ausführung**: Der Import läuft asynchron als Hintergrund-Task (Worker), um die API-Reaktionszeit nicht zu
   beeinträchtigen.
3. **Trigger**: Der Import kann über einen REST-Endpunkt (für Datei-Uploads) oder manuell via CLI/Trigger gestartet
   werden.
4. **Schreibkanal**: Der Importer ist der primäre Schreibkanal für Stammdaten im System. Direkte API-Schreibzugriffe auf
   Stammdaten sind in Phase 1 nicht vorgesehen (Read-Only API für externe Konsumenten).

## Konsequenzen

- **Positiv**: Starke Kohäsion, da die Datenhoheit und die Importlogik im selben SCS liegen.
- **Positiv**: Vereinfachte Persistenz, da der Worker direkt auf die Masterdata-DB zugreifen kann (kein
  Remote-API-Overhead).
- **Negativ**: Ressourcenverbrauch des Workers (CPU/RAM beim Parsen großer Dateien) teilt sich die Ressourcen mit der
  REST-API innerhalb des Containers. Dies muss über Limits (Docker/K8s) oder Task-Scheduling gesteuert werden.
- **Neutral**: Erfordert eine robuste Idempotenz-Logik, da Importe wiederholbar sein müssen (Checksum-Checks,
  Upsert-Semantik).

## Betrachtete Alternativen

- **Eigenständiger Microservice**: Wurde verworfen, um die Anzahl der zu betreibenden Dienste gering zu halten und "
  Database-per-Service" nicht durch geteilte Datenbankzugriffe zu verletzen (oder teure API-Synchronisation zu
  benötigen).
- **Integration in die GUI (Client-seitig)**: Verworfen, da die Datenhoheit im Server liegen muss und große Importe (
  100k+ Records) im Hintergrund auf dem Server stabiler laufen.

## Referenzen

- [Roadmap_ZNS_Importer.md](../../../docs/01_Architecture/Roadmap_ZNS_Importer.md)
- [ROADMAP.md](../ROADMAP.md)