Stefan Mogeritsch 5c510208d2 feat(docs): add comprehensive README for masterdata service

- Introduced detailed documentation for `masterdata` service, outlining purpose, architecture, and ÖTO rule compliance.
- Highlighted its hexagonal architecture and Gradle multi-module project structure.
- Documented key APIs, domain models (`LandDefinition`, `Altersklasse`, `Platz`), and testing practices using Testcontainers.
- Emphasized the service’s role as a central source of truth for ÖTO-conformant reference data.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>

2026-03-30 11:21:54 +02:00

4.1 KiB

Raw Blame History

🧹 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. Ä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.

4.1 KiB Raw Blame History