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>
56 lines
2.6 KiB
Markdown
56 lines
2.6 KiB
Markdown
---
|
|
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)
|