meldestelle/docs/development/getting-started-de.md

Entwicklungsanleitung - Erste Schritte

Überblick

Diese Anleitung hilft neuen Entwicklern beim Einstieg in das Meldestelle-Projekt. Sie deckt alle notwendigen Schritte ab, von der initialen Einrichtung bis zur ersten erfolgreichen Entwicklungsumgebung.

Voraussetzungen

System-Anforderungen

• Betriebssystem: Windows 10+, macOS 10.15+, oder Linux (Ubuntu 20.04+ empfohlen)
• RAM: Mindestens 8GB (16GB empfohlen)
• Speicher: Mindestens 10GB freier Speicherplatz
• Netzwerk: Stabile Internetverbindung für Downloads

Erforderliche Software

1. Java Development Kit (JDK)

# Java 21 installieren (empfohlen: Eclipse Temurin)
# Windows (mit Chocolatey)
choco install temurin21

# macOS (mit Homebrew)
brew install --cask temurin21

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install openjdk-21-jdk

# Verifizierung
java -version
javac -version

2. Docker und Docker Compose

# Docker Desktop installieren (Windows/macOS)
# Herunterladen von: https://www.docker.com/products/docker-desktop

# Linux (Ubuntu)
sudo apt update
sudo apt install docker.io docker-compose
sudo usermod -aG docker $USER

# Verifizierung
docker --version
docker-compose --version

3. Git

# Windows (mit Chocolatey)
choco install git

# macOS (mit Homebrew)
brew install git

# Linux (Ubuntu)
sudo apt install git

# Verifizierung
git --version

4. IDE (Empfohlen: IntelliJ IDEA)

# IntelliJ IDEA Community Edition
# Herunterladen von: https://www.jetbrains.com/idea/download/

# Oder mit Package Manager
# Windows (Chocolatey)
choco install intellijidea-community

# macOS (Homebrew)
brew install --cask intellij-idea-ce

# Linux (Snap)
sudo snap install intellij-idea-community --classic

Projekt-Setup

1. Repository klonen

# Repository klonen
git clone <repository-url>
cd Meldestelle

# Branch-Status prüfen
git status
git branch -a

2. Umgebungsvariablen konfigurieren

# .env-Datei erstellen (falls nicht vorhanden)
cp .env.example .env

# .env-Datei bearbeiten
nano .env  # oder mit bevorzugtem Editor

Wichtige Umgebungsvariablen

# Anwendungskonfiguration
APP_ENVIRONMENT=development
APP_NAME=meldestelle
APP_VERSION=1.0.0

# Datenbank-Konfiguration
DATABASE_URL=jdbc:postgresql://localhost:5432/meldestelle
DATABASE_USERNAME=meldestelle
DATABASE_PASSWORD=password

# Redis-Konfiguration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Keycloak-Konfiguration
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=meldestelle
KEYCLOAK_CLIENT_ID=meldestelle-client

# Kafka-Konfiguration
KAFKA_BOOTSTRAP_SERVERS=localhost:9092
KAFKA_GROUP_ID=meldestelle-group

3. Docker-Infrastruktur starten

# Alle Services starten
docker-compose up -d

# Status überprüfen
docker-compose ps

# Logs anzeigen (optional)
docker-compose logs -f

# Einzelne Services starten (falls gewünscht)
docker-compose up -d postgres redis keycloak

Service-Übersicht

Service	Port	Beschreibung	URL
PostgreSQL	5432	Hauptdatenbank	localhost:5432
Redis	6379	Cache & Event Store	localhost:6379
Keycloak	8080	Authentifizierung	http://localhost:8080
Kafka	9092	Messaging	localhost:9092
Zookeeper	2181	Kafka Koordination	localhost:2181
Zipkin	9411	Distributed Tracing	http://localhost:9411
Prometheus	9090	Metriken	http://localhost:9090
Grafana	3000	Dashboards	http://localhost:3000

4. Umgebung validieren

# Validierungsskript ausführen
./validate-env.sh

# Oder manuell prüfen
docker-compose ps
curl http://localhost:8080/auth/realms/meldestelle

IDE-Konfiguration

IntelliJ IDEA Setup

1. Projekt öffnen

1. IntelliJ IDEA starten
2. "Open" wählen
3. Meldestelle-Projektverzeichnis auswählen
4. "Open as Project" bestätigen

2. Kotlin-Plugin aktivieren

1. File → Settings (Ctrl+Alt+S)
2. Plugins → Marketplace
3. "Kotlin" suchen und installieren
4. IDE neu starten

3. Gradle-Konfiguration

1. File → Settings → Build → Gradle
2. "Use Gradle from" → "gradle-wrapper.properties file"
3. "Gradle JVM" → Java 21 auswählen
4. "Apply" und "OK"

