diff --git a/backend/services/masterdata/README.md b/backend/services/masterdata/README.md new file mode 100644 index 00000000..7b3d34fb --- /dev/null +++ b/backend/services/masterdata/README.md @@ -0,0 +1,65 @@ +# 🧹 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. diff --git a/docs/99_Journal/2026-03-30_Session_Log_Masterdata_README.md b/docs/99_Journal/2026-03-30_Session_Log_Masterdata_README.md new file mode 100644 index 00000000..3fe0e23e --- /dev/null +++ b/docs/99_Journal/2026-03-30_Session_Log_Masterdata_README.md @@ -0,0 +1,51 @@ +--- +type: Journal +status: COMPLETED +owner: Curator +last_update: 2026-03-30 +--- + +# Session Log: Stammdaten-Service Dokumentation (README) + +🧹 **[Curator]** | 30. März 2026 + +## Kontext + +Der `masterdata` Service im Backend ist ein kritischer Bounded Context für die Bereitstellung von ÖTO-konformen +Stammdaten. Bisher fehlte eine zentrale README-Datei, die den Zweck, die hexagonale Modulstruktur und die fachliche +Bedeutung (ÖTO) für Entwickler schnell erfassbar macht. + +## Erledigte Aufgaben + +### 1. ✅ Analyse der Service-Struktur + +- Untersuchung der 5 Teilmodule: `masterdata-api`, `masterdata-common`, `masterdata-domain`, `masterdata-infrastructure` + und `masterdata-service`. +- Identifikation der wichtigsten Domänenmodelle (`LandDefinition`, `Altersklasse`, `Platz`). +- Prüfung der API-Endpunkte und der Persistenz-Implementierung (Exposed). + +### 2. ✅ Erstellung der README.md + +- Dokumentation des Services in deutscher Sprache in `backend/services/masterdata/README.md`. +- Detaillierte Beschreibung der Modulverantwortlichkeiten. +- Hervorhebung der **ÖTO-Konformität** als fachliche Basis. +- Dokumentation technischer Besonderheiten wie des `IdempotencyPlugin`. + +## Technische Details & Architektur + +- **Architektur:** Hexagonale Architektur (Ports & Adapters). +- **Technologien:** Kotlin (KMP für Domain), Ktor (API), Exposed (SQL), Spring Boot (Host). +- **Fachlicher Fokus:** ÖTO § 39 (Altersklassen) und Geografische Referenzdaten (OEPS-Kürzel). + +## Nächste Schritte + +- Synchronisation der Dokumentation mit dem `actor-context`, da dieser stark von den Stammdaten abhängt. +- Regelmäßige Aktualisierung der `MASTER_ROADMAP` bei Erweiterung der Stammdaten-Typen. + +--- + +## Referenzen + +- `MASTER_ROADMAP.md` (Phase 4: MVP-Implementierung) +- ÖTO (Österreichische Turnierordnung) +- ADR-0016 (API-Design & ACL)