# 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 (🧹)