From f839b61f4337aab041fe9dd60c31ed3615b74bac Mon Sep 17 00:00:00 2001 From: StefanMoCoAt Date: Sat, 26 Jul 2025 23:08:26 +0200 Subject: [PATCH] =?UTF-8?q?wichtige=20Neuerungen=20f=C3=BCr=20die=20Weiter?= =?UTF-8?q?entwicklungen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Bericht_Meldestelle_Pro.txt | 82 +++++++ .../C4-Modell_Meldestelle_Pro.puml | 205 ++++++++++++++++++ .../Optimierung_Meldestelle_Pro.md | 62 ++++++ .../Roadmap_Meldestelle_Pro.md | 90 ++++++++ .../entwickungszyklus/TODO_Meldestelle_Pro.md | 42 ++++ 5 files changed, 481 insertions(+) create mode 100644 docs/entwickungszyklus/Bericht_Meldestelle_Pro.txt create mode 100644 docs/entwickungszyklus/C4-Modell_Meldestelle_Pro.puml create mode 100644 docs/entwickungszyklus/Optimierung_Meldestelle_Pro.md create mode 100644 docs/entwickungszyklus/Roadmap_Meldestelle_Pro.md create mode 100644 docs/entwickungszyklus/TODO_Meldestelle_Pro.md diff --git a/docs/entwickungszyklus/Bericht_Meldestelle_Pro.txt b/docs/entwickungszyklus/Bericht_Meldestelle_Pro.txt new file mode 100644 index 00000000..6b6f20c8 --- /dev/null +++ b/docs/entwickungszyklus/Bericht_Meldestelle_Pro.txt @@ -0,0 +1,82 @@ +Umfassender Bericht: Strategie, Architektur & Roadmap für Meldestelle_Pro +Datum: 26. Juli 2025 +Autoren: Stefan-Mo (Fachlicher Experte), Programmier-Meister (Technischer Experte) +Status: Finalisiert & zur Umsetzung freigegeben + +1. Einleitung & Vision +Dieses Dokument ist das Ergebnis einer intensiven Zusammenarbeit, um die Anforderungen an eine moderne Meldestellen-Software zu analysieren und in eine zukunftssichere, technische Strategie zu überführen. Es dient als zentrale Blaupause für die Entwicklung des Projekts "Meldestelle_Pro". + +Die Vision: Meldestelle_Pro wird die führende digitale Plattform für die Verwaltung und Durchführung von Pferdesport-Veranstaltungen in Österreich. Das System wird nicht nur die komplexen Regularien der ÖTO und FEI korrekt abbilden, sondern durch intelligente, integrierte Werkzeuge die Arbeit für Veranstalter, Funktionäre und Teilnehmer revolutionieren. + +Die Grundlage dafür ist eine moderne Software-Architektur, die auf folgenden, in den initialen Architecture Decision Records (ADRs) festgehaltenen, Prinzipien beruht: + +Modulare Microservice-Architektur: Zerlegung des Systems in unabhängige, wartbare Dienste [cite: 0003-microservices-architecture-de.md]. + +Domain-Driven Design (DDD): Die Fachlichkeit und die Sprache der Experten stehen im Zentrum des Entwurfs [cite: 0002-domain-driven-design-de.md]. + +Ereignisgesteuerte Kommunikation: Lose Kopplung und hohe Resilienz durch asynchrone Events via Apache Kafka [cite: 0004-event-driven-communication-de.md]. + +Multiplattform-Client-Strategie: Eine gemeinsame Code-Basis für Web- und Desktop-Anwendungen zur Maximierung der Effizienz und Konsistenz [cite: 0008-multiplatform-client-applications-de.md]. + +2. Das finale DDD-Zieldomänen-Modell +Unsere Analyse hat zu einer Verfeinerung des ursprünglichen Modells geführt. Das System wird in die folgenden, klar abgegrenzten Bounded Contexts (Domänen) gegliedert, die jeweils als eigenständiger Microservice implementiert werden. + +2.1 Fundamentale Domänen (Daten & Regeln) +BC1: OeTO-Verwaltung (Masterdata-Service): Die "Quelle der Wahrheit". Verwaltet alle globalen Regelwerke, Lizenztypen, Turnierkategorien und sportfachlichen Definitionen gemäß ÖTO und FEI. + +BC2: ZNS-Import (ACL): Der "Übersetzer". Ein Anti-Corruption Layer, der die OEPS .dat-Dateien einliest und in saubere, systeminterne Domänen-Events transformiert. + +BC3: Sportler, Pferde & Vereine (z.B. members- & horses-service): Verwalten die Stammdaten aller Akteure und bilden die Basis für Benutzerkonten und Turnier-Assets. + +BC4: Lizenzen & Qualifikationen (licensing-service): Verwaltet die spezifischen sportlichen Berechtigungen einer Person. + +BC5: Veranstaltungsplanung (events-service): Modelliert die hierarchische Struktur von Veranstaltungen (Dach-Veranstaltung -> Turnier-Mandat -> Bewerb). + +2.2 Prozessorientierte Domänen (Workflows & Logik) +BC6: Mandanten- & Lizenz-Verwaltung (tenancy-service): Steuert das Geschäftsmodell. Verwaltet Kunden (Mandanten), Produkte ("Web" vs. "Pro") und deren Software-Lizenzen. + +BC7: Nennungsabwicklung (nennungs-service): Das operative Herzstück. Orchestriert den gesamten Nennprozess, führt die komplexe Zulassungsprüfung durch und erstellt die Startlisten. + +BC8: Abrechnung & Finanzen (billing-service): Die zentrale Kasse. Garantiert eine strikt getrennte Kassenführung pro Turnier-Mandat und verwaltet alle Gebühren, Nenngelder und Preisgelder. + +BC9: Ergebnisdienst (result-service): Erfasst, berechnet und persistiert die finalen Ergebnisse und ist für den korrekten Export im OEPS-Format zuständig. + +BC10: Serien-Verwaltung (championship-service): Verwaltet übergeordnete Cups und Meisterschaften, die sich über mehrere, unabhängige Turniere erstrecken. + +3. Strategische Entwicklungs-Roadmap +Wir verfolgen einen agilen, iterativen Ansatz, um schnellstmöglich ein nutzbares Produkt zu schaffen und aus der Praxis zu lernen. + +Zyklus 1: MVP für C/C-Neu Turniere (Dressur & Springen) +Ziel: Ein voll funktionsfähiges End-to-End-System für den am weitesten verbreiteten Turniertyp. + +Umfang: Implementierung aller Domänen in einer "abgespeckten" Version, die sich auf die Anforderungen von C-Turnieren konzentriert. Dies beinhaltet die manuelle Ergebniserfassung, die grundlegende Nennungs-Validierung und den finalen Ergebnis-Export. + +Ergebnis: Ein produktiv nutzbares System für "Feld-Versuche", um wertvolles Feedback zu sammeln. + +Zyklus 2: Erweiterung für B/A-Turniere & Professionalisierung +Ziel: Abbildung der komplexeren Regeln höherer Turnierkategorien und Automatisierung. + +Umfang: Erweiterung der Masterdata-Domäne um M/S-Regeln. Implementierung des "getrennten Richtens" (Dressur), Anbindung von Zeitmess-Hardware (Springen) und korrekte Preisgeldberechnung. Entwicklung des "Live-Turnier-Cockpits". + +Zyklus 3 & darüber hinaus: Ökosystem & Wachstum +Ziel: Das System um strategische Module zur Kundenbindung und -gewinnung erweitern. + +Umfang: Implementierung der Serien-Verwaltung für Cups/Meisterschaften. Entwicklung des Parcours-Design-Moduls als "Freemium"-Standalone-Tool, um Parcours-Bauer als Multiplikatoren zu gewinnen. + +4. Geplante Optimierungen & nächste Schritte (TODO) +Über die reine Feature-Entwicklung hinaus planen wir folgende Professionalisierungs-Maßnahmen: + +Daten-Synchronisation: Entwicklung einer Strategie zur Aktualisierung der Stammdaten bei neuen zns.zip-Lieferungen. + +Benutzerverwaltung: Implementierung eines Self-Service-Portals für Veranstalter (Vereine), um ihre eigenen Benutzer zu verwalten. + +Funktionärs-Management: Erweiterung des Systems um Funktionen zur Planung und Verwaltung von Funktionärs-Einsätzen. + +Reporting & Analysen: Schaffung einer Reporting-Komponente, die Veranstaltern wertvolle Einblicke und finanzielle Abrechnungen liefert. + +Betrieb & Performance: Einführung von Contract Testing, Resilience Patterns und proaktiver Performance-Optimierung. Langfristige Migration des Deployments auf Kubernetes. + +5. Schlussfolgerung +Das Projekt "Meldestelle_Pro" verfügt nun über eine umfassende, detaillierte und fachlich fundierte Blaupause. Die Kombination aus einer modernen, entkoppelten Microservice-Architektur und einer agilen, praxisorientierten Roadmap stellt sicher, dass wir ein System entwickeln, das nicht nur die heutigen Anforderungen des österreichischen Turniersports erfüllt, sondern auch flexibel genug ist, um zukünftige Herausforderungen und Chancen zu meistern. + +Der Plan ist vollständig. Die nächste Phase ist die Umsetzung. diff --git a/docs/entwickungszyklus/C4-Modell_Meldestelle_Pro.puml b/docs/entwickungszyklus/C4-Modell_Meldestelle_Pro.puml new file mode 100644 index 00000000..dc935438 --- /dev/null +++ b/docs/entwickungszyklus/C4-Modell_Meldestelle_Pro.puml @@ -0,0 +1,205 @@ +@startuml +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml + +' ################################################################## +' ### STYLING-DEFINITIONEN ### +' ################################################################## + +' Globale Layout-Optionen +' LAYOUT_WITH_LEGEND() +LAYOUT_TOP_DOWN() +' LAYOUT_AS_SKETCH() + +' Tags für Technologien und Domänen +!define DE_SPRING_BOOT "Spring Boot & Kotlin" +!define DE_POSTGRES "PostgreSQL DB" +!define DE_KAFKA "Apache Kafka" +!define DE_REDIS "Redis" +!define DE_COMPOSE "Compose Multiplatform" +!define DE_KEYCLOAK "Keycloak" +!define DE_KTOR "Ktor" +!define DE_ZNS_FORMAT "OEPS ZNS (.dat)" +!define DE_ERGEBNIS_FORMAT "OEPS Ergebnis (.erg, .xml)" + +skinparam defaultFontName "Segoe UI" +skinparam defaultFontSize 12 +skinparam roundCorner 20 +skinparam shadowing false + +skinparam person { + BackgroundColor #08427b + BorderColor #08427b + FontColor #FFFFFF + StereotypeFontColor #FFFFFF +} + +skinparam system { + BackgroundColor #1168bd + BorderColor #1168bd + FontColor #FFFFFF + StereotypeFontColor #FFFFFF +} + +skinparam container { + BackgroundColor #4284d3 + BorderColor #4284d3 + FontColor #FFFFFF + StereotypeFontColor #FFFFFF +} + +skinparam database { + BackgroundColor #6c757d + BorderColor #6c757d + FontColor #FFFFFF + StereotypeFontColor #FFFFFF +} + +' ################################################################## +' ### LEVEL 1: SYSTEMKONTEXT-DIAGRAMM ### +' ################################################################## + +title Meldestelle_Pro - C4 Level 1: Systemkontext + +' --- Personen / Akteure --- +Person(reiter, "Reiter / Pferdebesitzer", "Nennt für Turniere, verwaltet eigene Daten.") +Person(veranstalter, "Veranstalter / Meldestelle", "Organisiert Turniere, managt Nennungen, erfasst Ergebnisse.") +Person(admin, "Mandanten-Admin", "Interner Admin von Meldestelle_Pro, verwaltet Kunden & Lizenzen.") +Person(parcoursbauer, "Parcours-Bauer", "Entwirft Parcours-Skizzen.") +Person(funktionaer, "Funktionär (Richter, Zeitnehmer)", "Nutzt digitale Werkzeuge zur Bewertung und Zeitmessung.") + +' --- Externe Systeme --- +System_Ext(oeps_zns, "OEPS ZNS", "Zentrales Nenn-System des OEPS.") +System_Ext(zeitmessung, "Zeitmess-Systeme", "Professionelle Hardware (z.B. Alge, Microgate).") +System_Ext(email, "E-Mail System", "Versendet Benachrichtigungen.") + +' --- Unser System --- +System(meldestelle_pro, "Meldestelle_Pro", "Die zentrale Plattform zur Verwaltung und Durchführung von Pferdesport-Veranstaltungen.") + +' --- Beziehungen --- +Rel(reiter, meldestelle_pro, "Nennt online, sieht Start- & Ergebnislisten") +Rel(veranstalter, meldestelle_pro, "Verwaltet Turniere & Finanzen, nutzt das Live-Cockpit") +Rel(admin, meldestelle_pro, "Richtet neue Vereine (Mandanten) ein") +Rel(parcoursbauer, meldestelle_pro, "Nutzt das Parcours-Design-Modul (Freemium)") +Rel(funktionaer, meldestelle_pro, "Nutzt die Schreiber-App & das Parcours-Cockpit") + +Rel(meldestelle_pro, oeps_zns, "Importiert Stammdaten (.dat), exportiert Ergebnisse (.erg/.xml)", DE_ZNS_FORMAT " / " DE_ERGEBNIS_FORMAT) +Rel(meldestelle_pro, zeitmessung, "Empfängt Zeit-Signale", "Serielle Schnittstelle / USB") +Rel(meldestelle_pro, email, "Sendet Bestätigungen & Benachrichtigungen", "SMTP") + +' ################################################################## +' ### LEVEL 2: CONTAINER-DIAGRAMM ### +' ################################################################## + +title Meldestelle_Pro - C4 Level 2: Container-Diagramm + +' --- Externe Systeme & Personen (aus Level 1 wiederverwenden) --- +' Positionierung der externen Akteure +LAYOUT_LANDSCAPE() +reiter -- (0, 10) +veranstalter -- (0, 10) +admin -- (0, 10) +parcoursbauer -- (0, 10) +funktionaer -- (0, 10) + +System_Boundary(c1, "Meldestelle_Pro") { + + ' --- Client-Anwendungen --- + Container(webapp, "Web-Anwendung", DE_COMPOSE, "Bietet Online-Nennung für Reiter und Verwaltungs-Dashboards für Admins/Veranstalter.") + Container(desktopapp, "Desktop-Anwendung", DE_COMPOSE, "Offline-fähige 'Pro'-Version für die Meldestelle mit Hardware-Anbindung und vollem Funktionsumfang.") + + ' --- API Gateway --- + Container(api_gateway, "API Gateway", DE_KTOR, "Zentraler, gesicherter Eingangspunkt für alle API-Anfragen. Leitet Anfragen an die Backend-Services weiter.") + + ' --- Datenbanken & Messaging --- + ContainerDb(postgres_db, "Relationale Datenbank", DE_POSTGRES, "Speichert die primären Geschäftsdaten (Personen, Pferde, Events etc.). Jeder Service hat ein eigenes, isoliertes Schema.") + ContainerDb(redis, "In-Memory Datenspeicher", DE_REDIS, "Dient als High-Performance Cache und als Event Store für das Event Sourcing.") + ContainerQueue(kafka, "Message Bus", DE_KAFKA, "Ermöglicht die asynchrone, ereignisgesteuerte Kommunikation zwischen den Services.") + + ' --- Unterstützende Services --- + Container(keycloak, "Identity & Access Mgmt", DE_KEYCLOAK, "Zentraler Service für Authentifizierung und Autorisierung (Benutzer-Logins, Rollen).") + + ' --- Bounded Contexts / Microservices --- + System_Boundary(c2, "Backend Services") { + + package "Stammdaten & Import" { + Container(masterdata_service, "Masterdata Service", DE_SPRING_BOOT, "Verwaltet globale Regeln, Lizenzen, Qualifikationen und sportfachliche Definitionen.") + Container(zns_import_acl, "ZNS-Import (ACL)", DE_SPRING_BOOT, "Liest und übersetzt die OEPS .dat Dateien in Domänen-Events.") + Container(personen_service, "Personen/Pferde Service", DE_SPRING_BOOT, "Verwaltet die Stammdaten von Personen, Pferden und Vereinen.") + } + + package "Planung & Abwicklung" { + Container(events_service, "Veranstaltungs-Service", DE_SPRING_BOOT, "Verwaltet die Struktur von Veranstaltungen (Dach-Event, Turnier, Bewerb).") + Container(nennungs_service, "Nennungs-Service", DE_SPRING_BOOT, "Orchestriert den Nennprozess von der Abgabe bis zur Startliste.") + Container(ergebnis_service, "Ergebnis-Service", DE_SPRING_BOOT, "Erfasst, berechnet und exportiert die finalen Ergebnisse.") + } + + package "Geschäfts- & Meta-Logik" { + Container(tenancy_service, "Mandanten-Service", DE_SPRING_BOOT, "Verwaltet Kunden, Produkte ('Web'/'Pro') und Software-Lizenzen.") + Container(billing_service, "Abrechnungs-Service", DE_SPRING_BOOT, "Zentrale Kasse für Nenngelder, Preisgelder und Gebühren.") + Container(championship_service, "Serien-Service", DE_SPRING_BOOT, "Verwaltet übergreifende Cups und Meisterschaften.") + } + } +} + + +' --- Beziehungen Level 2 --- + +' Benutzer -> Frontend / Gateway +Rel(reiter, webapp, "Nutzt") +Rel(veranstalter, webapp, "Nutzt") +Rel(veranstalter, desktopapp, "Nutzt") +Rel(admin, webapp, "Nutzt") +Rel(parcoursbauer, webapp, "Nutzt") +Rel(funktionaer, desktopapp, "Nutzt") + +Rel(webapp, api_gateway, "Macht API-Aufrufe", "HTTPS/JSON") +Rel(desktopapp, api_gateway, "Macht API-Aufrufe", "HTTPS/JSON") + +' Gateway -> Backend +Rel(api_gateway, masterdata_service, "Leitet Anfragen weiter") +Rel(api_gateway, personen_service, "Leitet Anfragen weiter") +Rel(api_gateway, events_service, "Leitet Anfragen weiter") +Rel(api_gateway, nennungs_service, "Leitet Anfragen weiter") +Rel(api_gateway, ergebnis_service, "Leitet Anfragen weiter") +Rel(api_gateway, billing_service, "Leitet Anfragen weiter") +Rel(api_gateway, tenancy_service, "Leitet Anfragen weiter") +Rel(api_gateway, championship_service, "Leitet Anfragen weiter") + +' Authentifizierung +Rel(api_gateway, keycloak, "Validiert JWT Token") +Rel(webapp, keycloak, "Authentifiziert Benutzer", "OAuth2") +Rel(desktopapp, keycloak, "Authentifiziert Benutzer", "OAuth2") + +' Service -> Datenbanken +Rel(masterdata_service, postgres_db, "Liest/Schreibt", "JDBC") +Rel(personen_service, postgres_db, "Liest/Schreibt", "JDBC") +Rel(events_service, postgres_db, "Liest/Schreibt", "JDBC") +Rel(nennungs_service, postgres_db, "Liest/Schreibt", "JDBC") +Rel(ergebnis_service, postgres_db, "Liest/Schreibt", "JDBC") +Rel(billing_service, postgres_db, "Liest/Schreibt", "JDBC") +Rel(tenancy_service, postgres_db, "Liest/Schreibt", "JDBC") +Rel(championship_service, postgres_db, "Liest/Schreibt", "JDBC") +Rel(zns_import_acl, postgres_db, "Liest (für Abgleich)", "JDBC") + + +' Service -> Caching & Event Store +Rel_Neighbor(nennungs_service, redis, "Nutzt für Caching & Event Sourcing") +Rel_Neighbor(ergebnis_service, redis, "Nutzt für Caching & Event Sourcing") + +' Asynchrone Kommunikation via Kafka +Rel(zns_import_acl, kafka, "Publiziert 'Stammdaten Aktualisiert' Events") +Rel(personen_service, kafka, "Subscribed Events von ZNS-Import") +Rel(nennungs_service, kafka, "Publiziert 'Nennung Eingereicht' & 'Startliste Finalisiert' Events") +Rel(billing_service, kafka, "Subscribed 'Nennung Eingereicht' Event") +Rel(ergebnis_service, kafka, "Subscribed 'Startliste Finalisiert' Event, Publiziert 'Ergebnis Finalisiert' Event") +Rel(championship_service, kafka, "Subscribed 'Ergebnis Finalisiert' Event") + +' Direkte Service-zu-Service Kommunikation (Beispiele, sollte minimiert werden) +Rel(nennungs_service, masterdata_service, "Fragt Regeln für Validierung an", "HTTPS/JSON") +Rel(nennungs_service, personen_service, "Fragt Reiter/Pferde-Details an", "HTTPS/JSON") + + +' Hardware Anbindung +Rel(desktopapp, zeitmessung, "Empfängt Zeit-Signale", "Serielle Schnittstelle / USB") + +@enduml diff --git a/docs/entwickungszyklus/Optimierung_Meldestelle_Pro.md b/docs/entwickungszyklus/Optimierung_Meldestelle_Pro.md new file mode 100644 index 00000000..5689898d --- /dev/null +++ b/docs/entwickungszyklus/Optimierung_Meldestelle_Pro.md @@ -0,0 +1,62 @@ +# TODO-Liste: Optimierung & Performance-Verbesserung für Meldestelle_Pro + +**Datum:** 26. Juli 2025 + +Dieses Dokument listet die geplanten Optimierungsmaßnahmen in den Bereichen Developer Experience, Betrieb & Performance sowie strategische Weiterentwicklung auf. + +--- + +### 1. Developer Experience (DevEx) & Code-Qualität + +*Ziel: Die Effizienz, Qualität und Wartbarkeit der Softwareentwicklung maximieren.* + +- [ ] **Logging-Strategie implementieren:** + - [ ] Ein zentrales Logging-Framework (z.B. SLF4J mit Logback) im `core`-Modul definieren. + - [ ] Alle `println`-Anweisungen im gesamten Projekt durch strukturierte Logger-Aufrufe ersetzen. + - [ ] Ein konsistentes Log-Format mit Korrelations-IDs für die Nachverfolgung von Anfragen über Service-Grenzen hinweg etablieren. + +- [ ] **Contract Testing einführen:** + - [ ] Ein Framework für Contract Testing (z.B. Pact) evaluieren und in den Build-Prozess integrieren. + - [ ] Einen ersten Contract zwischen `nennungs-service` (Consumer) und `members-service` (Provider) als Pilotprojekt erstellen. + - [ ] Den Contract-Test in die CI/CD-Pipeline integrieren, um inkompatible Änderungen automatisch zu verhindern. + +- [ ] **Resilience Patterns implementieren:** + - [ ] Eine Bibliothek für Resilience Patterns (z.B. Resilience4j) in die Service-Kommunikation integrieren. + - [ ] "Retry"-Mechanismus für kritische, temporär fehlschlagende Service-Aufrufe (z.B. bei der Nennungsvalidierung) implementieren. + - [ ] "Circuit Breaker"-Muster für Services implementieren, die bei längeren Ausfällen eines abhängigen Services nicht blockieren sollen. + +--- + +### 2. Betrieb & Performance + +*Ziel: Ein schnelles, sicheres und zuverlässiges System im Live-Betrieb gewährleisten.* + +- [ ] **Advanced Caching-Strategien umsetzen:** + - [ ] "Cache Warming" für die `Masterdata-Domäne` implementieren, um Regelwerke beim Service-Start vorzuladen. + - [ ] Ein Monitoring-Dashboard in Grafana für Cache-Metriken (Hit/Miss Ratios, Cache-Größe) erstellen. + - [ ] Die Cache-Konfiguration (z.B. TTLs) basierend auf den Monitoring-Daten feinjustieren. + +- [ ] **Datenbank-Performance proaktiv optimieren:** + - [ ] Regelmäßige Analyse von SQL-Abfragen mit `EXPLAIN ANALYZE` in den Entwicklungs-Workflow integrieren. + - [ ] Fehlende oder ineffiziente Indizes für die Kern-Entitäten (`Nennung`, `DomPerson` etc.) identifizieren und hinzufügen. + - [ ] Connection-Pool-Größen für jeden Service basierend auf erwarteter Last optimieren. + +- [ ] **Deployment auf Kubernetes vorbereiten:** + - [ ] Helm-Charts für jeden Microservice erstellen, um das Deployment zu standardisieren. + - [ ] Eine Strategie für "Rolling Updates" definieren, um Aktualisierungen ohne Downtime zu ermöglichen. + - [ ] "Liveness"- und "Readiness"-Probes für alle Services implementieren, damit Kubernetes den Zustand der Services überwachen kann. + +--- + +### 3. Strategische & Zukünftige Optimierungen + +*Ziel: Die technologische Basis für zukünftige Anforderungen und Skalierbarkeit schaffen.* + +- [ ] **Echtzeit-Updates mit WebSockets implementieren:** + - [ ] Eine WebSocket-Schnittstelle im `ergebnis-service` und in der `client-app` implementieren. + - [ ] Das "Live-Turnier-Cockpit" so umbauen, dass es Status-Änderungen und Zwischenergebnisse per Push-Nachricht erhält statt durch Polling. + +- [ ] **GraphQL als API-Alternative evaluieren:** + - [ ] Einen Prototyp für eine GraphQL-Schnittstelle (z.B. für die `events-service`-API) erstellen. + - [ ] Die Komplexität und den Nutzen im Vergleich zu REST für unsere Client-Anwendungen bewerten. + - [ ] Entscheiden, ob zukünftige oder bestehende APIs zusätzlich mit GraphQL angeboten werden sollen. diff --git a/docs/entwickungszyklus/Roadmap_Meldestelle_Pro.md b/docs/entwickungszyklus/Roadmap_Meldestelle_Pro.md new file mode 100644 index 00000000..3bea712d --- /dev/null +++ b/docs/entwickungszyklus/Roadmap_Meldestelle_Pro.md @@ -0,0 +1,90 @@ +# Meldestelle_Pro: Strategische Roadmap & finales Zieldomänen-Modell + +**Datum:** 26. Juli 2025 +**Autor:** Programmier-Meister (in Abstimmung mit Stefan-Mo) + +Dieses Dokument fasst die strategische Entwicklungs-Roadmap und das finale, detaillierte Domänen-Modell für das Projekt "Meldestelle_Pro" zusammen. Es dient als zentrale Blaupause für die gesamte weitere Entwicklung. + +--- + +## Teil 1: Strategische Entwicklungs-Roadmap + +Wir verfolgen einen agilen, iterativen Ansatz. Jeder Zyklus liefert ein funktionierendes, in der Praxis testbares Produkt ("Minimum Viable Product" - MVP), das wir basierend auf Feedback schrittweise erweitern. + +### Zyklus 1: MVP für C/C-Neu Turniere (Dressur & Springen) + +* **Ziel:** Ein voll funktionsfähiges End-to-End-System für den am weitesten verbreiteten Turniertyp, um schnelles Feedback aus "Feld-Versuchen" zu erhalten. +* **Kern-Features pro Domäne:** + * **OeTO-Verwaltung (Masterdata):** Implementierung der Regeln für Klassen E-LM, einfache Lizenztypen (Reiterpass, R1) und Turnierkategorien C/C-Neu. + * **ZNS-Import (ACL):** Implementierung des Imports der `.dat`-Dateien (`LIZENZ01`, `PFERDE01`, `VEREIN01`) zur Befüllung der Stammdaten. + * **Sportler, Pferde & Lizenzen:** Grundlegende Verwaltung der importierten `DomPerson`, `DomPferd` und `DomLizenz` Entitäten. + * **Veranstaltungsplanung (Events):** Der "Event-Setup-Wizard" wird auf die Erstellung von C/C-Neu Turnieren mit dem dreistufigen Modell (`Dach-Veranstaltung` -> `Turnier-Mandat` -> `Bewerb`) beschränkt. + * **Nennungsabwicklung:** Implementierung der Online-Nennung, Validierung für die in C-Turnieren relevanten Lizenzen und Erstellung von `Startlisten`. + * **Abrechnung & Finanzen:** Verbuchung von `Nenngeld` und `Startgeld`. Preisgelder und komplexe Gebühren sind vorerst ausgenommen. + * **Ergebnisdienst:** Manuelle Eingabe für "gemeinsames Richten" (Dressur) und "Standardspringen" (Springen). Finaler Export der Ergebnisse im dualen Format (`.erg` und `.erg.xml`). + +### Zyklus 2: Erweiterung für B/A-Turniere & Professionalisierung + +* **Ziel:** Abbildung der komplexeren Regeln höherer Turnierkategorien und Automatisierung von Prozessen. +* **Kern-Features pro Domäne:** + * **Masterdata:** Erweiterung um Regeln für Klassen M und S, komplexere Lizenztypen (R2, R3, etc.) und deren Höherreihungs-Logik. + * **Springreiten-Bewertung:** Anbindung externer Zeitmessgeräte über die "Hardware-Adapter-Schicht". + * **Dressur-Bewertung:** Implementierung des "getrennten Richtens" und der Erfassung von Einzelnoten pro Richter. + * **Abrechnung & Finanzen:** Implementierung der korrekten Preisgeldberechnung und -aufteilung gemäß ÖTO. + * **Client-App:** Entwicklung des "Live-Turnier-Cockpits" für die Meldestelle. + +### Zyklus 3 & darüber hinaus: Ökosystem & Wachstum + +* **Ziel:** Das System um strategische Module erweitern, die über die reine Turnierabwicklung hinausgehen. +* **Kern-Features pro Domäne:** + * **Serien-Verwaltung:** Implementierung des `championship-service` zur Verwaltung von Cups und Meisterschaften, die sich über mehrere Turniere erstrecken. + * **Parcours-Design-Modul:** Entwicklung des visuellen Editors als "Freemium"-Tool, um Parcours-Bauer als neue Nutzergruppe zu gewinnen. + * **Erweiterung der Sparten:** Schrittweise Implementierung der spezifischen Logiken für weitere Disziplinen wie Vielseitigkeit, Fahren etc. + +--- + +## Teil 2: Detailliertes Zieldomänen-Modell (DDD Context Map) + +Dieses Modell ist die finale Blaupause unserer Architektur. Es integriert die Struktur Ihrer `.puml`-Diagramme in unsere service-orientierte Landschaft. + +### BC1: OeTO-Verwaltung (Masterdata-Service) +* **Kern-Verantwortung:** Definiert alle Regelwerke, Typen und Klassifikationen. +* **Schlüssel-Konzepte:** `LizenzTypGlobal`, `QualifikationsTyp`, `BewerbsKategorieOetoDefinition`, `Sportfachliche_Stammdaten` (z.B. Dressuraufgaben, Richtverfahren). + +### BC2: ZNS-Import (Anti-Corruption-Layer) +* **Kern-Verantwortung:** Isoliert das System von den OEPS-Rohdatenformaten. Liest `.dat`-Dateien und publiziert saubere Domänen-Events. +* **Schlüssel-Konzepte:** `ZNS_Daten_Uebersetzer`, `ZNS_LIZENZ01_dat_Satz`, etc.. + +### BC3: Sportler, Pferde & Vereine (z.B. `members-` & `horses-service`) +* **Kern-Verantwortung:** Hält die Stammdaten der Akteure. +* **Schlüssel-Aggregate:** `DomPerson`, `DomPferd`, `DomVerein`. + +### BC4: Lizenzen & Qualifikationen (`licensing-service`) +* **Kern-Verantwortung:** Verwaltet die Berechtigungen von Personen. +* **Schlüssel-Aggregate:** `Lizenznehmer` (referenziert `DomPerson`). Enthält Listen von `DomLizenz` und `DomQualifikation`. + +### BC5: Veranstaltungsplanung (`events-service`) +* **Kern-Verantwortung:** Modelliert die komplette Struktur von Veranstaltungen. +* **Schlüssel-Aggregate & Entitäten:** `DachVeranstaltung` -> `TurnierMandat` -> `Bewerb` -> `Abteilung`. Nutzt spartenspezifische Detail-Entitäten wie `SpringBewerbDetails`. + +### BC6: Mandanten- & Lizenz-Verwaltung (`tenancy-service`) +* **Kern-Verantwortung:** Steuert das Geschäftsmodell und den Software-Zugriff. +* **Schlüssel-Aggregate:** `Mandant` (referenziert `DomVerein`), `Lizenz`. + +### BC7: Nennungsabwicklung (`nennungs-service`) +* **Kern-Verantwortung:** Orchestriert den Nennprozess. +* **Schlüssel-Aggregate:** `Nennung`, `Startliste`. +* **Wichtiges Entwurfs-Muster:** **Daten-Snapshots**. Die `Nennung` speichert beim Erstellen eine Kopie der relevanten Daten (z.B. in `ReiterReferenzVO`, `PferdeReferenzVO`), um historische Korrektheit zu garantieren. + +### BC8: Abrechnung & Finanzen (`billing-service`) +* **Kern-Verantwortung:** Garantiert eine strikt getrennte Kassenführung und zentrale Gebührenberechnung. +* **Schlüssel-Aggregate & Entitäten:** `TurnierKonto` (pro `TurnierMandat`), `Gebuehrenposten`. + +### BC9: Ergebnisdienst (`result-service`) +* **Kern-Verantwortung:** Erfasst, berechnet und exportiert Ergebnisse. +* **Schlüssel-Aggregate:** `Bewerbsergebnis` (pro `Abteilung`). +* **Wichtiges Entwurfs-Muster:** **Polymorphe `LeistungVO`**. Nutzt spezifische Value Objects (`DressurLeistungVO`, `SpringenLeistungVO`) zur Abbildung der unterschiedlichen Ergebnisstrukturen pro Sparte. + +### BC10: Serien-Verwaltung (`championship-service`) +* **Kern-Verantwortung:** Verwaltet übergreifende Cups und Meisterschaften. +* **Schlüssel-Aggregate:** `Serie`, die auf `Bewerbe` aus der `Events-Domäne` verweist. diff --git a/docs/entwickungszyklus/TODO_Meldestelle_Pro.md b/docs/entwickungszyklus/TODO_Meldestelle_Pro.md new file mode 100644 index 00000000..ae4f95f0 --- /dev/null +++ b/docs/entwickungszyklus/TODO_Meldestelle_Pro.md @@ -0,0 +1,42 @@ +# TODO-Liste: Nächste Schritte & Meta-Themen für Meldestelle_Pro + +**Datum:** 26.Juli 2025 + +Dieses Dokument listet die übergeordneten Aufgaben und konzeptionellen Ausarbeitungen auf, die parallel zur oder nach der initialen MVP-Entwicklung (Zyklus 1) angegangen werden müssen. + +--- + +### 1. Daten-Aktualisierung & Synchronisation + +- [ ] **Konzept ausarbeiten:** Eine detaillierte Strategie für die Synchronisation von aktualisierten `zns.zip`-Dateien definieren. + - [ ] **Frage klären:** Wie identifizieren wir Änderungen in den Rohdaten? (z.B. über Zeitstempel, Hash-Werte) + - [ ] **Frage klären:** Wie gehen wir mit Konflikten um? (z.B. wenn ein Datensatz manuell in unserem System geändert und gleichzeitig vom OEPS aktualisiert wurde) +- [ ] **Implementierung im `ZNS-Import (ACL)`-Service:** Die Update-Logik implementieren, die bestehende `DomPerson`-, `DomPferd`- und `DomLizenz`-Entitäten aktualisiert, anstatt sie nur neu anzulegen. +- [ ] **Testfälle definieren:** Spezifische Tests für Update-Szenarien erstellen (z.B. "Reiter erhält neue Lizenz", "Pferd wechselt Besitzer"). + +--- + +### 2. Benutzerverwaltung für Veranstalter (Onboarding) + +- [ ] **Konzept ausarbeiten:** Den genauen Workflow für das Onboarding eines neuen Vereins (Mandanten) definieren. +- [ ] **Rollen in Keycloak anlegen:** Die Rollen `Mandanten-Administrator` und `Veranstalter` mit den entsprechenden Berechtigungen in Keycloak konfigurieren. +- [ ] **Self-Service-UI entwerfen:** Eine einfache Benutzeroberfläche für den "Vereins-Admin" entwerfen, mit der er weitere Benutzer seines Vereins einladen und verwalten kann. +- [ ] **Implementierung der UI:** Die Self-Service-Benutzerverwaltung in der Client-Anwendung umsetzen. + +--- + +### 3. Funktionärs-Management + +- [ ] **Domäne erweitern:** Die `Members-Domäne` (oder eine neue, spezialisierte `Funktionärs-Domäne`) um Entitäten zur Verwaltung von Funktionärs-Qualifikationen und Verfügbarkeiten erweitern. +- [ ] **UI für Funktionärs-Planung entwerfen:** Eine Ansicht für den `Veranstalter` oder `Mandanten-Admin` konzipieren, um verfügbare Funktionäre für ein Turnier zu suchen und einzuplanen (basierend auf der Idee der `FunktionaerEinsatzPlanung`). +- [ ] **Implementierung der Funktionärs-Verwaltung:** Die entsprechenden Backend-Services und UI-Komponenten umsetzen. + +--- + +### 4. Reporting & Analysen + +- [ ] **Anforderungen definieren:** In Abstimmung mit Ihnen (Stefan-Mo) eine Liste der wichtigsten Berichte und Statistiken erstellen, die ein Veranstalter benötigt. + - [ ] Mögliche Berichte: Finanzielle Gesamtabrechnung, Nennungs-Statistiken pro Bewerb, Teilnehmer-Demografie etc. +- [ ] **Technisches Konzept erstellen:** Entscheiden, wie die Reporting-Komponente auf die Daten der verschiedenen Microservices zugreift (z.B. über dedizierte Query-APIs oder ein separates Data-Warehouse). +- [ ] **UI für Berichte entwerfen:** Eine übersichtliche Dashboard-Ansicht für den `Veranstalter` gestalten, in der er seine Berichte abrufen und exportieren kann. +- [ ] **Implementierung der Reporting-Komponente:** Die Backend-Logik zur Datenaggregation und die Frontend-Komponenten zur Visualisierung umsetzen.