mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a50b1b3822
meldestelle/README.md
stefan 65a0084f91 docs: Migrationsplan für Projekt-Restrukturierung hinzugefügt 
- Detaillierter Plan zur Migration von alter zu neuer Modulstruktur
- Umfasst Überführung von shared-kernel zu core-Modulen
- Definiert Migration von Fachdomänen zu bounded contexts:
  * master-data → masterdata-Module
  * member-management → members-Module
  * horse-registry → horses-Module
  * event-management → events-Module
- Beschreibt Verlagerung von api-gateway zu infrastructure/gateway
- Strukturiert nach Domain-driven Design Prinzipien
- Berücksichtigt Clean Architecture Layering (domain, application, infrastructure, api)
2025-07-25 13:05:42 +02:00

348 lines
8.7 KiB
Markdown
Raw Blame History

# Meldestelle
## Überblick
Meldestelle ist ein modulares System zur Verwaltung von Pferdesportveranstaltungen. Das System ermöglicht die Registrierung von Pferden, Mitgliedern und Veranstaltungen sowie die Verwaltung von Stammdaten.
Das Projekt wurde kürzlich auf eine modulare Architektur migriert, um die Wartbarkeit und Erweiterbarkeit zu verbessern.
## Systemanforderungen
- Java 21
- Kotlin 2.1.21
- Gradle 8.14
- Docker und Docker Compose
## Infrastruktur
Das System nutzt folgende Dienste:
- **PostgreSQL 16**: Primäre Datenbank
- **Redis 7**: Caching
- **Keycloak 23.0**: Authentifizierung und Autorisierung
- **Kafka 7.5.0**: Messaging und Event-Streaming
- **Zipkin**: Distributed Tracing
- **Prometheus & Grafana**: Monitoring (optional)
## Projektstruktur
Das Projekt ist in folgende Hauptmodule unterteilt:
- **core**: Gemeinsame Kernkomponenten
- core-domain: Domänenmodelle und Geschäftslogik
- core-utils: Allgemeine Hilfsfunktionen
- **masterdata**: Umfassende Verwaltung von Stammdaten für Pferdesportveranstaltungen
- **Funktionalität**: Länder (ISO-Codes, EU/EWR-Mitgliedschaft), Bundesländer (OEPS/ISO-Codes), Altersklassen (Teilnahmeberechtigung), Turnierplätze (Typ, Abmessungen, Boden)
- **API-Endpunkte**: 37 REST-Endpunkte mit vollständiger CRUD-Funktionalität
- **Geschäftslogik**: Validierung, Duplikatsprüfung, Berechtigung, Eignung für Disziplinen
- masterdata-api: REST-Controller und DTO-Definitionen
- masterdata-application: Use Cases und Geschäftslogik
- masterdata-domain: Domänenmodelle und Repository-Interfaces
- masterdata-infrastructure: Datenbankzugriff und Persistierung
- masterdata-service: Spring Boot Service-Implementierung
- **members**: Mitgliederverwaltung
- members-api: API-Definitionen
- members-application: Anwendungslogik
- members-domain: Domänenmodelle
- members-infrastructure: Infrastrukturkomponenten
- members-service: Service-Implementierung
- **horses**: Pferderegistrierung
- horses-api: API-Definitionen
- horses-application: Anwendungslogik
- horses-domain: Domänenmodelle
- horses-infrastructure: Infrastrukturkomponenten
- horses-service: Service-Implementierung
- **events**: Veranstaltungsverwaltung
- events-api: API-Definitionen
- events-application: Anwendungslogik
- events-domain: Domänenmodelle
- events-infrastructure: Infrastrukturkomponenten
- events-service: Service-Implementierung
- **infrastructure**: Gemeinsame Infrastrukturkomponenten
- auth: Authentifizierung
- cache: Caching
- event-store: Event-Speicher
- gateway: API-Gateway
- messaging: Messaging-Infrastruktur
- monitoring: Monitoring-Komponenten
- **client**: Client-Anwendungen
- common-ui: Gemeinsame UI-Komponenten
- desktop-app: Desktop-Anwendung
- web-app: Web-Anwendung
## Installation und Setup
### Voraussetzungen
Stellen Sie sicher, dass Java 21, Docker und Docker Compose installiert sind.
### Docker-Infrastruktur
Das System bietet verschiedene Docker-Konfigurationen für unterschiedliche Umgebungen:
#### Entwicklungsumgebung (Schnellstart)
```bash
# Infrastruktur starten
docker-compose up -d
# Status überprüfen
docker-compose ps
# Logs anzeigen
docker-compose logs -f
```
Dies startet alle erforderlichen Dienste wie PostgreSQL, Redis, Keycloak, Kafka, Zipkin und optional Prometheus und Grafana.
#### Produktionsumgebung
Für die Produktionsumgebung siehe **[README-PRODUCTION.md](README-PRODUCTION.md)** - enthält:
- Umfassende Sicherheitskonfiguration
- SSL/TLS-Setup
- Detaillierte Troubleshooting-Anleitung
- Backup- und Wiederherstellungsverfahren
#### Umgebungsvariablen
Für die Konfiguration von Umgebungsvariablen siehe **[README-ENV.md](README-ENV.md)** - enthält:
- Vollständige Umgebungsvariablen-Dokumentation
- Validierungsskripte
- Konfigurationsbeispiele
### Validierung und Troubleshooting
```bash
# Umgebungsvariablen validieren
./validate-env.sh
# Docker-Compose Konfiguration validieren
./validate-docker-compose.sh
# Service-Status überprüfen
docker-compose ps
# Service-Logs anzeigen
docker-compose logs [service-name]
```
### Projekt bauen
```bash
./gradlew build
```
### Dienste starten
```bash
# Gateway starten
./gradlew :infrastructure:gateway:bootRun
# Masterdata-Service starten
./gradlew :masterdata:masterdata-service:bootRun
# Members-Service starten
./gradlew :members:members-service:bootRun
# Horses-Service starten
./gradlew :horses:horses-service:bootRun
# Events-Service starten
./gradlew :events:events-service:bootRun
```
### Client-Anwendungen starten
```bash
# Desktop-Anwendung starten
./gradlew :client:desktop-app:run
# Web-Anwendung bauen
./gradlew :client:web-app:build
```
## Entwicklung
### Aktuelle Migrationshinweise
Das Projekt wurde kürzlich von einer monolithischen Struktur zu einer modularen Architektur migriert. Die Migration umfasste:
- Umzug von `:shared-kernel` zu `core`-Modulen
- Umzug von `:master-data` zu `masterdata`-Modulen
- Umzug von `:member-management` zu `members`-Modulen
- Umzug von `:horse-registry` zu `horses`-Modulen
- Umzug von `:event-management` zu `events`-Modulen
- Umzug von `:api-gateway` zu `infrastructure/gateway`
- Umzug von `:composeApp` zu `client`-Modulen
Es gibt noch einige offene Probleme, insbesondere bei den Client-Modulen, die Kotlin Multiplatform und Compose Multiplatform verwenden.
### Entwicklungsrichtlinien
- Verwenden Sie die in der Projektstruktur definierten Module
- Folgen Sie den Architekturentscheidungen (ADRs) im Verzeichnis `docs/architecture/adr` (verfügbar in Deutsch mit Dateiendung `-de.md`)
- Verwenden Sie die C4-Diagramme im Verzeichnis `docs/architecture/c4` für einen Überblick über die Systemarchitektur (verfügbar in Deutsch mit Dateiendung `-de.puml`)
- Verwenden Sie die Datenmodelle aus `docs/architecture/data-model`
### Tests ausführen
```bash
./gradlew test
```
## Docker Troubleshooting (Entwicklungsumgebung)
### Häufige Probleme und Lösungen
#### 1. Services starten nicht
```bash
# Alle Services stoppen und neu starten
docker-compose down
docker-compose up -d
# Einzelnen Service neu starten
docker-compose restart [service-name]
# Service-Logs überprüfen
docker-compose logs [service-name]
```
#### 2. Port bereits belegt
```bash
# Verwendete Ports prüfen
netstat -tulpn | grep :[port]
# oder
lsof -i :[port]
# Ports in .env anpassen
nano .env
# Beispiel: API_PORT=8081 statt 8080
```
#### 3. Datenbank-Verbindungsfehler
```bash
# PostgreSQL-Status prüfen
docker-compose exec postgres pg_isready -U meldestelle
# Datenbank-Logs anzeigen
docker-compose logs postgres
# Verbindung manuell testen
docker-compose exec postgres psql -U meldestelle -d meldestelle
```
#### 4. Keycloak-Authentifizierung fehlgeschlagen
```bash
# Keycloak-Status prüfen
docker-compose logs keycloak
# Keycloak Admin-Console öffnen
# http://localhost:8180/admin (admin/admin)
# Keycloak-Datenbank zurücksetzen
docker-compose down
docker volume rm meldestelle_postgres-data
docker-compose up -d
```
#### 5. Kafka-Verbindungsprobleme
```bash
# Kafka-Status prüfen
docker-compose exec kafka kafka-topics --bootstrap-server localhost:9092 --list
# Zookeeper-Status prüfen
docker-compose exec zookeeper nc -z localhost 2181
# Kafka-Logs anzeigen
docker-compose logs kafka zookeeper
```
#### 6. Speicherplatz-Probleme
```bash
# Docker-Speicherverbrauch prüfen
docker system df
# Ungenutzte Ressourcen bereinigen
docker system prune -f
# Volumes bereinigen (ACHTUNG: Datenverlust!)
docker system prune -f --volumes
```
#### 7. Performance-Probleme
```bash
# Ressourcenverbrauch überwachen
docker stats
# Container-Limits anpassen (in docker-compose.yml)
# deploy:
# resources:
# limits:
# memory: 1G
# cpus: '0.5'
```
### Nützliche Docker-Befehle
```bash
# Alle Services mit Logs starten
docker-compose up
# Services im Hintergrund starten
docker-compose up -d
# Bestimmte Services starten
docker-compose up postgres redis
# Services stoppen
docker-compose stop
# Services stoppen und Container entfernen
docker-compose down
# Services mit Volume-Bereinigung stoppen
docker-compose down -v
# Container-Shell öffnen
docker-compose exec [service-name] /bin/bash
# oder für Alpine-basierte Images:
docker-compose exec [service-name] /bin/sh
# Konfiguration validieren
docker-compose config
# Service-Status anzeigen
docker-compose ps
# Logs aller Services anzeigen
docker-compose logs
# Logs eines bestimmten Services verfolgen
docker-compose logs -f [service-name]
```
## Dokumentation
Weitere Dokumentation finden Sie im `docs`-Verzeichnis:
- API-Dokumentation: `docs/api`
- Architektur: `docs/architecture`
- Entwicklungsrichtlinien: `docs/development`
- Diagramme: `docs/diagrams`
- Betriebsanleitung: `docs/operations`
- Postman-Sammlungen: `docs/postman`
## Lizenz
Siehe [LICENSE](LICENSE) Datei.
## Stand
Letzte Aktualisierung: 22. Juli 2025
Reference in New Issue View Git Blame Copy Permalink