feat(docs): expand masterdata documentation with Reiter- and Pferdeprüfungen

- Added `REITER_PRUEFUNGEN.md` and `PFERDEPRUEFUNGEN_BEWERTUNG.md` to document evaluation criteria, scoring logic, and system requirements for dressage and show jumping. - Updated `README.md` with links to new documentation on rider- and horse-specific regulations. - Created database schemas for `TurnierklasseTable`, `RichtverfahrenTable`, `GebuehrTable`, `LicenseTable`, and `RegulationConfigTable`, aligning with ÖTO 2026. - Logged architectural decisions and analysis in `session-logs` and created ADRs `0017-masterdata-importer-worker` and `0019-api-ingestion-layers`. Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
2026-03-30 14:29:55 +02:00
parent 6375ec23c3
commit e8757c5c32
29 changed files with 1663 additions and 18 deletions
@@ -203,6 +203,9 @@ und über definierte Schnittstellen kommunizieren.
 | 8  | 6 Bounded Contexts: Mapping & Aggregate Roots                | ✅      | ADR-0014                     |
 | 9  | Context Map: Integration Patterns & ACL-Strategie            | ✅      | ADR-0015                     |
 | 10 | API-Design & ACL: Ports, DTOs, REST-Endpunkte, Domain Events | ✅      | ADR-0016                     |
+| 11 | Masterdata: Importer-Einbettung als Worker                   | ✅      | ADR-0017                     |
+| 12 | Masterdata: Rule-Versionierung (Regulation-as-Data)          | ✅      | ADR-0018                     |
+| 13 | Masterdata: API-Schichten (REST vs. Ingestion)               | ✅      | ADR-0019                     |

 ---