4. Code-Style konfigurieren

1. File → Settings → Editor → Code Style
2. Scheme → "Project" auswählen
3. Kotlin → Tabs and Indents:
   • Tab size: 4
   • Indent: 4
   • Continuation indent: 8

5. Nützliche Plugins installieren

• Docker: Docker-Integration
• Database Tools: Datenbankzugriff
• GitToolBox: Erweiterte Git-Features
• Rainbow Brackets: Bessere Klammer-Visualisierung
• String Manipulation: Text-Utilities

VS Code Setup (Alternative)

1. Erforderliche Extensions

# Extension Pack for Java
code --install-extension vscjava.vscode-java-pack

# Kotlin Language
code --install-extension fwcd.kotlin

# Docker
code --install-extension ms-azuretools.vscode-docker

# GitLens
code --install-extension eamodio.gitlens

2. Workspace-Konfiguration

{
    "java.home": "/path/to/java-21",
    "java.configuration.updateBuildConfiguration": "automatic",
    "kotlin.languageServer.enabled": true,
    "docker.showStartPage": false
}

Erstellen Sie diese Datei als .vscode/settings.json im Projektverzeichnis.

Projekt-Architektur verstehen

Modulare Struktur

Meldestelle/
├── core/                    # Shared Kernel
│   ├── core-domain/        # Gemeinsame Domain-Modelle
│   └── core-utils/         # Utilities und Konfiguration
├── members/                 # Mitgliederverwaltung
│   ├── members-domain/     # Domain Layer
│   ├── members-application/ # Application Layer
│   ├── members-infrastructure/ # Infrastructure Layer
│   ├── members-api/        # API Layer
│   └── members-service/    # Service Layer
├── horses/                  # Pferderegistrierung
├── events/                  # Veranstaltungsverwaltung
├── masterdata/             # Stammdatenverwaltung
├── infrastructure/         # Infrastruktur-Services
├── client/                 # Client-Anwendungen
└── docs/                   # Dokumentation

Clean Architecture Prinzipien

1. Domain Layer: Geschäftslogik und Entitäten
2. Application Layer: Use Cases und Orchestrierung
3. Infrastructure Layer: Datenbankzugriff und externe Services
4. API Layer: REST-Controller und DTOs
5. Service Layer: Spring Boot Anwendungen

Technologie-Stack

• Backend: Kotlin + Spring Boot
• Datenbank: PostgreSQL + Exposed ORM
• Caching: Redis
• Messaging: Apache Kafka
• Authentifizierung: Keycloak + JWT
• Monitoring: Prometheus + Grafana
• Tracing: Zipkin
• Frontend: Jetpack Compose (Desktop/Web)
• Build: Gradle mit Kotlin DSL

Erste Entwicklungsschritte

1. Projekt kompilieren

# Vollständigen Build ausführen
./gradlew build

# Nur kompilieren (ohne Tests)
./gradlew compileKotlin

# Spezifisches Modul kompilieren
./gradlew :members:members-service:build

2. Tests ausführen

# Alle Tests
./gradlew test

# Modul-spezifische Tests
./gradlew :members:test

# Integration Tests
./gradlew integrationTest

# Test-Reports anzeigen
open build/reports/tests/test/index.html

3. Services starten

# Einzelnen Service starten
./gradlew :members:members-service:bootRun

# Mit spezifischem Profil
./gradlew :members:members-service:bootRun --args='--spring.profiles.active=dev'

# API Gateway starten
./gradlew :infrastructure:gateway:bootRun

4. Datenbank-Migrationen

# Flyway-Migrationen ausführen
./gradlew flywayMigrate

# Migration-Status prüfen
./gradlew flywayInfo

# Datenbank zurücksetzen (Vorsicht!)
./gradlew flywayClean

Entwicklungsworkflows

Feature-Entwicklung

1. Feature Branch erstellen

# Neuen Feature Branch erstellen
git checkout -b feature/neue-funktion

# Branch auf Remote pushen
git push -u origin feature/neue-funktion

2. Code-Änderungen

# Änderungen committen
git add .
git commit -m "feat: neue Funktion implementiert"

# Code-Style prüfen
./gradlew ktlintCheck

# Code formatieren
./gradlew ktlintFormat

3. Tests und Qualitätssicherung

# Tests ausführen
./gradlew test

# Code-Coverage prüfen
./gradlew jacocoTestReport
open build/reports/jacoco/test/html/index.html

# Statische Code-Analyse
./gradlew detekt

4. Pull Request erstellen

1. Änderungen auf Remote Branch pushen
2. Pull Request im Repository erstellen
3. Code Review abwarten
4. Nach Approval mergen

