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>
This commit is contained in:
2026-03-30 11:21:54 +02:00
parent a6f50fd2ae
commit 5c510208d2
2 changed files with 116 additions and 0 deletions
@@ -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)