Stefan Mogeritsch
e8757c5c32
- 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>
79 lines
5.2 KiB
Markdown
79 lines
5.2 KiB
Markdown
# 🧹 Masterdata Service
|
|
|
|
Der **Masterdata Service** ist ein zentraler Bounded Context innerhalb der Meldestelle-Biest Architektur. Er dient als "
|
|
Single Source of Truth" für alle statischen und semi-statischen Stammdaten, die für den Turnierbetrieb und die
|
|
Verwaltung von Reitern, Pferden und Organisationen (Vereinen) notwendig sind.
|
|
|
|
## 🎯 Zweck & Aufgaben
|
|
|
|
Dieser Service stellt sicher, dass alle anderen Contexts (wie `registration-context` oder `actor-context`) auf
|
|
konsistente und standardisierte Referenzdaten zugreifen können.
|
|
|
|
**Hauptaufgaben:**
|
|
|
|
* **Geografische Daten:** Verwaltung von Ländern (ISO-Codes), Bundesländern und deren OEPS-spezifischen Kürzeln.
|
|
* **Sportliche Reglements:** Bereitstellung von Altersklassen (ÖTO-konform), Sparten und Lizenzstufen.
|
|
* **Infrastruktur:** Verwaltung von Austragungsplätzen (Dimensionen, Bodenbeschaffenheit) innerhalb von Turnierstätten.
|
|
* **Referenzdaten:** Zentrale Pflege von Enums und Konstanten (z.B. Turniertypen, Status-Codes).
|
|
|
|
## 🏗️ Architektur & Modulstruktur
|
|
|
|
Der Service folgt einer **Hexagonalen Architektur** und ist als Gradle Multi-Modul-Projekt innerhalb des Backends
|
|
organisiert. Dies ermöglicht eine saubere Trennung zwischen Fachlogik und technischer Infrastruktur.
|
|
|
|
| Modul | Beschreibung |
|
|
|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| `masterdata-domain` | **KMP-Modul.** Enthält die Domänenmodelle (`LandDefinition`, `Altersklasse`, etc.) und Repository-Interfaces. Keine Abhängigkeiten nach außen. |
|
|
| `masterdata-common` | Beinhaltet die fachliche Logik in Form von **Use-Cases** (Interaktoren). |
|
|
| `masterdata-api` | Stellt die REST-Schnittstellen mittels **Ktor** bereit. Enthält Controller, DTO-Mapping und das Idempotency-Plugin. |
|
|
| `masterdata-infrastructure` | Implementiert die Persistenzschicht mit **Exposed** (PostgreSQL) und bindet externe Dienste an. |
|
|
| `masterdata-service` | Der **Spring Boot Host**, der alle Module zusammenführt, die Konfiguration verwaltet und den Service startet. |
|
|
|
|
## 🛠️ Wichtige Domänenmodelle (Auszug)
|
|
|
|
* **`LandDefinition`:** ISO-3166 konforme Länderdaten inklusive EU/EWR-Status und Wappen-URLs.
|
|
* **`Bundesland`:** Zuordnung zu Ländern, inklusive der für die OEPS-Satznummern relevanten Landes-Codes.
|
|
* **`Altersklasse`:** Definitionen basierend auf dem Geburtsjahr, Geschlecht und der Sparte (ÖTO § 39).
|
|
* **`Platz`:** Beschreibung von Austragungs- und Vorbereitungsplätzen für Turniere.
|
|
|
|
## 🔌 Schnittstellen (API)
|
|
|
|
Die APIs sind unter `/api/v1/masterdata/...` erreichbar.
|
|
|
|
**Wichtige Endpunkte:**
|
|
|
|
* `GET /countries`: Liste aller unterstützten Länder.
|
|
* `GET /bundeslaender`: Regionale Gliederung (vorrangig Österreich).
|
|
* `GET /altersklassen`: Abfrage der gültigen Klassen für einen Reiter in einer bestimmten Sparte.
|
|
* `GET /plaetze`: Infrastruktur-Abfrage für Turnierplanung.
|
|
|
|
## 🧪 Entwicklung & Tests
|
|
|
|
* **Unit-Tests:** Befinden sich in den jeweiligen Modulen (v.a. `domain` und `common`).
|
|
* **Integration-Tests:** Nutzen Testcontainers für die Datenbankvalidierung (in `infrastructure` und `service`).
|
|
* **Idempotenz:** Der Service nutzt ein spezialisiertes `IdempotencyPlugin` in der API-Schicht, um doppelte
|
|
Schreiboperationen bei Netzwerkfehlern zu verhindern.
|
|
|
|
## 📜 ÖTO-Konformität
|
|
|
|
Sämtliche Stammdaten (insbesondere Altersklassen und Sparten) sind strikt nach dem **ÖTO (Österreichische
|
|
Turnierordnung)** Regelwerk modelliert. Detaillierte Aufstellungen der verwendeten Definitionen finden sich hier:
|
|
|
|
* [Strategische Roadmap](docs/ROADMAP.md) (Phasen, Meilensteine, Verantwortlichkeiten)
|
|
* [ÖTO-Stammdaten Dokumentation](docs/OETO_STAMMDATEN.md) (Fachliche Logik)
|
|
* [Turnier-Sparten & Klassen](docs/TURNIER_KLASSEN.md) (Detaillierte Übersicht Springen/Dressur & C-NEU)
|
|
* [Reiter-Lizenzen & Startberechtigungen](docs/REITER_LIZENZEN.md) (Lizenzstufen & Sportliche Relevanz)
|
|
* [Richter & Parcoursbauer Qualifikationen](docs/FUNKTIONAERE_QUALIFIKATIONEN.md) (Befugnisse & Einsatzvorgaben)
|
|
* [Gebührenordnung ÖTO 2026](docs/GEBUEHRENORDNUNG.md) (Nenn-/Startgelder & Geldpreise)
|
|
* [Pferdeprüfungen (Jungpferde)](docs/PFERDEPRUEFUNGEN.md) (Dressur-/Springpferdeprotokolle)
|
|
* [Pferdeprüfungen (Bewertungssystem)](docs/PFERDEPRUEFUNGEN_BEWERTUNG.md) (Abzugslogik & qualitative Noten)
|
|
* [Reiter-Prüfungen (Dressur & Stilspringen)](docs/REITER_PRUEFUNGEN.md) (Fokus auf Sitz & Einwirkung)
|
|
* [ZNS-Schnittstellen Spezifikation](docs/ZNS_SCHNITTSTELLE.md) (Technisches Transfer-Format)
|
|
|
|
Änderungen am Regelwerk müssen hier zentral eingepflegt werden, damit sie
|
|
systemweit (z.B. in der Nennungsprüfung) wirksam werden.
|
|
|
|
---
|
|
> 🧹 **Curator-Hinweis:** Diese Dokumentation wird laufend aktualisiert. Änderungen an der Domänenstruktur müssen in der
|
|
`MASTER_ROADMAP` reflektiert werden.
|