Debugging

1. Service-Debugging

# Service mit Debug-Port starten
./gradlew :members:members-service:bootRun --debug-jvm

# Oder mit spezifischem Port
./gradlew :members:members-service:bootRun -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"

2. IntelliJ Remote Debugging

1. Run → Edit Configurations
2. "+" → Remote JVM Debug
3. Port: 5005 (oder gewählter Port)
4. Debug-Session starten

3. Logs analysieren

# Service-Logs anzeigen
docker-compose logs -f members-service

# Alle Logs
docker-compose logs -f

# Spezifische Log-Level
export LOGGING_LEVEL_ROOT=DEBUG
./gradlew :members:members-service:bootRun

API-Testing

1. Swagger UI verwenden

# Service starten
./gradlew :members:members-service:bootRun

# Swagger UI öffnen
open http://localhost:8082/swagger-ui.html

2. cURL-Beispiele

# Alle Mitglieder abrufen
curl -H "Authorization: Bearer <token>" \
     http://localhost:8082/api/members

# Neues Mitglied erstellen
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>" \
     -d '{"firstName":"Max","lastName":"Mustermann","email":"max@example.com","membershipNumber":"M2024001","membershipStartDate":"2024-01-01"}' \
     http://localhost:8082/api/members

3. Postman Collections

# Postman Collections importieren
# Dateien in docs/postman/ verwenden

Häufige Probleme und Lösungen

Docker-Probleme

Services starten nicht

# Ports prüfen
netstat -tulpn | grep :5432

# Docker-Logs prüfen
docker-compose logs postgres

# Services neu starten
docker-compose down
docker-compose up -d

Speicherplatz-Probleme

# Nicht verwendete Images entfernen
docker system prune -a

# Volumes aufräumen
docker volume prune

Build-Probleme

Gradle-Cache-Probleme

# Gradle-Cache löschen
./gradlew clean
rm -rf ~/.gradle/caches

# Dependencies neu laden
./gradlew build --refresh-dependencies

Kotlin-Compiler-Probleme

# Kotlin-Daemon stoppen
./gradlew --stop

# Build-Verzeichnis löschen
./gradlew clean

# Neu kompilieren
./gradlew build

Datenbank-Probleme

Verbindungsfehler

# PostgreSQL-Status prüfen
docker-compose ps postgres

# Datenbank-Logs prüfen
docker-compose logs postgres

# Verbindung testen
psql -h localhost -p 5432 -U meldestelle -d meldestelle

Migration-Fehler

# Migration-Status prüfen
./gradlew flywayInfo

# Fehlgeschlagene Migration reparieren
./gradlew flywayRepair

# Datenbank zurücksetzen (Entwicklung)
docker-compose down -v
docker-compose up -d postgres
./gradlew flywayMigrate

Nützliche Befehle

Gradle-Tasks

# Alle verfügbaren Tasks anzeigen
./gradlew tasks

# Abhängigkeiten anzeigen
./gradlew dependencies

# Projekt-Informationen
./gradlew projects

# Build-Scan erstellen
./gradlew build --scan

Docker-Befehle

# Container-Status
docker-compose ps

# Logs verfolgen
docker-compose logs -f [service-name]

# Container neu starten
docker-compose restart [service-name]

# In Container einloggen
docker-compose exec postgres psql -U meldestelle

Git-Workflows

# Aktuellen Status prüfen
git status

# Änderungen stagen
git add .

# Commit mit konventioneller Nachricht
git commit -m "feat(members): neue Validierung hinzugefügt"

# Branch wechseln
git checkout main
git pull origin main

Weiterführende Ressourcen

Dokumentation

• API-Dokumentation
• Architektur-Dokumentation
• Deployment-Anleitung

Externe Ressourcen

• Kotlin-Dokumentation
• Spring Boot-Dokumentation
• Docker-Dokumentation
• PostgreSQL-Dokumentation

Community und Support

• Issue Tracker: GitHub Issues
• Diskussionen: GitHub Discussions
• Code Reviews: Pull Requests
• Dokumentation: Wiki

Nächste Schritte

Nach erfolgreichem Setup:

1. Code-Basis erkunden: Beginnen Sie mit dem members-Modul
2. Tests ausführen: Verstehen Sie die Test-Struktur
3. Erste Änderung: Implementieren Sie eine kleine Verbesserung
4. Code Review: Erstellen Sie einen Pull Request
5. Dokumentation: Erweitern Sie die Dokumentation

---

Letzte Aktualisierung: 25. Juli 2025 Version: 1.0 Zielgruppe: Neue Entwickler

Bei Fragen oder Problemen erstellen Sie bitte ein Issue im Repository oder wenden Sie sich an das Entwicklungsteam.