@@ -0,0 +1,58 @@
+---
+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)
@@ -0,0 +1,53 @@
+---
+type: ADR
+status: AKZEPTIERT
+owner: Lead Architect
+date: 2026-03-30
+---
+
+# ADR-0018: Rule-Versionierung und -Management (ÖTO-Regeln)
+
+## Status
+
+Akzeptiert
+
+## Kontext
+
+Die ÖTO-Regeln (Österreichische Turnierordnung) für Dressur, Springen und andere Sparten ändern sich regelmäßig (
+jährlich oder bei Bedarf). Das System muss in der Lage sein, Stammdaten (Altersklassen, Lizenzen, Richtverfahren,
+Gebühren) für ein Turnier basierend auf dem zum Turnierzeitpunkt gültigen Regelwerk zu validieren und anzuzeigen. Eine
+rein Code-basierte Regelverwaltung (Hardcoding) ist aufgrund der Dynamik und Offline-Fähigkeit nicht praktikabel.
+
+## Entscheidung
+
+ÖTO-Regeln werden als **versionierte Datensätze in der Datenbank** verwaltet (Regulation-as-Data).
+
+Details:
+
+1. **Versionierungs-Schema**: Alle Regel-Datensätze (z.B. Lizenz-Klasse-Matrix, Altersklassen-Berechnung) erhalten
+   `valid_from` und `valid_to` Zeitstempel.
+2. **Aktives Regel-Set**: Die Applikationslogik ermittelt zur Laufzeit (z.B. basierend auf dem Turnierdatum) das jeweils
+   aktive Regel-Set aus der Datenbank.
+3. **Seed-Strategie**: Zu Beginn jeder Saison (oder bei Major-Updates) wird ein neues Regel-Set als Seed in die
+   Datenbank eingespielt. Das "Regel-Set 2026" dient als Basis.
+4. **Unveränderlichkeit (Immutability)**: Bestehende, in Turnieren verwendete Regeln dürfen nicht überschrieben werden.
+   Bei Änderungen wird ein neuer Datensatz mit neuem Gültigkeitsbereich angelegt (SCD Type 2 Pattern).
+
+## Konsequenzen
+
+- **Positiv**: Hohe Flexibilität ohne Code-Deployments (Config-over-Code).
+- **Positiv**: Historische Turniere bleiben nachvollziehbar, da sie auf das damals gültige Regelwerk verweisen.
+- **Negativ**: Erhöhte Komplexität bei Datenbank-Abfragen (immer Zeitbezug erforderlich).
+- **Negativ**: Notwendigkeit für robuste Administrations-Schnittstellen oder SQL-Seeds zur Regelpflege.
+
+## Betrachtete Alternativen
+
+- **Hardcoding in Kotlin-Use-Cases**: Schneller zu implementieren, aber unflexibel bei unterjährigen Regeländerungen und
+  historischer Auswertung schwierig.
+- **Git-basierte Konfiguration (YAML/JSON)**: Gut für CI/CD, aber schwierig für Offline-Szenarien ohne vollen
+  Repository-Sync; Datenbank-Integration für Abfragen komplexer.
+
+## Referenzen
+
+- [ROADMAP.md](../ROADMAP.md)
+- [Abteilungs-Trennungs-Schwellenwerte.md](../../../docs/03_Domain/02_Reference/OETO_Regelwerk/Abteilungs-Trennungs-Schwellenwerte.md)
@@ -0,0 +1,55 @@
+---
+type: ADR
+status: AKZEPTIERT
+owner: Lead Architect
+date: 2026-03-30
+---
+
+# ADR-0019: API-Schichten und Ingestion-Pattern im Masterdata-SCS
+
+## Status
+
+Akzeptiert
+
+## Kontext
+
+Das Masterdata-SCS (Stammdaten) dient als zentrale Informationsquelle für alle anderen Bounded Contexts (z.B.
+Registration, Competition). Es muss sowohl Massendaten aus dem ZNS (Zentrales Nennungs-System) aufnehmen (Schreibkanal)
+als auch hochperformante Lesezugriffe (Lesekanal) für die Suche und Validierung ermöglichen. Dabei ist die Trennung
+zwischen internen Ingestion-Prozessen und externen Client-APIs entscheidend für die Stabilität und Sicherheit.
+
+## Entscheidung
+
+Die API-Architektur wird in **klare Schichten für Ingestion (Schreiben) und REST (Lesen)** unterteilt.
+
+Details:
+
+1. **Lesekanal (Public REST API)**: Bietet Endpunkte für die Suche (Reiter, Pferde, Vereine) und den Abruf von
+   Regelwerken. Diese API ist optimiert für Performance (Indizes, Paging, ETags) und nutzt DTOs mit Kotlinx
+   Serialization.
+2. **Schreibkanal (Ingestion API/Worker)**: Dieser Kanal ist internen Prozessen (ZNS-Importer) vorbehalten. Direkte
+   Schreibzugriffe von Clients auf Stammdaten sind in der ersten Phase unterbunden. Der Schreibkanal nutzt ein
+   Ingestion-Pattern, das auf Idempotenz (Upserts) und Validierung (Checksum-Checks) basiert.
+3. **Internal API (Core Interfaces)**: Innerhalb des Masterdata-SCS werden klare Interfaces für Repositories und
+   UseCases genutzt, die von Ingestion und REST gemeinsam verwendet werden.
+4. **Versioning**: Alle APIs werden versioniert (v1, v2), um zukünftige Schema-Änderungen ohne Breaking Changes zu
+   ermöglichen.
+
+## Konsequenzen
+
+- **Positiv**: Klare Trennung der Verantwortlichkeiten (Separation of Concerns).
+- **Positiv**: Höhere Sicherheit, da Stammdaten nicht versehentlich durch die Public-API manipuliert werden können.
+- **Positiv**: Bessere Skalierbarkeit: Lesekanal kann unabhängig vom Schreibkanal optimiert werden.
+- **Negativ**: Erhöhter Implementierungsaufwand durch getrennte DTOs und Validierungslogik für die Ingestion-Phase.
+
+## Betrachtete Alternativen
+
+- **Einheitliche CRUD-API**: Alle Zugriffe über die gleiche API-Schicht. Verworfen wegen mangelnder Sicherheit bei
+  sensiblen Stammdaten und Performance-Problemen bei Massen-Imports.
+- **GraphQL**: Bietet hohe Flexibilität beim Lesen, wurde jedoch für die erste Phase als zu komplex für die einfache
+  Suche in Stammdaten angesehen. REST ist für Offline-Szenarien und Caching (ETags) einfacher zu handhaben.
+
+## Referenzen
+
+- [ADR-0017: Importer-Einbettung](./0017-masterdata-importer-worker-de.md)
+- [ROADMAP.md](../ROADMAP.md)
@@ -0,0 +1,47 @@
+# Session Log: Einarbeitung C-NEU Bestimmungen & Turnier-Sparten
+
+**Datum:** 2026-03-30  
+**Agent:** 📜 [ÖTO/FEI Rulebook Expert] / 🧹 [Curator]
+
+## Zielsetzung
+
+Integration der spezifischen Bestimmungen für C-NEU Turniere (CDN-C NEU / CSN-C NEU) in die Stammdaten-Dokumentation des
+`masterdata` Services. Aufbereitung einer detaillierten Übersicht über Turnier-Sparten (Dressur & Springen), deren
+Klassen und die korrespondierenden Startberechtigungen (Lizenz-Matrix).
+
+## Durchgeführte Änderungen
+
+### 1. Erweiterung der zentralen Stammdaten (`OETO_STAMMDATEN.md`)
+
+* **Abteilungslogik:** Spezifikation der 3-Abteilungs-Regel für CSN-C NEU bis 95 cm (Abt. 1: ohne Lizenz, Abt. 2: R1,
+  Abt. 3: R2+).
+* **Dressur-Klassen:** Ergänzung der Klasse `LF` (Lizenzfrei) für Reiterpass-/Reiternadel-Aufgaben im C-NEU Bereich.
+* **C-NEU Spezifika:** Dokumentation der Einschränkung, dass Lizenzinhaber in RP/Nadel-Bewerben nicht startberechtigt
+  sind.
+
+### 2. Neue Fachdokumentation (`TURNIER_KLASSEN.md`)
+
+* Erstellung einer detaillierten Übersicht für **Springen (CSN)**:
+  * Höhenstufen (E0 bis S****).
+  * C-NEU Besonderheiten (Registrierungspflicht erst ab 95 cm, Startlimits).
+  * Strukturelle Abteilungs-Vorgaben.
+* Erstellung einer detaillierten Übersicht für **Dressur (CDN)**:
+  * Aufgabenniveau (LF bis S).
+  * Startberechtigungen pro Klasse.
+* **Startberechtigungs-Matrix:** Zentrale Gegenüberstellung von Lizenzstufen (LZF, R1-R4, RD1-RD3) und den maximal
+  zulässigen Klassen in beiden Sparten.
+
+### 3. Service-Integration (`README.md`)
+
+* Verlinkung der neuen `TURNIER_KLASSEN.md` in der zentralen Dokumentations-Übersicht des `masterdata` Services.
+
+## Verifizierung
+
+* Abgleich der Daten mit `Bestimmungen_CSN-C_NEU.md` und `Bestimmungen_CDN-C_NEU.md`.
+* Validierung der Lizenzstufen gegen `REITER_LIZENZEN.md` und die ÖTO 2026.
+* Prüfung der Konsistenz mit den Abteilungs-Schwellenwerten aus der Master-Referenz.
+
+## Nächste Schritte
+
+* Implementierung der `Validation-Engine` Logik basierend auf der erstellten Startberechtigungs-Matrix.
+* Erweiterung des `zns-import` Moduls zur Berücksichtigung der C-NEU Registrierungs-Ausnahmen für Pferde.
@@ -0,0 +1,36 @@
+# Session Log: Masterdata Funktionär-Qualifikationen
+
+**Datum:** 2026-03-30
+**Agent:** 📜 [ÖTO/FEI Rulebook Expert]
+
+## 🎯 Ziel
+
+Aufbereitung der Qualifikationen für Richter und Parcoursbauer basierend auf der ÖTO 2026 und dem ZNS-Pflichtenheft v2.4
+zur Integration in den `masterdata` Service.
+
+## 🛠️ Änderungen
+
+### 1. Neue Dokumentation: `FUNKTIONAERE_QUALIFIKATIONEN.md`
+
+* **Fachlich:** Zusammenfassung der Richtergruppen (Dressur, Springen, Vielseitigkeit) und Zusatzqualifikationen (SPF,
+  DPF).
+* **Level:** Dokumentation der Parcoursbauer-Level (P1-P4) inklusive der spezifischen Anforderung für C-NEU (mind. P1).
+* **Regelwerk:** Integration der Einsatzvorgaben (§ 50 A-Teil) wie Mindestbesetzung und Zeitlimits.
+* **Technisch:** Detaillierung der ZNS-Satzarten (X-Satz für Richter, Y-Satz für Parcoursbauer) mit Felddefinitionen (
+  Stelle/Länge).
+
+### 2. README-Update
+
+* Verlinkung der neuen Dokumentation in der zentralen `README.md` des `masterdata` Services.
+
+## 🔍 Validierung
+
+* Abgleich der Felddefinitionen mit dem Original-Pflichtenheft v2.4.
+* Prüfung der fachlichen Anforderungen gegen die ÖTO 2026 (A- und B-Teil).
+* Verifizierung der Pfade und Verlinkungen innerhalb des Service-Kontexts.
+
+## 📌 Nächste Schritte
+
+* Implementierung der `Funktionaer`-Entity in `masterdata-domain` (erledigt).
+* Ausbau des `ExposedFunktionaerRepository` zur Unterstützung des ZNS-Imports der X- und Y-Sätze.
+* Integration der Qualifikations-Validierung in die Turnier-Ausschreibung (Validation Engine).
@@ -0,0 +1,41 @@
+# Session Log: Masterdata Gebührenordnung (ÖTO 2026)
+
+**Datum:** 2026-03-30
+**Agent:** 🧹 [Curator] & 📜 [ÖTO/FEI Rulebook Expert]
+
+## 🎯 Ziel
+
+Aufbereitung der offiziellen ÖTO-Gebührenordnung 2026 für die Sparten Dressur und Springen zur späteren Implementierung
+in die Berechnungs- und Validierungs-Logik des Masterdata-Services.
+
+## 📝 Durchgeführte Änderungen
+
+### 1. Fachdokumentation erstellt
+
+* **Datei:** `backend/services/masterdata/docs/GEBUEHRENORDNUNG.md`
+* **Inhalt:**
+  * **Nenn- und Startgelder:** Strukturierte Übersicht über Nenngelder nach Kategorie (A/B/C) und
+    Startgeld-Obergrenzen (mit/ohne Geldpreis, C-NEU, getrenntes Richten).
+  * **Zusatzabgaben:** Dokumentation von Tierwohleuro (1,00 €) und Sportförderbeitrag (1,00 €).
+  * **Geldpreise:** Tabellarische Aufbereitung der Mindest-Geldpreise für Dressur (Klassen A bis S) und Springen (
+    Höhenstufen 105 cm bis 160 cm) für alle Turnierkategorien.
+  * **Funktionärsvergütung:** Festhalten der Tagessätze (120 € / 100 €), Kilometergelder (0,50 €) und
+    Unterkunftsvorgaben.
+
+### 2. Integration & Verlinkung
+
+* Aktualisierung der `backend/services/masterdata/README.md`, um die neue Gebührenordnung als Referenz für die
+  ÖTO-Konformität aufzunehmen.
+
+## 🔍 Validierung
+
+* Abgleich der Daten mit dem Originaldokument
+  `docs/03_Domain/02_Reference/OETO_Regelwerk/OETO-2026_E-Teil-Gebuehrenordnung_18-12-2025.md`.
+* Sicherstellung, dass spartenrelevante Ausnahmen (z.B. Tierwohleuro nur bei Springen) korrekt markiert sind.
+
+## 💡 Nächste Schritte
+
+* Überführung der Gebührensätze in Domänen-Konstanten (`masterdata-domain`).
+* Implementierung einer `AccountingEngine` oder eines `FeeCalculator` Services im `competition-context`, der auf diese
+  Stammdaten zugreift.
+* Erweiterung der Ausschreibungs-Validierung um die Prüfung der Mindest-Geldpreis-Summen.
@@ -0,0 +1,29 @@
+### Summary
+
+- Aufbereitung und Dokumentation der spezifischen Anforderungen für Pferdeprüfungen (Jungpferde) in Dressur und Springen
+  gemäß ÖTO 2026.
+- Integration der komplexeren Bewertungslogik (Qualitative Noten, Abzüge bei Springpferdeprüfungen) in den `masterdata`
+  Service-Kontext.
+
+### Changes
+
+- **Neue Fachdokumentation:** `backend/services/masterdata/docs/PFERDEPRUEFUNGEN.md` erstellt, die Altersklassen,
+  Richtverfahren und Bewertungskriterien für Dressur-, Spring- und Reitpferdeprüfungen beschreibt.
+- **Bewertungs-Logik:** Detaillierung der qualitativen Merkmale (Grundgangarten, Rittigkeit, Perspektive) und der
+  spezifischen Abzugs-Regeln für Springpferdeprüfungen.
+- **README-Update:** Die zentrale `README.md` des `masterdata` Services wurde um die Verlinkung der neuen
+  Pferdeprüfungs-Dokumentation ergänzt.
+- **Journaling:** Erstellung eines detaillierten Session Logs zur Dokumentation der Aufbereitung für
+  Jungpferdeprüfungen.
+
+### Verification
+
+- Abgleich der Altersklassen und Richtverfahren mit den ÖTO-Regelwerken 2026 (Abschnitt B I und B II).
+- Validierung der Abzugs-Logik (§ 204 Abs. 4) für Springpferdeprüfungen.
+- Prüfung der internen Verlinkung innerhalb der Service-Struktur.
+
+### Notes
+
+- Die Dokumentation dient als Grundlage für die Implementierung der Notenerfassung im UI (Einzelnoten-Eingabe vs.
+  Gesamtnote).
+- Die Pferdealter-Validierung muss beim Nennungsprozess strikt auf dem Geburtsjahr (Stichtag 1.1.) basieren.
@@ -0,0 +1,24 @@
+### Summary
+
+- Aufbereitung und Dokumentation des spezifischen Bewertungssystems für Pferdeprüfungen (Dressur-/Springpferde) und
+  Stilspringprüfungen gemäß ÖTO 2026.
+- Integration der qualitativen Bewertungskriterien und der automatisierten Abzugslogik in den `masterdata`
+  Service-Kontext.
+
+### Changes
+
+- **Neue Fachdokumentation:** `backend/services/masterdata/docs/PFERDEPRUEFUNGEN_BEWERTUNG.md` erstellt, die
+  Einzelnoten-Kriterien für Dressurpferdeprüfungen (Schritt, Trab, Galopp etc.) und die Abzugslogik für
+  Springpferde/Stilspringen (-0,5/-1,0) detailliert beschreibt.
+- **Spezialregelung:** Dokumentation der „ohne Bewertung“ (o.B.) Logik für Endnoten <= 4,9 inklusive deren spezifischer
+  Reihung in Ergebnislisten.
+- **System-Anforderungen:** Definition der UI- und Berechnungs-Anforderungen für die Meldestellen-Software (
+  Echtzeit-Kalkulation der Endnoten).
+- **README-Update:** Die zentrale `README.md` des `masterdata` Services wurde um die Verlinkung der neuen
+  Bewertungs-Dokumentation erweitert.
+
+### Verification
+
+- Abgleich der Kriterien und Abzugswerte mit den ÖTO-Regelwerken 2026 (Abschnitt B, § 103, § 104, § 203, § 204).
+- Validierung der Konsistenz zwischen fachlichen Anforderungen und den zuvor erstellten allgemeinen
+  Pferdeprüfungs-Stammdaten.
@@ -0,0 +1,27 @@
+# Session Log: Masterdata Reiter-Prüfungen (Dressur & Stilspringen)
+
+## 📋 Zusammenfassung
+
+- Aufbereitung der Stammdaten für Dressurreiter- und Stilspringprüfungen gemäß ÖTO 2026.
+- Fokus auf die spezifische Bewertungslogik (Wertnoten vs. Abzüge) und deren Anforderungen an das System.
+
+## 🛠 Änderungen
+
+- **Neue Fachdokumentation:** `backend/services/masterdata/docs/REITER_PRUEFUNGEN.md` erstellt.
+- **Inhalt:**
+  - Definition Dressurreiterprüfung (Sitz, Einwirkung, Hufschlaglinien).
+  - Detaillierte Abzugslogik für Stilspringprüfungen (Hindernisfehler, Ungehorsam, Sturz).
+  - System-Anforderungen für die UI (Erfassungsmasken) und Validierung (Lizenzprüfung).
+- **README-Update:** Verlinkung der neuen Dokumentation in der zentralen `README.md` des Masterdata-Services.
+
+## ✅ Verifizierung
+
+- Abgleich der Abzugswerte (z.B. -0,5 für Abwurf im Stilspringen) mit der ÖTO 2026.
+- Prüfung der Reihungsregeln bei Punktgleichheit (Stilnote vor Abzügen).
+- Validierung der Konsistenz mit dem bestehenden ZNS-Schnittstellen-Mapping.
+
+## 📝 Notizen
+
+- Diese Daten sind besonders für die Umsetzung von Nachwuchsbewerben und C-NEU Turnieren (lizenzfrei) von hoher
+  Bedeutung.
+- Der `Score-Service` muss im Backend die Logik zur automatischen Berechnung der Endnoten im Stilspringen bereitstellen.