mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4e8ed21ac0
meldestelle/docs/01_Architecture/Roadmap_ZNS_Importer.md
Stefan Mogeritsch 4e8ed21ac0 feat(docs): add ZNS-Importer roadmap and update MASTER_ROADMAP 
- Documented `Roadmap_ZNS_Importer.md` outlining goals, phases, and specifications for the ZNS importer MVP.
- Updated `MASTER_ROADMAP.md` to include ZNS roadmap reference and detailed task breakdown for ZNS importer.
- Marked progress on ÖTO/FEI rulebook tasks for CAN and CVN, with partial resolutions documented.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
2026-03-25 12:19:58 +01:00

4.2 KiB
Raw Blame History

type status owner last_update
Roadmap PLANNED Curator 2026-03-25

Roadmap: ZNS-Importer (MVP)

🧹 [Curator] | 25. März 2026

Kontext: Um den registration-context und actor-context unter realistischen Bedingungen testen zu können, benötigen wir echte Stammdaten (Reiter, Pferde, Vereine, Funktionäre). Diese Daten werden vom ÖPS (Österreichischer Pferdesportverband) in Form einer ZNS.zip bereitgestellt.

Ziel: Entwicklung eines asynchronen, robusten Importers für die Legacy-ZNS-Daten (ZNS.zip), der über die Compose-Desktop-App gesteuert wird und die Daten persistent im Backend (actor-context) ablegt.

1. Spezifikationen & Rahmenbedingungen

  • Dateiformat: Fixed-Width ASCII (Feste Spaltenbreiten, keine Trennzeichen).
  • Encoding: Zwingend Codepage 850 (CP850). (Achtung: Umlaute!).
  • Architektur-Muster: Asynchroner Upload & Processing (Job-Pattern).
  • Import-Reihenfolge (Abhängigkeiten beachten!):
    1. VEREIN01.dat (Vereine)
    2. LIZENZ01.dat (Reiter/Lizenzen)
    3. PFERDE01.dat (Pferde - benötigt Vereins-ID)
    4. RICHT01.dat (Richter/Parcoursbauer)

2. Phasen & Aufgabenverteilung

Phase 1: Backend-Infrastruktur & Parsing (👷 Backend Developer)

  • API Design:
  • POST /api/v1/import/zns (Multipart/form-data, nimmt .zip oder .dat entgegen).
  • Rückgabe: 202 Accepted mit einer JobId (UUID).
  • GET /api/v1/import/zns/{jobId}/status (Gibt aktuellen Fortschritt und Statusmeldungen zurück).
  • Job-Management:
  • Implementierung einer Thread-sicheren In-Memory-Registry oder einfachen DB-Tabelle für den Import-Status (z. B. " ENTPACKEN", "LADE_VEREINE_40%", "ABGESCHLOSSEN").
  • Unzip-Service:
  • Entpacken der übermittelten ZNS.zip in ein temporäres Verzeichnis (bzw. in den Speicher).
  • Legacy-Parser (CP850 Fixed-Width):
  • Schreiben von robusten Mapping-Funktionen, die die Strings bytegenau auslesen.
  • Berücksichtigung der Spezifikationen aus OETO-2026_Meldestelle_Pflichtenheft_V2.4_2021-07-28.md.

Phase 2: Domain-Mapping & Persistenz (👷 Backend Developer)

  • Mapper-Logik:
  • Konvertierung der geparsten Legacy-Daten in unsere Domain-Modelle (DomVerein, DomReiter, DomPferd, DomFunktionaer).
  • Sonderfälle:
    • PFERDE01.dat: Ausländische Systemnummern ignorieren (keine echten Lebensnummern).
    • LIZENZ01.dat: Sperrlisten-Flag (S) korrekt auf das DomReiter-Modell mappen.
  • Upsert-Strategie (DB):
  • Sicherstellen, dass bei mehrfachem Import keine Duplikate entstehen.
  • Abgleich über eindeutige ZNS-IDs (Satznummern). INSERT bei neuen, UPDATE bei bestehenden Datensätzen.

Phase 3: Frontend-Integration (🎨 Frontend Expert)

  • UI-Komponenten (Compose Desktop):
  • Erstellung eines "Stammdaten-Import" Screens in der Master-Desktop-App.
  • Integration eines nativen File-Pickers (nur Auswahl von .zip zulassen).
  • Netzwerk & State-Management (KMP):
  • Ktor-Client anpassen für Multipart-Uploads.
  • Implementierung eines Polling-Mechanismus: Nach erfolgreichem Upload alle X Sekunden den Status-Endpunkt abfragen.
  • User Feedback:
  • Anzeige einer Progress-Bar mit Live-Updates (z. B. "Verarbeite Reiter: 1250/5000").
  • Fehler-Handling (z. B. falsches Dateiformat, Timeouts) sauber darstellen.

Phase 4: Testing & QA (🧐 QA Specialist)

  • Test-Datensatz prüfen:
  • Einlesen der docs/OePS/ZNS.zip und Überprüfung der Umlaute (CP850 Encoding Test).
  • Abhängigkeits-Test:
  • Sicherstellen, dass Pferde korrekt ihren Vereinen zugeordnet werden.
  • Edge-Cases:
  • Upload einer fehlerhaften Zip-Datei.
  • Abbruch des Uploads/Imports.

3. Offene Fragen / Risiken

  • Werden die Legacy-Daten in der Datenbank (PostgreSQL) mit UUIDs oder mit den ZNS-Satznummern als Primary Keys abgelegt?
    • Architektur-Beschluss: Wir sollten interne UUIDs als Primary Keys verwenden und die ZNS-Nummern als eindeutige Business-Keys (UNIQUE CONSTRAINT) ablegen.
  • Wie gehen wir mit gelöschten Datensätzen aus dem ZNS um?
    • Vorerst: Der ZNS-Import ist ein "Add/Update"-Only Vorgang. Löschungen müssen manuell oder in einer späteren Phase synchronisiert werden.