mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f7d11ccf97
meldestelle/backend/services/masterdata/docs/ROADMAP.md
Stefan Mogeritsch e3d517cc5e docs(CHANGELOG & ROADMAP): update for completed phases, added features, and integrations 
- Documented new features: `AbteilungsRegelService`, `CompetitionWarningService`, `profile-feature`, `billing-feature`, and V2-Screens in CHANGELOG.
- Marked P1, P2, and P3 contexts as complete in ROADMAP, including MVP and integration phases.
- Added ZNS-Importer enhancements and frontend feature integrations to ROADMAP progress.
- Updated status of major project phases to reflect completion.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
2026-03-30 16:41:53 +02:00

6.4 KiB
Raw Blame History

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:
    • ADR-Set im Repo (Rules, DB, Import, API) → ADR-0017, ADR-0018, ADR-0019
    • Operative Runbooks (Backup/Restore, Re-Import, Rollback) -> masterdata-ops.md

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. 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 (🧹)
  8. Frontend-Feature "profile-feature" & "billing-feature" integriert (🎨)