From c576bbd6af78dafb42950c27d774886d423d879d Mon Sep 17 00:00:00 2001 From: Stefan Mogeritsch Date: Mon, 30 Mar 2026 12:13:24 +0200 Subject: [PATCH] feat(docs): add ZNS interface documentation and session log for OEPS compliance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Created detailed session log for ZNS interface documentation (`2026-03-30_Session_Log_ZNS_Documentation.md`), outlining analysis, technical specifications, and next steps. - Added comprehensive ZNS Schnittstelle documentation (`ZNS_SCHNITTSTELLE.md`) to the `masterdata` service. - Linked new documentation in `masterdata/README.md` to ensure alignment with ÖTO standards. Signed-off-by: Stefan Mogeritsch --- .../masterdata/docs/ZNS_SCHNITTSTELLE.md | 87 +++++++++++++++++++ ...026-03-30_Session_Log_ZNS_Documentation.md | 54 ++++++++++++ 2 files changed, 141 insertions(+) create mode 100644 backend/services/masterdata/docs/ZNS_SCHNITTSTELLE.md create mode 100644 docs/99_Journal/2026-03-30_Session_Log_ZNS_Documentation.md diff --git a/backend/services/masterdata/docs/ZNS_SCHNITTSTELLE.md b/backend/services/masterdata/docs/ZNS_SCHNITTSTELLE.md new file mode 100644 index 00000000..89740b6d --- /dev/null +++ b/backend/services/masterdata/docs/ZNS_SCHNITTSTELLE.md @@ -0,0 +1,87 @@ +# 📜 ZNS-Datentransfer & Schnittstellen-Spezifikation (OEPS) + +Diese Dokumentation beschreibt die Struktur der Datenaustausch-Dateien zwischen dem **OEPS (Österreichischer +Pferdesportverband)** und den **Meldestellen**, basierend auf dem Pflichtenheft v2.4 (2021). + +## 📂 Die ZNS.zip (Stammdaten) + +Die Datei `zns.zip` enthält die zentralen Referenzdaten für den Turnierbetrieb. Alle Dateien sind im **ASCII-Format ( +Codepage 850)** kodiert. + +### 1. Richter & Parcoursbauer (`RICHT01.dat`) + +Enthält alle offiziellen Funktionäre mit ihren Qualifikationen. + +| Feld | Position | Länge | Format / Werte | +|:--------------------|:---------|:------|:---------------------------------------| +| **Satz-ID** | 1 | 1 | `X` (Richter) oder `Y` (Parcoursbauer) | +| **Satznummer** | 2 | 6 | Eindeutige OEPS-ID (`000000`) | +| **Name** | 8 | 75 | Familienname, Vorname | +| **Qualifikationen** | 83 | 30 | Kommagetrennt (z.B. `D,S,CSN-B`) | + +### 2. Lizenzen & Reiter (`LIZENZ01.dat`) + +Zentrale Liste aller Reiter mit aktiven Lizenzen und Startkarten. + +| Feld | Position | Länge | Format / Werte | +|:-------------------|:---------|:--------|:--------------------------------------------------------| +| **Satznummer** | 1 | 6 | Eindeutige Reiter-ID | +| **Name/Vorname** | 7 / 57 | 50 / 25 | - | +| **Bundesland** | 82 | 2 | 01=W, 02=NÖ, 03=B, 04=ST, 05=K, 06=OÖ, 07=S, 08=T, 09=V | +| **Vereinsname** | 84 | 50 | Stammverein | +| **Nationalität** | 134 | 3 | ISO-Code (z.B. `AUT`) | +| **Reiterlizenz** | 137 | 4 | z.B. `R1`, `RD2`, `R3` | +| **Altersklasse** | 144 | 2 | `JG`=Jugend, `JR`=Junior, `25`=U25 | +| **Junger Reiter** | 146 | 1 | `Y` = Junger Reiter | +| **Sperrliste** | 200 | 1 | `S` = Gesperrt (Info prüfen) | +| **Lizenz-Details** | 201 | 10 | Bezahlte Lizenzen (z.B. `RD1,F1`) | + +### 3. Pferde (`PFERDE01.dat`) + +Referenzdaten für alle registrierten Pferde (max. 3 Jahre nach letzter Zahlung). + +| Feld | Position | Länge | Format / Werte | +|:-----------------|:---------|:------|:--------------------------| +| **Kopfnummer** | 1 | 4 | Registrierte Kopfnummer | +| **Pferdename** | 5 | 30 | - | +| **Lebensnummer** | 35 | 9 | OEPS-Lebensnummer | +| **Geschlecht** | 44 | 1 | `W`, `H`, `S` | +| **Geburtsjahr** | 45 | 4 | JJJJ | +| **Besitzer** | 87 | 75 | Verantwortliche Person | +| **Satznummer** | 202 | 10 | Eindeutige OEPS-Pferde-ID | + +### 4. Vereine (`VEREIN01.dat`) + +| Feld | Position | Länge | Format / Werte | +|:------------------|:---------|:------|:---------------------------| +| **Vereinsnummer** | 1 | 4 | Eindeutige OEPS-Vereins-ID | +| **Vereinsname** | 5 | 50 | - | + +--- + +## 📩 Nennungsdaten (`n2-.dat`) + +Diese Datei enthält alle für ein spezifisches Turnier eingegangenen Nennungen. Sie folgt im Wesentlichen dem Aufbau der +`LIZENZ01` und `PFERDE01`, ergänzt um: + +* **A-Satz:** Turnierstammdaten (Name, Ort, Datum, Kategorie). +* **B-Satz:** Liste der ausgeschriebenen Bewerbe inkl. 3-stelliger Bewerbnummer (Pos. 60). +* **K-Satz (Kartei):** Verknüpfung Pferd ↔ Reiter ↔ Genannte Bewerbe. + +--- + +## 🏆 Ergebnisdaten (`.erg`) + +Die Rückmeldung der Ergebnisse an den OEPS nach Abschluss des Turniers. + +* **B-Satz:** Bewerbs-Informationen (Starteranzahl, ausgezahltes Geldpreis-Summe). +* **C-Satz:** Eingesetzte Richter für diesen Bewerb (Satznummern). +* **D-Satz (Ergebniszeile):** + * **Platz:** 1-996, `997`=Ausschluss, `999`=Disqualifikation. + * **Punkte/Wertnote:** Pos. 121 (Format 999999, 4 Vorkomma, 2 Nachkomma). + * **Zeit/Prozent:** Pos. 127 (3 Vorkomma, 2 Nachkomma; bei Dressur 2 Vorkomma, 3 Nachkomma). + * **Status:** `A`=Ausschluss, `D`=Disqualifikation, `T`=Teilnahmeverzicht (nur Stechen). + +--- +> 📜 **Rulebook Expert Hinweis:** Diese Spezifikationen sind die Grundlage für den `zns-import` Service. Die Längen und +> Positionen sind strikt einzuhalten, da der OEPS-Parser keine Abweichungen toleriert. diff --git a/docs/99_Journal/2026-03-30_Session_Log_ZNS_Documentation.md b/docs/99_Journal/2026-03-30_Session_Log_ZNS_Documentation.md new file mode 100644 index 00000000..77dadf2b --- /dev/null +++ b/docs/99_Journal/2026-03-30_Session_Log_ZNS_Documentation.md @@ -0,0 +1,54 @@ +--- +type: Journal +status: COMPLETED +owner: Curator +last_update: 2026-03-30 +--- + +# Session Log: Dokumentation der ZNS-Schnittstelle (OEPS) + +📜 **[ÖTO/FEI Rulebook Expert]** | 30. März 2026 + +## Kontext + +Basierend auf dem OEPS-Pflichtenheft v2.4 und der bereitgestellten `ZNS.zip` wurden die technischen Spezifikationen für +den Datenaustausch zwischen Verband und Meldestelle dokumentiert. Diese Daten bilden die Grundlage für den `zns-import` +Service und die Validierung im `masterdata` Kontext. + +## Erledigte Aufgaben + +### 1. ✅ Analyse der ZNS-Struktur + +- Auswertung der `ZNS.zip` Inhalte (`LIZENZ01.dat`, `PFERDE01.dat`, `RICHT01.dat`, `VEREIN01.dat`). +- Abgleich mit dem Pflichtenheft 2021 V2.4 bezüglich Feldlängen, Positionen und Formaten (ASCII CP 850). + +### 2. ✅ Technische Dokumentation + +- Erstellung der Datei `backend/services/masterdata/docs/ZNS_SCHNITTSTELLE.md`. +- Detaillierte Auflistung der Datensätze für Richter, Lizenzen, Pferde und Vereine. +- Dokumentation der Nennungs- (`n2-*.dat`) und Ergebnisformate (`*.erg`). +- Definition kritischer Felder wie Satznummern, Bundesland-Codes und Ergebnis-Status (`A`, `D`, `T`). + +### 3. ✅ Konsolidierung + +- Verknüpfung der neuen technischen Doku in der `masterdata/README.md`. +- Sicherstellung der Konsistenz zwischen fachlichen ÖTO-Regeln und technischer ZNS-Umsetzung. + +## Technische Details + +- **Formate:** Fixe Satzlängen, ASCII Codepage 850. +- **Kritische Pfade:** Die 10-stellige Satznummer für Pferde (Einführung v2.3) ist zwingend für die Ergebnisrückmeldung. +- **Validierung:** Bundesland-Codes (01-09) und Altersklassen-Kürzel (`JG`, `JR`, `25`) müssen im Frontend und Backend + synchron sein. + +## Nächste Schritte + +- Anbindung des `zns-import` Services an die neu dokumentierten Strukturen. +- Implementierung der Parser-Logik für die `*.dat` Dateien unter Berücksichtigung der fixen Feldpositionen. + +--- + +## Referenzen + +- `backend/services/masterdata/docs/ZNS_SCHNITTSTELLE.md` +- `docs/03_Domain/02_Reference/Legacy_Specs/OETO-2026_Meldestelle_Pflichtenheft_V2.4_2021-07-28.md`