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>
141 lines
6.3 KiB
Markdown
141 lines
6.3 KiB
Markdown
# 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 (🧹)
|