Stefan Mogeritsch e8757c5c32 feat(docs): expand masterdata documentation with Reiter- and Pferdeprüfungen

- 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>

2026-03-30 14:29:58 +02:00

2.6 KiB

Raw Blame History

type	status	owner	date
ADR	AKZEPTIERT	Lead Architect	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:

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

2.6 KiB Raw Blame History