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>
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
# Strategische Roadmap: Masterdata (Stammdaten) 2026 H1–H2
|
||||
|
||||
🏗️ [Lead Architect]
|
||||
|
||||
## Leitbild und Scope
|
||||
|
||||
- Ziel: ÖTO-konforme, offline-fähige Stammdaten-Plattform für Dressur & Springen als Self‑Contained System mit eigener
|
||||
DB, klaren APIs und einem wiederverwendbaren Frontend-Feature (Compose MPP).
|
||||
- Ergebnis: Lesekanal (REST-API), Schreibkanal (ZNS-Ingestion), datengesteuerte Regel-Engine (Versionierung von
|
||||
ÖTO-Regeln), vollständige Observability und Betrieb.
|
||||
- Nicht-Ziele (Phase 1): FEI-Integration, weitere Sparten (VS, Western), komplexe Serien-/Cup-Reglements.
|
||||
|
||||
---
|
||||
|
||||
## Phasenüberblick und Meilensteine
|
||||
|
||||
### 1) Foundation & Governance (WK 1–2)
|
||||
|
||||
- Architektur-Entscheide (ADRs) finalisieren: Database-per-Service, Rule-Engine als Datenmodell, Importer als Worker im
|
||||
Masterdata-SCS.
|
||||
- Versionierungs-Strategie: `valid_from/valid_to` auf Regel-Datensätzen; „Regel-Set 2026“ als Seed.
|
||||
- Security/Cross-Cutting: API-Schlüssel/Service-Tokens, CORS, Ratelimits, Idempotency-Policies dokumentieren und
|
||||
aktivieren.
|
||||
- Deliverables:
|
||||
- [x] ADR-Set im Repo (Rules, DB, Import, API) → ADR-0017, ADR-0018, ADR-0019
|
||||
- Operative Runbooks (Backup/Restore, Re-Import, Rollback)
|
||||
|
||||
### 2) Datenmodell & Persistenz (WK 2–4)
|
||||
|
||||
- Tabellenkatalog vervollständigen und migrieren (Exposed + Flyway/Liquibase): Reiter, Pferde, Vereine, Funktionäre,
|
||||
Altersklassen, Lizenzen, Turnierklassen, Gebührenordnung, Richtverfahren, Regelkonfiguration.
|
||||
- Indizes/Keys: Eindeutige Schlüssel gemäß ZNS (Satz-/Lizenznummern), Suchindizes für Name/Teilstrings.
|
||||
- Deliverables:
|
||||
- Migrationsskripte v1.0
|
||||
- Repository-Impls mit Upsert-Semantik
|
||||
- Test-Datasets (Mini-ZNS, ÖTO-Seeds)
|
||||
|
||||
### 3) Rule-Engine (WK 4–6)
|
||||
|
||||
- Domänenlogik kapseln: Altersklassenrechner, Lizenz-zu-Klasse-Matrix, Abteilungsregeln,
|
||||
Pferde-/Reiterprüfungs-Scoring (Stilspringen/Dressurpferde), Gebühren-Lookups.
|
||||
- Datengesteuerte Konfiguration: Tabellen „RegulationConfig“, „LicenseMatrix“, „ClassDefinitions“ mit Versionen.
|
||||
- Deliverables:
|
||||
- UseCases im `masterdata-common` (pure Kotlin) + Unit-Tests
|
||||
- Admin-Seed für „ÖTO 2026“
|
||||
|
||||
### 4) ZNS-Ingestion als Worker (WK 5–7)
|
||||
|
||||
- Import-Pipeline (ASCII CP850) als Masterdata-Submodul/Worker: Validierung, Deduplikation (Idempotenz),
|
||||
Fehlerreporting.
|
||||
- Re-Import & Delta-Regeln; Konfliktstrategien (last-write-wins vs. checksum‑based skip).
|
||||
- Deliverables:
|
||||
- Batch-Job + CLI/HTTP Trigger
|
||||
- Import-Report (persistiert + JSON-Export)
|
||||
|
||||
### 5) API-Fassade (WK 6–8)
|
||||
|
||||
- Read-APIs (v1):
|
||||
- GET /reiter?search=…
|
||||
- GET /horses?search=…
|
||||
- GET /vereine?bundesland=…
|
||||
- GET /altersklassen, /turnierklassen, /lizenzmatrix, /richtverfahren, /gebuehrenordnung
|
||||
- Admin/Tech-APIs: GET /rulesets, GET /health, GET /metrics
|
||||
- DTOs mit Kotlinx Serialization; Paginierung & ETags.
|
||||
- Deliverables: OpenAPI 3 Spec, Contract-Tests
|
||||
|
||||
### 6) Frontend-Feature „masterdata“ (WK 7–9)
|
||||
|
||||
- KMP-Feature-Modul: Such-/Detail-Views für Reiter, Pferde, Vereine; Read‑only Rule-Explorer.
|
||||
- State-Management, Offline‑Cache (Local DB) für Desktop; Fehler-/Konfliktanzeigen beim Import.
|
||||
- Deliverables: Integrations-Demo in Desktop-Shell, UI-Snippets für Web-Shell
|
||||
|
||||
### 7) Observability & Operations (WK 5–9, parallel)
|
||||
|
||||
- Logging-Konzepte (strukturierte Logs), Metriken (Importdauer, Records/s, API Latenzen), Tracing (optional).
|
||||
- Dashboards/Alerts: Import-Fehlerquote, API 5xx, DB‑Wachstum, Regel-Set-Mismatch.
|
||||
- Backups/Restore-Runbooks, DR-Test.
|
||||
|
||||
### 8) Quality Gate & Go‑Live (WK 9–10)
|
||||
|
||||
- Test-Strategie:
|
||||
- Unit: Rule-Engine, UseCases
|
||||
- Integration: Repos + API + Importer (Mini-ZNS)
|
||||
- End‑to‑End: Desktop-Feature → API → DB
|
||||
- Security Review, Performance Smoke (100k Reiter, 50k Pferde, 2k Vereine), Data Quality Checks.
|
||||
- Go‑Live Checklist und Staged Rollout.
|
||||
|
||||
---
|
||||
|
||||
## Verantwortlichkeiten (Agents)
|
||||
|
||||
- 🏗️ Lead Architect: ADRs, Architektur-Governance, Phasenabnahme
|
||||
- 👷 Backend Developer: DB/Repositories, UseCases, API, Importer
|
||||
- 🎨 Frontend Expert: KMP-Feature, Offline-Cache, API-Integration
|
||||
- 🐧 DevOps Engineer: CI/CD, Deploy, Observability, Backups
|
||||
- 🧐 QA Specialist: Test-Strategie, Abdeckung, E2E
|
||||
- 📜 Rulebook Expert: Daten-Seeds, Regel-Validierung, Review der Matrix
|
||||
- 🧹 Curator: Docs-as-Code, Changelogs, Runbooks, Session Logs
|
||||
|
||||
---
|
||||
|
||||
## Architekturprinzipien (Wartbarkeit)
|
||||
|
||||
- Hexagonale Architektur strikt einhalten; UseCases sind framework-frei und testbar.
|
||||
- Regeln im Datenmodell versionieren; Code nutzt nur „aktives Regel-Set“ je Turnier/Datum.
|
||||
- Importer ist ein Worker des Masterdata-SCS (Schreibkanal), API ist der Lesekanal.
|
||||
- Idempotenz konsequent: Upserts, ETags, Import-Footprint (checksum, source_id, imported_at).
|
||||
|
||||
---
|
||||
|
||||
## Abhängigkeiten & Risiken
|
||||
|
||||
- Abhängigkeiten: Postgres-Verfügbarkeit, ZNS-Dateiqualität, Identity (Token) für gesicherte Admin-Routen, Desktop-App
|
||||
Shell.
|
||||
- Risiken & Gegenmaßnahmen:
|
||||
- Regeländerungen kurz vor Saisonstart → Versionierte Rulesets + Blue/Green Umschaltung per Config.
|
||||
- Datenqualität ZNS (Inkonsistenzen) → strikte Validierung + Fehlerreport + manuelle Korrekturrouten (später).
|
||||
- Performance bei Erstimport → Batchgrößen, Indizes, COPY/Batch-Insert, Profiling.
|
||||
- Scope‑Creep (weitere Sparten) → Phasen-Governance, ADRs, Feature‑Flags.
|
||||
|
||||
---
|
||||
|
||||
## Erfolgskriterien (Messbar)
|
||||
|
||||
- T0 Import: Komplettes ZNS-Paket < 10 Minuten, Fehlerrate < 0,5% pro Datei, 100% idempotent.
|
||||
- API: P95 Latenz < 150 ms bei 500 RPS Burst (Read‑Only Endpunkte), Fehlerquote < 0,1%.
|
||||
- Rule-Engine: 100% Übereinstimmung mit dokumentierten Beispielen (Golden Files) und ÖTO-Referenzen.
|
||||
- Observability: 4 zentrale Dashboards + 6 Alarm-Regeln aktiv; Backup/Restore in < 30 Minuten validiert.
|
||||
|
||||
---
|
||||
|
||||
## Nächste konkrete Schritte (2‑Wochen Sprint‑Plan)
|
||||
|
||||
1. [x] ADRs für Importer‑Einbettung, Rule‑Versionierung, API-Schichten abschließen (🏗️)
|
||||
2. Exposed-Tabellen vervollständigen und in `SchemaUtils.create`/Migrationen registrieren (👷)
|
||||
3. UseCases: Altersklasse, Lizenz‑Matrix, Abteilungs‑Regeln inkl. Unit‑Tests (👷🧐)
|
||||
4. ZNS‑Importer an Repositories anbinden, Idempotenz-Checks ergänzen, Mini‑ZNS Testlauf (👷🧐)
|
||||
5. API v1 Endpunkte + OpenAPI, Contract‑Tests (👷🧐)
|
||||
6. Observability-Grundlagen (Metriken + Dashboards) (🐧)
|
||||
7. Curator: Docs aktualisieren, Runbooks und Changelogs pflegen (🧹)
|
||||
Reference in New Issue
Block a user