mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Fix: Test-Commit für VCS-Integration (MP-8) (#15)

Browse Source 
* MP-8 OTHER Implementiere JWT-Authentifizierungs-Filter im Gateway

* Fix(ci): Update upload-artifact action to v4

* Fix(ci): Add start command for Keycloak and failure logs

* Fix(ci): Remove invalid 'command' property from Keycloak service

* Fix(ci): Use KC_DEV_MODE env var to start Keycloak

* Fix(ci): Keycloak service was removed from GitHub Actions services and replaced with a manual docker run step that starts Keycloak with the start-dev command.

* dev(ci): vereinheitliche Keycloak auf 26.4.2; aktiviere Health im CI (MP-8)

* Fix(ci): Stabilize Keycloak startup in integration tests via matrix

- Add `dev-file` Keycloak variant to matrix for stability fallback.
- Improve wait logic and health checks for Keycloak and Postgres.
- Unify Keycloak version to 26.4.2 across codebase.
- Add log dumps on failure.

* Fix(ci): Die betroffene Datei docs/Visionen-Ideen/Infrastruktur-Strategie_DSGVO-Konformität.md endet aktuell mit genau einer leeren Zeile (Zeile 87). Das entspricht der Regel MD047 („Files should end with a single newline character“). Damit ist deine Korrektur korrekt.

* Fix(ci): Repository-wide auto-fix for Markdown files was implemented with a GitHub Actions workflow and a local helper script. EditorConfig and markdownlint ignore files were added to ensure consistent formatting. Instructions for using the auto-fix both via GitHub Actions and locally were provided.

* fix(gradle): build.gradle.kts jsBrowser testTask disabled

* fix(gradle): build.gradle.kts jsBrowser testTask disabled

* Fix(ci): Stabilize integration tests with Keycloak matrix build (MP-8)

Introduces a matrix strategy (`keycloak_db: [postgres, dev-file]`)
in the integration-tests workflow to mitigate flaky Keycloak starts
when using the Postgres service container.

- Adds a `dev-file` Keycloak variant for stability fallback.
- Improves wait logic and health checks for Keycloak/Postgres.
- Unifies Keycloak version to 26.4.2 across codebase (Dockerfile, Compose,
  ADR, README, tests).
- Adds log dumps on failure in CI.
- Ensures `KC_HEALTH_ENABLED=true` is set.
- Updates related documentation (README, Schlachtplan).
- Includes broader Docker SSoT cleanup (versions.toml as source,
  script updates, env file cleanup, validator hardening).

This resolves recurring CI failures related to Keycloak startup and
ensures required checks for PRs (#15) are reliable, while also
improving overall Docker build consistency.

* feat(docs, ci): Implement YouTrack SSoT strategy with Dokka sync (MP-8)

- Add Dokka multi-module Gradle configuration and KDoc style guide.
- Add GitHub Actions workflow (docs-kdoc-sync.yml) and Python script
  (youtrack-sync-kb.py) to sync Dokka GFM output to YouTrack KB.
- Extend front-matter schema (bc, doc_type) and update relevant pages/stubs.
- Adapt CI scripts (validate-frontmatter, check-docs-drift, ci-docs link ignore).
- Update README.md to reference YouTrack KB.

* feat(docs, ci): Implement YouTrack SSoT strategy with Dokka sync (MP-8)

- Add Dokka multi-module Gradle configuration and KDoc style guide.
- Add GitHub Actions workflow (docs-kdoc-sync.yml) and Python script
  (youtrack-sync-kb.py) to sync Dokka GFM output to YouTrack KB.
- Extend front-matter schema (bc, doc_type) and update relevant pages/stubs.
- Adapt CI scripts (validate-frontmatter, check-docs-drift, ci-docs link ignore).
- Update README.md to reference YouTrack KB.

* Fix(ci): Replace OpenAPI validator with Spectral

Replaces the deprecated 'char0n/swagger-editor-validate' action,
which failed due to sandbox issues in GitHub Actions, with the
modern '@stoplight/spectral-cli'.

This ensures robust OpenAPI specification validation without
requiring a headless browser environment. The 'generate-api-docs'
job now depends on the successful completion of the Spectral validation.

Part of resolving CI failures for PR #15 (MP-8).

* Fix(ci): Specify spectral:oas ruleset for OpenAPI validation (MP-8)

* Fix(ci): Remove explicit ruleset argument for Spectral validation (MP-8)

* Fix(ci): Added a .spectral.yaml file to fix Spectral linting errors. Corrected markdown lint issues in two documentation files. Updated README.md with a new guidelines section to fix link validation errors.

* Fix(ci): Markdownlint errors were fixed by adding required blank lines. The Guidelines Validation error was resolved by updating the README.md link. The API Documentation Generator workflow was stabilized by updating paths, tasks, and validation steps.

* Fix(ci): Alle vier fehlerhaften GitHub-Action-Prüfungen wurden behoben. Fehler in der OpenAPI-Spezifikation, Probleme mit der Markdown-Linting-Analyse und Validierungsfehler bei Querverweisen wurden korrigiert. Die README.md enthält nun alle erforderlichen Links zu den Richtlinien.

* Fix(ci): Markdown linting errors in docs/api/README.md were fixed by specifying languages in fenced code blocks. OpenAPI specification errors in documentation.yaml were resolved by correcting example property types to strings. Cross-reference validation errors in README.md were fixed by adding the missing link to project-standards/coding-standards.md.

* Fix(ci): Duplicate heading errors in docs/api/members-api.md were fixed. Cross-reference validation errors for docker-architecture.md were resolved. All originally reported issues passed validation successfully.

* Fix(ci): The markdown heading levels in docs/api/members-api.md were corrected from h5 to h4 to fix linting errors. The missing cross-reference link from technology-guides/docker/docker-development.md to docker-overview.md was added. These fixes resolved the original validation and linting errors causing the process to fail.

* Fix(ci): Duplicate heading warnings in docs/api/members-api.md were resolved. Cross-reference validation for docker-development.md to docker-architecture.md was fixed. A new unrelated warning about docker-production.md was identified but not addressed.

* refactor(ci,docs): Simplify CI pipeline and migrate docs to YouTrack SSoT

BREAKING CHANGE: Documentation structure radically simplified

- Consolidate 9 GitHub Actions workflows into 1 main pipeline (ci-main.yml)
- Remove redundant workflows: ci-docs, markdownlint-autofix, guidelines-validation, api-docs
- Delete documentation migrated to YouTrack: api/, BCs/, Visionen-Ideen/, reference/, now/, overview/
- Keep only ADRs, C4 diagrams, and essential dev guides in repo
- Update README.md with YouTrack KB links
- Create new docs/README.md as documentation gateway
- Relax markdown-lint config for pragmatic developer experience

Kept workflows:
- ssot-guard.yml (Docker SSoT validation)
- docs-kdoc-sync.yml (KDoc → YouTrack sync)
- integration-tests.yml (Integration tests)
- deploy-proxmox.yml (Deployment)
- youtrack-sync.yml (YouTrack integration)

Related: MP-DOCS-001

* refactor(ci,docs): Simplify CI pipeline and migrate docs to YouTrack SSoT

BREAKING CHANGE: Documentation structure radically simplified

- Consolidate 9 GitHub Actions workflows into 1 main pipeline (ci-main.yml)
- Remove redundant workflows: ci-docs, markdownlint-autofix, guidelines-validation, api-docs
- Delete documentation migrated to YouTrack: api/, BCs/, Visionen-Ideen/, reference/, now/, overview/
- Keep only ADRs, C4 diagrams, and essential dev guides in repo
- Update README.md with YouTrack KB links
- Create new docs/README.md as documentation gateway
- Relax markdown-lint config for pragmatic developer experience

Kept workflows:
- ssot-guard.yml (Docker SSoT validation)
- docs-kdoc-sync.yml (KDoc → YouTrack sync)
- integration-tests.yml (Integration tests)
- deploy-proxmox.yml (Deployment)
- youtrack-sync.yml (YouTrack integration)

Related: MP-DOCS-001

* refactor(ci,docs): README.md und einige andere Dokumentationen überarbeitet.
ports-and-urls.md hinzugefügt.
Related: MP-DOCS-001

* refactor(ci,docs): Die Markdownlint-Fehler in README.md und docs/README.md wurden behoben, indem die Überschriftenebenen angepasst, überflüssige Satzzeichen am Ende entfernt und die notwendigen Leerzeilen um Überschriften, Listen, Tabellen und Codeblöcke eingefügt wurden. Das problematische Leerzeichen am Ende in docs/README.md wurde ebenfalls entfernt. Die Dateien entsprechen nun den vorgegebenen Markdownlint-Regeln und sollten die CI-Validierung bestehen.
Related: MP-DOCS-001

* refactor(ci,docs): Docker guideline cross-references were fixed and normalized to lowercase labels. Validation scripts confirmed zero cross-reference warnings and consistent metadata. Documentation was updated with a changelog and enhanced README navigation.
Related: MP-DOCS-001

* refactor(ci,docs): Docker guideline cross-references were fixed and normalized to lowercase labels. Validation scripts confirmed zero cross-reference warnings and consistent metadata. Documentation was updated with a changelog and enhanced README navigation.
Related: MP-DOCS-001

* refactor(ci,docs): Dead links in docs/architecture/adr were fixed by updating URLs to stable sources and adding an ignore pattern for a placeholder link. Specific ADR files had their broken links replaced with valid ones. The markdown-link-check GitHub Action is expected to pass with zero dead links now.
Related: MP-DOCS-001

* refactor(ci,docs): Links in ADR checked
Related: MP-DOCS-001

* refactor(ci,docs): Links in ADR checked
Related: MP-DOCS-001

* refactor(ci,docs): Markdown Regeln ausgebessert
Related: MP-DOCS-001

* refactor(ci,docs): Markdown Regeln ausgebessert
Related: MP-DOCS-001

* refactor(ci,docs): Markdown Regeln ausgebessert
Related: MP-DOCS-001

* Chore: Rerun CI checks with updated branch protection rules
This commit is contained in:
StefanMo
2025-11-07 12:26:33 +01:00
committed by GitHub
parent 6850cd92d4
commit b35c4087a2
129 changed files with 4016 additions and 7131 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.junie/guidelines/README.md
+45 -33
View File
@@ -20,33 +20,38 @@ This directory contains the comprehensive development guidelines for the Meldest
## 🗂️ Guidelines Structure
### 📊 Master Guideline
- **[Master-Guideline](./master-guideline.md)** - Central project guidelines and architectural foundations
- **[Master-Guideline](master-guideline.md)** - Central project guidelines and architectural foundations
### 🏗️ Project Standards
Core development standards and quality requirements:
| Guideline | Scope | AI Context |
|-----------|-------|------------|
| [Coding Standards](./project-standards/coding-standards.md) | Code quality, naming conventions, patterns | Kotlin standards, Result pattern, value classes |
| [Testing Standards](./project-standards/testing-standards.md) | Test strategies, tools, coverage | Test pyramid, Testcontainers, debugging |
| [Documentation Standards](./project-standards/documentation-standards.md) | Documentation language, structure, API docs | German language rules, README templates |
| [Architecture Principles](./project-standards/architecture-principles.md) | Microservices, DDD, EDA, KMP | Clean Architecture, bounded contexts, MVVM |
| Guideline | Scope | AI Context |
|---------------------------------------------------------------------------|---------------------------------------------|-------------------------------------------------|
| [Coding Standards](./project-standards/coding-standards.md) | Code quality, naming conventions, patterns | Kotlin standards, Result pattern, value classes |
| [Testing Standards](./project-standards/testing-standards.md) | Test strategies, tools, coverage | Test pyramid, Testcontainers, debugging |
| [Documentation Standards](./project-standards/documentation-standards.md) | Documentation language, structure, API docs | German language rules, README templates |
| [Architecture Principles](./project-standards/architecture-principles.md) | Microservices, DDD, EDA, KMP | Clean Architecture, bounded contexts, MVVM |
### 🔧 Technology Guides
Technology-specific implementation guidelines:
#### Web Applications
- **[Web App Guideline](./technology-guides/web-app-guideline.md)** - Compose Multiplatform development for desktop and web clients
#### Docker & Infrastructure
| Docker Module | Focus Area | AI Context |
|---------------|------------|------------|
| [Docker Overview](./technology-guides/docker/docker-overview.md) | Philosophy and principles | Container strategy, security-first approach |
| [Docker Architecture](./technology-guides/docker/docker-architecture.md) | Services and version management | Service categories, centralized versions |
| [Docker Development](./technology-guides/docker/docker-development.md) | Development workflow | Makefile commands, debugging, hot-reload |
| [Docker Production](./technology-guides/docker/docker-production.md) | Production deployment | Security hardening, SSL/TLS, monitoring |
| [Docker Monitoring](./technology-guides/docker/docker-monitoring.md) | Observability setup | Prometheus, Grafana, health checks |
| [Docker Troubleshooting](./technology-guides/docker/docker-troubleshooting.md) | Problem resolution | Common issues, best practices, workflows |
| Docker Module | Focus Area | AI Context |
|--------------------------------------------------------------------------------|---------------------------------|---------------------------------------------|
| [Docker Overview](./technology-guides/docker/docker-overview.md) | Philosophy and principles | Container strategy, security-first approach |
| [Docker Architecture](./technology-guides/docker/docker-architecture.md) | Services and version management | Service categories, centralized versions |
| [Docker Development](./technology-guides/docker/docker-development.md) | Development workflow | Makefile commands, debugging, hot-reload |
| [Docker Production](./technology-guides/docker/docker-production.md) | Production deployment | Security hardening, SSL/TLS, monitoring |
| [Docker Monitoring](./technology-guides/docker/docker-monitoring.md) | Observability setup | Prometheus, Grafana, health checks |
| [Docker Troubleshooting](./technology-guides/docker/docker-troubleshooting.md) | Problem resolution | Common issues, best practices, workflows |
### 🔄 Process Guides
Development process and workflow guidelines:
@@ -57,16 +62,16 @@ Development process and workflow guidelines:
### Common Development Tasks
| Task | Primary Guidelines | Supporting Guidelines |
|------|-------------------|----------------------|
| **New Feature Development** | Architecture Principles, Coding Standards | Testing Standards, Docker Development |
| **Frontend Development** | Web App Guideline | Architecture Principles, Coding Standards |
| **Backend Service Creation** | Architecture Principles, Coding Standards | Docker Development, Testing Standards |
| **Infrastructure Setup** | Docker Architecture, Docker Development | Docker Overview, Docker Monitoring |
| **Production Deployment** | Docker Production | Docker Architecture, Docker Monitoring |
| **Testing Implementation** | Testing Standards | Coding Standards, Docker Development |
| **Documentation Writing** | Documentation Standards | All related technical guidelines |
| **Troubleshooting Issues** | Docker Troubleshooting | Docker Development, Docker Monitoring |
| Task | Primary Guidelines | Supporting Guidelines |
|------------------------------|-------------------------------------------|-------------------------------------------|
| **New Feature Development** | Architecture Principles, Coding Standards | Testing Standards, Docker Development |
| **Frontend Development** | Web App Guideline | Architecture Principles, Coding Standards |
| **Backend Service Creation** | Architecture Principles, Coding Standards | Docker Development, Testing Standards |
| **Infrastructure Setup** | Docker Architecture, Docker Development | Docker Overview, Docker Monitoring |
| **Production Deployment** | Docker Production | Docker Architecture, Docker Monitoring |
| **Testing Implementation** | Testing Standards | Coding Standards, Docker Development |
| **Documentation Writing** | Documentation Standards | All related technical guidelines |
| **Troubleshooting Issues** | Docker Troubleshooting | Docker Development, Docker Monitoring |
### Key Architectural Decisions
@@ -78,29 +83,32 @@ Development process and workflow guidelines:
### Technology Stack Quick Reference
| Layer | Technologies | Guidelines |
|-------|-------------|------------|
| **Frontend** | Kotlin Multiplatform, Compose Multiplatform | Web App Guideline |
| **Backend** | Spring Boot, Kotlin, Clean Architecture | Architecture Principles, Coding Standards |
| **Infrastructure** | Docker, PostgreSQL, Redis, Kafka, Consul | Docker Guides |
| **Monitoring** | Prometheus, Grafana, Zipkin | Docker Monitoring |
| **Testing** | JUnit 5, MockK, Testcontainers | Testing Standards |
| Layer | Technologies | Guidelines |
|--------------------|---------------------------------------------|-------------------------------------------|
| **Frontend** | Kotlin Multiplatform, Compose Multiplatform | Web App Guideline |
| **Backend** | Spring Boot, Kotlin, Clean Architecture | Architecture Principles, Coding Standards |
| **Infrastructure** | Docker, PostgreSQL, Redis, Kafka, Consul | Docker Guides |
| **Monitoring** | Prometheus, Grafana, Zipkin | Docker Monitoring |
| **Testing** | JUnit 5, MockK, Testcontainers | Testing Standards |
## 🚀 Getting Started
### For Developers
1. Start with [Master-Guideline](./master-guideline.md) for project overview
2. Review [Architecture Principles](./project-standards/architecture-principles.md) for architectural foundations
3. Follow [Coding Standards](./project-standards/coding-standards.md) for development practices
4. Use [Docker Development](./technology-guides/docker/docker-development.md) for local setup
### For AI Assistants
1. Each guideline includes structured metadata and AI context
2. Use the `ai_context` field for understanding guideline scope
3. Cross-reference related guidelines through navigation sections
4. Leverage quick reference tables for rapid information access
### For Project Managers
1. [Trace Bullet Guideline](./process-guides/trace-bullet-guideline.md) for current development cycle
2. [Master-Guideline](./master-guideline.md) for project standards overview
3. Individual guidelines for specific team coordination
@@ -110,12 +118,14 @@ Development process and workflow guidelines:
Das Guidelines-System verfügt über umfassende Automatisierungsfeatures:
### 🔗 Automatische Validierung
- **Link-Validierung:** `.junie/scripts/validate-links.sh` - Cross-Referenzen und YAML-Konsistenz
- **Template-System:** `.junie/scripts/create-guideline.sh` - Automatische Guideline-Erstellung
- **Pre-commit Hook:** `.junie/scripts/pre-commit-guidelines.sh` - Lokale Validierung vor Commits
- **CI/CD-Integration:** `.github/workflows/guidelines-validation.yml` - Automatische Pipeline-Validierung
- **CI/CD-Integration (optional):** `.github/workflows/ci-main.yml` (Job: `validate-docs`) - Markdown-Lint und Link-Check für kritische Docs
### 📋 Verfügbare Templates
- **Project-Standards:** `project-standard-template.md`
- **Technology-Guides:** `technology-guideline-template.md`
- **Process-Guides:** `process-guide-template.md`
@@ -141,12 +151,14 @@ ai_context: "Brief description for AI understanding"
## 🔍 Guidelines Maintenance
### Update Process
1. **Content Changes** → Update specific guideline file
2. **Structural Changes** → Update README.md navigation
3. **New Guidelines** → Add to appropriate category and update index
4. **Deprecated Guidelines** → Archive and update references
### Quality Assurance
- All guidelines include AI-optimized metadata
- Cross-references are maintained and validated
- Navigation links are consistent across guidelines
.junie/guidelines/_archived/docker-guideline-v3.0.1-archived-2025-09-15.md
+110 -69
View File
@@ -46,7 +46,7 @@ Das Meldestelle-Projekt implementiert eine **moderne, sicherheitsorientierte Con
```mermaid
graph TB
subgraph "Infrastructure Services"
PG[PostgreSQL]
PG[PostgresQL]
RD[Redis]
KC[Keycloak]
KF[Kafka+Zookeeper]
@@ -80,20 +80,20 @@ graph TB
### Service-Ports Matrix
| Service | Development | Production | Health Check | Debug Port | Version |
|---------|------------|------------|--------------|------------|---------|
| PostgreSQL | 5432 | Internal | pg_isready -U meldestelle -d meldestelle | - | 16-alpine |
| Redis | 6379 | Internal | redis-cli ping | - | 7-alpine |
| Keycloak | 8180 | 8443 (HTTPS) | /health/ready | - | 26.0.7 |
| Kafka | 9092 | Internal | kafka-topics --bootstrap-server localhost:9092 --list | - | 7.4.0 |
| Zookeeper | 2181 | Internal | nc -z localhost 2181 | - | 7.4.0 |
| Consul | 8500 | Internal | /v1/status/leader | - | 1.15 |
| Auth Server | 8081 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Ping Service | 8082 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Monitoring Server | 8083 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Prometheus | 9090 | Internal | /-/healthy | - | v2.54.1 |
| Grafana | 3000 | 3443 (HTTPS) | /api/health | - | 11.3.0 |
| Nginx | - | 80/443 | /health | - | 1.25-alpine |
| Service | Development | Production | Health Check | Debug Port | Version |
|-------------------|-------------|--------------|-------------------------------------------------------|------------|-------------|
| PostgresQL | 5432 | Internal | pg_isready -U meldestelle -d meldestelle | - | 16-alpine |
| Redis | 6379 | Internal | redis-cli ping | - | 7-alpine |
| Keycloak | 8180 | 8443 (HTTPS) | /health/ready | - | 26.0.7 |
| Kafka | 9092 | Internal | kafka-topics --bootstrap-server localhost:9092 --list | - | 7.4.0 |
| Zookeeper | 2181 | Internal | nc -z localhost 2181 | - | 7.4.0 |
| Consul | 8500 | Internal | /v1/status/leader | - | 1.15 |
| Auth Server | 8081 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Ping Service | 8082 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Monitoring Server | 8083 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Prometheus | 9090 | Internal | /-/healthy | - | v2.54.1 |
| Grafana | 3000 | 3443 (HTTPS) | /api/health | - | 11.3.0 |
| Nginx | - | 80/443 | /health | - | 1.25-alpine |
---
@@ -135,7 +135,7 @@ clients = "dev"
### 🏗️ Architektur der zentralen Konfigurationsverwaltung
```
```plaintext
config/
├── central.toml # 🎯 ABSOLUTE SINGLE SOURCE OF TRUTH
├── README.md # Dokumentation
@@ -155,7 +155,8 @@ scripts/
### 📊 Konfigurationsbereiche
#### 1. **Port-Management** - Eliminiert 38+ Redundanzen
#### 1. **Port-Management** – eliminiert 38+ Redundanzen
```toml
[ports]
# --- Infrastructure Services ---
@@ -178,7 +179,8 @@ prometheus = 9090
grafana = 3000
```
#### 2. **Spring-Profile-Management** - Eliminiert 72+ Duplikate
#### 2. **Spring-Profile-Management** – eliminiert 72+ Duplikate
```toml
[spring-profiles]
default = "default"
@@ -194,6 +196,7 @@ clients = "dev"
```
#### 3. **Service-Discovery** - Standardisiert URLs
```toml
[services.ping-service]
name = "ping-service"
@@ -207,6 +210,7 @@ metrics-endpoint = "/actuator/prometheus"
```
#### 4. **Health-Check-Standardisierung**
```toml
[health-checks.defaults]
interval = "15s"
@@ -242,7 +246,7 @@ start-period = "20s"
./scripts/config-sync.sh validate
```
#### Ports ändern - Ein Befehl, überall aktualisiert
#### Ports ändern – ein Befehl, überall aktualisiert
```bash
# 1. config/central.toml bearbeiten
@@ -261,7 +265,7 @@ ping-service = 8092 # Geändert von 8082
# ✓ Und 33 weitere Dateien automatisch!
```
#### Spring-Profile ändern - Konsistenz garantiert
#### Spring-Profile ändern – Konsistenz garantiert
```bash
# 1. Zentral in config/central.toml ändern
@@ -281,6 +285,7 @@ services = "production" # Geändert von "docker"
### 🔄 Entwickler-Workflow mit zentraler Konfiguration
#### **Neuen Service hinzufügen**
```bash
# 1. Port in central.toml definieren
[ports]
@@ -298,6 +303,7 @@ port = 8090
```
#### **Umgebung wechseln**
```bash
# Development → Production Profile-Wechsel
# 1. config/central.toml anpassen
@@ -311,6 +317,7 @@ services = "prod"
```
#### **Monitoring hinzufügen**
```bash
# Neuer Service automatisch in Prometheus überwacht:
# 1. Service in central.toml definieren
@@ -320,23 +327,27 @@ services = "prod"
### 🎉 Vorteile der zentralen Konfigurationsverwaltung
#### **DRY-Prinzip auf Projekt-Ebene** ✅
#### **DRY-Prinzip auf Projekt-Ebene**
✅
- **Vor Version 4.0.0**: Port 8082 in 38 Dateien
- **Ab Version 4.0.0**: Port einmalig in `config/central.toml`
#### **Wartungsaufwand drastisch reduziert** ✅
#### **Wartungsaufwand drastisch reduziert**
✅
```bash
# BEFORE: 38 Dateien manuell editieren für Port-Änderung
# AFTER: Ein Befehl für alle Dateien
./scripts/config-sync.sh sync
```
#### **Konsistenz absolut garantiert** ✅
#### **Konsistenz absolut garantiert**
✅
- Keine Port-Konflikte mehr möglich
- Keine inkonsistenten Spring-Profile
- Automatische Validierung bei Synchronisation
#### **Skalierbarkeit für neue Services** ✅
```bash
# Neuer Service: Einmal definieren, überall verfügbar
[ports]
@@ -351,6 +362,7 @@ future-service = 8099
```
#### **Fehlerreduktion** ✅
- Keine Tippfehler bei Port-Definitionen
- Keine vergessenen Aktualisierungen
- Automatische Backup-Erstellung vor Änderungen
@@ -359,6 +371,7 @@ future-service = 8099
### 📚 Best Practices für zentrale Konfigurationsverwaltung
#### **DO: Zentrale Konfiguration verwenden**
```bash
# ✅ RICHTIG - Zentrale Konfiguration
./scripts/config-sync.sh sync
@@ -371,6 +384,7 @@ future-service = 8099
```
#### **DON'T: Manuelle Datei-Bearbeitung**
```bash
# ❌ FALSCH - Nie mehr manuelle Port-Änderungen
vim docker-compose.yml # Änderungen gehen verloren!
@@ -381,6 +395,7 @@ vim config/central.toml
```
#### **Konsistenz-Regeln**
1. **Niemals** Ports direkt in abhängigen Dateien ändern
2. **Immer** `config/central.toml` als Single Source of Truth verwenden
3. **Automatisch** mit `config-sync.sh` synchronisieren
@@ -390,6 +405,7 @@ vim config/central.toml
### 🔧 Erweiterte Funktionen
#### **Selective Synchronisation**
```bash
# Nur bestimmte Bereiche synchronisieren
./scripts/config-sync.sh gradle # Nur gradle.properties
@@ -400,6 +416,7 @@ vim config/central.toml
```
#### **Backup und Rollback**
```bash
# Alle Backups anzeigen
ls -la *.bak.*
@@ -409,6 +426,7 @@ cp gradle.properties.bak.20250915_103927 gradle.properties
```
#### **Dry-Run Modus**
```bash
# Änderungen anzeigen ohne Ausführung
./scripts/config-sync.sh sync --dry-run
@@ -417,6 +435,7 @@ cp gradle.properties.bak.20250915_103927 gradle.properties
### 🚀 Integration in CI/CD
#### **Automatische Konsistenz-Checks**
```yaml
# GitHub Actions Pipeline
- name: Validate Configuration Consistency
@@ -426,6 +445,7 @@ cp gradle.properties.bak.20250915_103927 gradle.properties
```
#### **Pre-Commit Hooks**
```bash
# .git/hooks/pre-commit
#!/bin/bash
@@ -434,7 +454,7 @@ cp gradle.properties.bak.20250915_103927 gradle.properties
### 🎯 Migration bestehender Projekte
Die zentrale Konfigurationsverwaltung ist **rückwärtskompatibel** und kann schrittweise eingeführt werden:
Die zentrale Konfigurationsverwaltung ist **rückwärts kompatibel** und kann schrittweise eingeführt werden:
1. **config/central.toml** erstellen
2. **scripts/config-sync.sh** ausführen
@@ -477,7 +497,7 @@ keycloak = "26.0.7"
### 🏗️ Architektur der zentralen Versionsverwaltung
```
```plaintext
docker/
├── versions.toml # 🎯 Single Source of Truth
├── build-args/ # Auto-generierte Environment Files
@@ -491,6 +511,7 @@ docker/
### 📊 Hierarchische Versionsverwaltung
#### 1. **Globale Versionen** (`docker/build-args/global.env`)
Verwendet von **allen** Dockerfiles:
```bash
# --- Build Tools ---
@@ -618,11 +639,13 @@ api-gateway:
### 🎉 Vorteile der zentralen Versionsverwaltung
#### **DRY-Prinzip Durchsetzung** ✅
#### **DRY-Prinzip Durchsetzung**
✅
- **Vor Version 3.0.0**: `GRADLE_VERSION=9.0.0` in 12 Dockerfiles
- **Ab Version 3.0.0**: `gradle = "9.0.0"` **einmalig** in `docker/versions.toml`
#### **Wartungsaufwand drastisch reduziert** ✅
```bash
# BEFORE: 12 Dateien manuell editieren für Gradle-Update
# AFTER: Ein Befehl für alle Services
@@ -630,11 +653,13 @@ api-gateway:
```
#### **Konsistenz garantiert** ✅
- Keine Version-Inkonsistenzen zwischen Services möglich
- Automatische Synchronisation aller Environment-Dateien
- Einheitliche Spring-Profile-Behandlung
#### **Skalierbarkeit für neue Services** ✅
```dockerfile
# Neue Services verwenden automatisch zentrale Versionen
ARG GRADLE_VERSION
@@ -644,18 +669,21 @@ ARG JAVA_VERSION
### 🔄 Migration bestehender Services
#### Schritt 1: Template-basierte Migration
```bash
# Neue Services basieren auf aktualisierten Templates
cp dockerfiles/templates/spring-boot-service.Dockerfile dockerfiles/services/new-service/
```
#### Schritt 2: Automatisierte Version-Synchronisation
```bash
# Bestehende Services automatisch aktualisieren
./scripts/docker-versions-update.sh sync
```
#### Schritt 3: Build-Integration
```bash
# Neue Builds verwenden zentrale Versionen
./scripts/docker-build.sh services
@@ -664,6 +692,7 @@ cp dockerfiles/templates/spring-boot-service.Dockerfile dockerfiles/services/new
### 📚 Best Practices für Version 3.0.0
#### **DO: Zentrale Versionskommandos verwenden**
```bash
# ✅ RICHTIG - Zentrale Version-Updates
./scripts/docker-versions-update.sh update java 22
@@ -673,6 +702,7 @@ cp dockerfiles/templates/spring-boot-service.Dockerfile dockerfiles/services/new
```
#### **DON'T: Manuelle Dockerfile-Bearbeitung**
```dockerfile
# ❌ FALSCH - Nie mehr hardcodierte Versionen
ARG GRADLE_VERSION=9.1.0
@@ -682,6 +712,7 @@ ARG GRADLE_VERSION
```
#### **Konsistenz-Regeln**
1. **Niemals** Versionen direkt in Dockerfiles hardcodieren
2. **Immer** `docker/versions.toml` als Single Source of Truth verwenden
3. **Automated** Environment-File-Synchronisation via Scripts
@@ -690,6 +721,7 @@ ARG GRADLE_VERSION
### 🚀 Entwickler-Workflow mit Version 3.0.0
#### **Neuen Service entwickeln**
```bash
# 1. Template kopieren (bereits Version 3.0.0 kompatibel)
cp dockerfiles/templates/spring-boot-service.Dockerfile dockerfiles/services/my-service/
@@ -700,6 +732,7 @@ cp dockerfiles/templates/spring-boot-service.Dockerfile dockerfiles/services/my-
```
#### **Versionen projekt-weit upgraden**
```bash
# 1. Java-Version upgraden (betrifft ALLE Services)
./scripts/docker-versions-update.sh update java 22
@@ -711,6 +744,7 @@ cp dockerfiles/templates/spring-boot-service.Dockerfile dockerfiles/services/my-
```
#### **Version-Status prüfen**
```bash
# Aktuelle zentrale Versionen anzeigen
./scripts/docker-versions-update.sh show
@@ -782,6 +816,7 @@ ephemeral = "32768-65535"
### ⚡ Automatische Port-Integration
#### Docker-Compose Integration
```yaml
# Ports werden automatisch aus versions.toml gelesen
api-gateway:
@@ -798,6 +833,7 @@ ping-service:
```
#### Script-basierte Port-Validierung
```bash
# scripts/validate-port-conflicts.sh
#!/bin/bash
@@ -874,6 +910,7 @@ test-containers = true
### 🚀 Environment-basierte Deployments
#### Development Environment
```bash
# Development mit Hot-Reload und Debug
export DOCKER_ENVIRONMENT=development
@@ -881,6 +918,7 @@ docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
```
#### Production Environment
```bash
# Production mit Security und Resource-Limits
export DOCKER_ENVIRONMENT=production
@@ -888,6 +926,7 @@ docker-compose -f docker-compose.prod.yml up -d
```
#### Testing Environment
```bash
# Testing mit schnellen Health-Checks
export DOCKER_ENVIRONMENT=testing
@@ -967,6 +1006,7 @@ EOF
### 🎯 Service-Kategorien Templates
#### Services Template
```bash
generate_services_compose() {
local services=($(get_services_from_toml))
@@ -981,6 +1021,7 @@ generate_services_compose() {
```
#### Infrastructure Template
```bash
generate_infrastructure_compose() {
local infrastructure=($(get_infrastructure_from_toml))
@@ -1281,7 +1322,7 @@ jobs:
Alle Dockerfiles folgen einem standardisierten Template-System:
```
```plaintext
dockerfiles/
├── templates/
│ ├── spring-boot-service.Dockerfile # Backend-Services
@@ -1657,7 +1698,7 @@ RUN --mount=type=cache,target=/home/gradle/.gradle/caches \
Unsere Compose-Dateien sind modular organisiert für verschiedene Einsatzszenarien:
```
```plaintext
├── docker-compose.yml # ✅ Development (Infrastructure)
├── docker-compose.prod.yml # ✅ Production (gehärtet, SSL/TLS)
├── docker-compose.services.yml # 🆕 Application Services
@@ -1667,7 +1708,7 @@ Unsere Compose-Dateien sind modular organisiert für verschiedene Einsatzszenari
### Verwendungsszenarien
#### 🏠 Lokale Entwicklung - Vollständiges System
#### 🏠 Lokale Entwicklung - vollständiges System
```bash
# Alle Services einschließlich Clients
@@ -2027,13 +2068,13 @@ labels:
### Health Check Matrix
| Service | Endpoint | Erwartung | Timeout |
|---------|----------|-----------|---------|
| API Gateway | `/actuator/health` | `{"status":"UP"}` | 15s |
| Ping Service | `/actuator/health/readiness` | HTTP 200 | 3s |
| PostgreSQL | `pg_isready` | Connection OK | 5s |
| Redis | `redis-cli ping` | PONG | 5s |
| Keycloak | `/health/ready` | HTTP 200 | 5s |
| Service | Endpoint | Erwartung | Timeout |
|--------------|------------------------------|-------------------|---------|
| API Gateway | `/actuator/health` | `{"status":"UP"}` | 15s |
| Ping Service | `/actuator/health/readiness` | HTTP 200 | 3s |
| PostgresQL | `pg_isready` | Connection OK | 5s |
| Redis | `redis-cli ping` | PONG | 5s |
| Keycloak | `/health/ready` | HTTP 200 | 5s |
### Log Aggregation
@@ -2362,40 +2403,40 @@ brew install ctop # Container-Monitoring-Tool
## 📝 Changelog
| Version | Datum | Änderungen |
|---------|-------|------------|
| 3.2.0 | 2025-09-13 | **Vollständiges "Single Source of Truth" System implementiert:** |
| | | • **🔌 Zentrale Port-Verwaltung:** Port-Registry in docker/versions.toml mit automatischer Konflikt-Erkennung |
| | | • **⚙️ Environment-Overrides Vereinheitlichung:** Zentrale Konfiguration für dev/test/prod Umgebungen |
| | | • **📝 Docker-Compose Template-System:** Automatische Generierung von Compose-Files aus TOML-Konfiguration |
| Version | Datum | Änderungen |
|---------|------------|----------------------------------------------------------------------------------------------------------------------------|
| 3.2.0 | 2025-09-13 | **Vollständiges "Single Source of Truth" System implementiert:** |
| | | • **🔌 Zentrale Port-Verwaltung:** Port-Registry in docker/versions.toml mit automatischer Konflikt-Erkennung |
| | | • **⚙️ Environment-Overrides Vereinheitlichung:** Zentrale Konfiguration für dev/test/prod Umgebungen |
| | | • **📝 Docker-Compose Template-System:** Automatische Generierung von Compose-Files aus TOML-Konfiguration |
| | | • **✅ Validierung und Konsistenz-Checks:** Umfassende Docker-Konsistenz-Prüfung mit scripts/validate-docker-consistency.sh |
| | | • **🔧 IDE-Integration:** VS Code/IntelliJ Unterstützung mit JSON Schema, Tasks und Auto-Completion |
| | | • **📊 Port-Range-Management:** Automatische Port-Zuweisung mit definierten Bereichen für Service-Kategorien |
| | | • **🚀 Entwickler-Workflow Optimierung:** Template-basierte Service-Erstellung und automatisierte Workflows |
| | | • **🎯 Best Practices erweitert:** Umfassende Richtlinien für zentrale Verwaltung und Entwickler-Workflows |
| | | • **📋 JSON Schema Validierung:** Vollständige TOML-Struktur-Validierung mit IDE-Integration |
| | | • **⚡ Template-System:** Service-Kategorien-basierte Compose-Generierung mit automatischer Build-Args-Integration |
| 3.0.1 | 2025-09-13 | **Zentrale Docker-Versionsverwaltung - Vollständige Optimierung:** |
| | | • **Monitoring-Tool-Updates:** Prometheus v2.54.1, Grafana 11.3.0, Keycloak 26.0.7 |
| | | • **Erweiterte Script-Funktionalität:** docker-versions-update.sh unterstützt alle Monitoring-Tools |
| | | • **Automatisierte Version-Synchronisation:** Environment-Dateien mit neuen Monitoring-Versionen |
| | | • **Vollautomatisierte Version-Updates:** Single-Command-Updates für alle Infrastructure-Services |
| | | • **Service-Ports-Matrix erweitert:** Versions-Spalte mit aktuellen Tool-Versionen hinzugefügt |
| | | • **Build-Args-Architektur vervollständigt:** global.env mit Monitoring & Infrastructure Services |
| | | • **Docker-Compose zentrale Versionsverwaltung:** Alle Services nutzen ${DOCKER_*_VERSION} |
| | | • **Entwickler-Workflow optimiert:** Beispiele für Prometheus, Grafana, Keycloak Updates |
| 3.0.0 | 2025-09-13 | **Zentrale Docker-Versionsverwaltung implementiert** |
| 1.1.0 | 2025-08-16 | **Umfassende Überarbeitung und Optimierung:** |
| | | • Aktualisierung aller Dockerfile-Templates auf aktuelle Implementierung |
| | | • Integration von BuildKit Cache Mounts für optimale Build-Performance |
| | | • Dokumentation moderner Docker-Features (syntax=docker/dockerfile:1.8) |
| | | • Erweiterte Service-Ports-Matrix mit Debug-Ports und korrekten Health-Checks |
| | | • Umfassende docker-compose Konfigurationsbeispiele mit Environment-Variablen |
| | | • Neue Sektion für automatisierte Container-Tests (test-dockerfile.sh) |
| | | • Aktualisierung auf Europe/Vienna Timezone und Java 21 Optimierungen |
| | | • Erweiterte Monitoring- und Observability-Konfigurationen |
| | | • Verbesserte Resource-Management und Performance-Tuning Einstellungen |
| 1.0.0 | 2025-08-16 | Initiale Docker-Guidelines basierend auf Containerisierungsstrategie |
| | | • **🔧 IDE-Integration:** VS Code/IntelliJ Unterstützung mit JSON Schema, Tasks und Auto-Completion |
| | | • **📊 Port-Range-Management:** Automatische Port-Zuweisung mit definierten Bereichen für Service-Kategorien |
| | | • **🚀 Entwickler-Workflow Optimierung:** Template-basierte Service-Erstellung und automatisierte Workflows |
| | | • **🎯 Best Practices erweitert:** Umfassende Richtlinien für zentrale Verwaltung und Entwickler-Workflows |
| | | • **📋 JSON Schema Validierung:** Vollständige TOML-Struktur-Validierung mit IDE-Integration |
| | | • **⚡ Template-System:** Service-Kategorien-basierte Compose-Generierung mit automatischer Build-Args-Integration |
| 3.0.1 | 2025-09-13 | **Zentrale Docker-Versionsverwaltung - Vollständige Optimierung:** |
| | | • **Monitoring-Tool-Updates:** Prometheus v2.54.1, Grafana 11.3.0, Keycloak 26.0.7 |
| | | • **Erweiterte Script-Funktionalität:** docker-versions-update.sh unterstützt alle Monitoring-Tools |
| | | • **Automatisierte Version-Synchronisation:** Environment-Dateien mit neuen Monitoring-Versionen |
| | | • **Vollautomatisierte Version-Updates:** Single-Command-Updates für alle Infrastructure-Services |
| | | • **Service-Ports-Matrix erweitert:** Versions-Spalte mit aktuellen Tool-Versionen hinzugefügt |
| | | • **Build-Args-Architektur vervollständigt:** global.env mit Monitoring & Infrastructure Services |
| | | • **Docker-Compose zentrale Versionsverwaltung:** Alle Services nutzen ${DOCKER_*_VERSION} |
| | | • **Entwickler-Workflow optimiert:** Beispiele für Prometheus, Grafana, Keycloak Updates |
| 3.0.0 | 2025-09-13 | **Zentrale Docker-Versionsverwaltung implementiert** |
| 1.1.0 | 2025-08-16 | **Umfassende Überarbeitung und Optimierung:** |
| | | • Aktualisierung aller Dockerfile-Templates auf aktuelle Implementierung |
| | | • Integration von BuildKit Cache Mounts für optimale Build-Performance |
| | | • Dokumentation moderner Docker-Features (syntax=docker/dockerfile:1.8) |
| | | • Erweiterte Service-Ports-Matrix mit Debug-Ports und korrekten Health-Checks |
| | | • Umfassende docker-compose Konfigurationsbeispiele mit Environment-Variablen |
| | | • Neue Sektion für automatisierte Container-Tests (test-dockerfile.sh) |
| | | • Aktualisierung auf Europe/Vienna Timezone und Java 21 Optimierungen |
| | | • Erweiterte Monitoring- und Observability-Konfigurationen |
| | | • Verbesserte Resource-Management und Performance-Tuning Einstellungen |
| 1.0.0 | 2025-08-16 | Initiale Docker-Guidelines basierend auf Containerisierungsstrategie |
---
.junie/guidelines/_templates/process-guide-template.md
+34 -12
View File
@@ -1,6 +1,7 @@
# {{NAME}} - Prozess-Richtlinie
---
guideline_type: "process-guide"
scope: "{{SCOPE}}"
audience: ["developers", "ai-assistants", "project-managers"]
@@ -8,6 +9,7 @@ last_updated: "{{DATE}}"
dependencies: ["master-guideline.md"]
related_files: []
ai_context: "{{SCOPE}}-Prozess und Workflow-Richtlinien für effiziente Entwicklung im Meldestelle-Projekt"
---
## 🎯 Prozess-Überblick
@@ -24,34 +26,42 @@ Dieser Guide beschreibt den standardisierten Workflow für {{SCOPE}} im Meldeste
## 📋 Workflow-Schritte
### Phase 1: Vorbereitung
**Ziel:** [Beschreibung des Ziels dieser Phase]
#### Voraussetzungen
- [ ] [Voraussetzung 1]
- [ ] [Voraussetzung 2]
- [ ] [Voraussetzung 3]
#### Durchführung
1. **Schritt 1:** [Detaillierte Beschreibung]
2. **Schritt 2:** [Detaillierte Beschreibung]
3. **Schritt 3:** [Detaillierte Beschreibung]
### Phase 2: Durchführung
**Ziel:** [Beschreibung des Ziels dieser Phase]
#### Hauptaufgaben
1. **Aufgabe 1:** [Beschreibung und Verantwortlicher]
2. **Aufgabe 2:** [Beschreibung und Verantwortlicher]
3. **Aufgabe 3:** [Beschreibung und Verantwortlicher]
#### Qualitätskontrolle
- **Zwischenprüfung:** [Was wird geprüft]
- **Kriterien:** [Erfolgskriterien]
### Phase 3: Abschluss und Validierung
**Ziel:** [Beschreibung des Ziels dieser Phase]
#### Abschlusschecks
- [ ] [Qualitätssicherung 1]
- [ ] [Qualitätssicherung 2]
- [ ] [Dokumentation aktualisiert]
@@ -59,13 +69,15 @@ Dieser Guide beschreibt den standardisierten Workflow für {{SCOPE}} im Meldeste
## ⚠️ Häufige Fallstricke
### Problem: [Häufiges Problem]
### Problem [häufiges Problem]
**Symptome:** [Wie erkennt man das Problem]
**Ursache:** [Warum tritt es auf]
**Lösung:** [Konkrete Schritte zur Lösung]
**Prävention:** [Wie kann es vermieden werden]
### Problem: [Weiteres Problem]
### Problem [weiteres Problem]
**Symptome:** [Wie erkennt man das Problem]
**Ursache:** [Warum tritt es auf]
**Lösung:** [Konkrete Schritte zur Lösung]
@@ -74,28 +86,33 @@ Dieser Guide beschreibt den standardisierten Workflow für {{SCOPE}} im Meldeste
## 🔧 Tools und Hilfsmittel
### Erforderliche Tools
| Tool | Verwendung | Installation/Zugriff | Dokumentation |
|------|------------|---------------------|---------------|
| [Tool 1] | [Zweck] | [Wie installieren] | [Link zur Doku] |
| [Tool 2] | [Zweck] | [Wie installieren] | [Link zur Doku] |
| Tool | Verwendung | Installation/Zugriff | Dokumentation |
|----------|------------|----------------------|-----------------|
| [Tool 1] | [Zweck] | [Wie installieren] | [Link zur Doku] |
| [Tool 2] | [Zweck] | [Wie installieren] | [Link zur Doku] |
### Optionale Tools
| Tool | Vorteil | Wann verwenden |
|------|---------|----------------|
| [Tool 1] | [Vorteil] | [Situation] |
| [Tool 2] | [Vorteil] | [Situation] |
| Tool | Vorteil | Wann verwenden |
|----------|-----------|----------------|
| [Tool 1] | [Vorteil] | [Situation] |
| [Tool 2] | [Vorteil] | [Situation] |
## 📊 Erfolgs-Metriken
### Qualitative Metriken
- **Kriterium 1:** [Beschreibung und Bewertung]
- **Kriterium 2:** [Beschreibung und Bewertung]
### Quantitative Metriken
- **Metrik 1:** [Zielwert und Messung]
- **Metrik 2:** [Zielwert und Messung]
### KPIs (Key Performance Indicators)
- **Effizienz:** [Wie wird gemessen]
- **Qualität:** [Wie wird gemessen]
- **Zufriedenheit:** [Wie wird gemessen]
@@ -103,10 +120,12 @@ Dieser Guide beschreibt den standardisierten Workflow für {{SCOPE}} im Meldeste
## 🚨 Eskalation und Support
### Wann eskalieren?
- [Situation 1 mit Zeitangabe]
- [Situation 2 mit Zeitangabe]
### Eskalationspfad
1. **Level 1:** [Erste Anlaufstelle]
2. **Level 2:** [Zweite Anlaufstelle]
3. **Level 3:** [Finale Eskalation]
@@ -114,16 +133,19 @@ Dieser Guide beschreibt den standardisierten Workflow für {{SCOPE}} im Meldeste
## 📋 Checkliste
### Vor Prozessstart
- [ ] Alle Voraussetzungen erfüllt
- [ ] Tools verfügbar und konfiguriert
- [ ] Team informiert und bereit
### Während des Prozesses
- [ ] Fortschritt dokumentiert
- [ ] Qualitätskontrollen durchgeführt
- [ ] Kommunikation aufrechterhalten
### Nach Prozessabschluss
- [ ] Ergebnisse validiert
- [ ] Dokumentation aktualisiert
- [ ] Lessons Learned erfasst
@@ -131,13 +153,13 @@ Dieser Guide beschreibt den standardisierten Workflow für {{SCOPE}} im Meldeste
## 🔗 Navigation
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
- [Master-Guideline](../master-guideline.md) - übergeordnete Projektrichtlinien
- [Architecture-Principles](../project-standards/architecture-principles.md) - Architektur-Grundsätze
- [Testing-Standards](../project-standards/testing-standards.md) - Qualitätssicherung
---
**Prozess-Status:** [Aktiv/Beta/In Entwicklung]
**Letzte Aktualisierung:** {{DATE}}
**letzte Aktualisierung:** {{DATE}}
**Nächste Überprüfung:** [Datum oder Trigger]
**Verantwortlicher:** [Name/Team]
.junie/guidelines/_templates/project-standard-template.md
+20 -9
View File
@@ -1,6 +1,7 @@
# {{NAME}} - Standards und Richtlinien
---
guideline_type: "project-standards"
scope: "{{SCOPE}}"
audience: ["developers", "ai-assistants", "architects"]
@@ -8,6 +9,7 @@ last_updated: "{{DATE}}"
dependencies: ["master-guideline.md"]
related_files: []
ai_context: "{{SCOPE}}-Standards und Best Practices für das Meldestelle-Projekt"
---
## 🎯 Überblick
@@ -23,42 +25,51 @@ Diese Richtlinie definiert die verbindlichen Standards und Best Practices für {
## 📋 Grundprinzipien
### 1. [Prinzip 1]
[Beschreibung des ersten Grundprinzips]
### 2. [Prinzip 2]
[Beschreibung des zweiten Grundprinzips]
### 3. [Prinzip 3]
[Beschreibung des dritten Grundprinzips]
## 🔧 Implementierungsrichtlinien
### [Bereich 1]
[Konkrete Implementierungsanforderungen]
### [Bereich 2]
[Weitere Implementierungsrichtlinien]
## ✅ Qualitätssicherung
### Überprüfung und Validierung
- **Checkliste:** [Spezifische Prüfpunkte]
- **Tools:** [Empfohlene Validierungstools]
- **Tests:** [Erforderliche Testarten]
### Erfolgskriterien
- **Quantitativ:** [Messbare Ziele]
- **Qualitativ:** [Qualitätskriterien]
## 🚨 Häufige Fallstricke
### Problem: [Häufiges Problem]
**Ursache:** [Warum tritt es auf]
**Lösung:** [Konkrete Lösung]
### Problem [häufiges Problem]
### Problem: [Weiteres Problem]
**Ursache:** [Warum tritt es auf]
**Lösung:** [Konkrete Lösung]
**Lösung:** [konkrete Lösung]
### Problem [Weiteres Problem]
**Ursache:** [Warum tritt es auf]
**Lösung:** [konkrete Lösung]
## 📊 Checkliste
@@ -70,12 +81,12 @@ Diese Richtlinie definiert die verbindlichen Standards und Best Practices für {
## 🔗 Navigation
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
- [Architecture-Principles](./architecture-principles.md) - Architektur-Grundsätze
- [Coding-Standards](./coding-standards.md) - Code-Qualitätsstandards
- [Master-Guideline](../master-guideline.md) - übergeordnete Projektrichtlinien
- [Architecture-Principles](../project-standards/architecture-principles.md) - Architektur-Grundsätze
- [Coding-Standards](../project-standards/coding-standards.md) - Code-Qualitätsstandards
---
**Status:** [Aktiv/In Entwicklung/Überarbeitung]
**Letzte Überprüfung:** {{DATE}}
**letzte Überprüfung:** {{DATE}}
**Nächste Überprüfung:** [Bei Bedarf oder regelmäßig]
.junie/guidelines/_templates/technology-guideline-template.md
+9 -5
View File
@@ -1,6 +1,7 @@
# [TECHNOLOGIE-NAME] Guidelines
---
guideline_type: "technology"
scope: "[spezifischer-bereich-identifier]"
audience: ["developers", "ai-assistants", "devops"]
@@ -8,6 +9,7 @@ last_updated: "[YYYY-MM-DD]"
dependencies: ["master-guideline.md", "[weitere-abhängigkeiten]"]
related_files: ["[relevante-projekt-dateien]", "config/[konfig-dateien]"]
ai_context: "[Deutsche Kurzbeschreibung für KI-Verständnis]"
---
## 🚀 Überblick und Philosophie
@@ -42,8 +44,8 @@ ai_context: "[Deutsche Kurzbeschreibung für KI-Verständnis]"
### Häufige Aufgaben
| Aufgabe | Befehl | Beschreibung |
|---------|---------|--------------|
| Aufgabe | Befehl | Beschreibung |
|----------|-------------|----------------|
| [Task 1] | `[command]` | [Beschreibung] |
| [Task 2] | `[command]` | [Beschreibung] |
| [Task 3] | `[command]` | [Beschreibung] |
@@ -81,8 +83,8 @@ ai_context: "[Deutsche Kurzbeschreibung für KI-Verständnis]"
### Metrics
| Metric | Typ | Beschreibung |
|--------|-----|--------------|
| Metric | Typ | Beschreibung |
|-----------------|-------|----------------|
| `[metric_name]` | [Typ] | [Beschreibung] |
## 🚨 Troubleshooting
@@ -90,6 +92,7 @@ ai_context: "[Deutsche Kurzbeschreibung für KI-Verständnis]"
### Häufige Probleme
#### [Problem 1]
```bash
# Diagnose
[diagnostic-commands]
@@ -99,12 +102,13 @@ ai_context: "[Deutsche Kurzbeschreibung für KI-Verständnis]"
```
#### [Problem 2]
[Weitere Problemlösungen]
---
**Navigation:**
- [Docker-Overview](./docker/docker-overview.md) - [falls relevant]
- [Docker-Overview](../technology-guides/docker/docker-overview.md) - [falls relevant]
- [Master-Guideline](../master-guideline.md) - Projekt-Überblick
- [Architecture Principles](../project-standards/architecture-principles.md) - Architektur-Grundlagen
.junie/guidelines/master-guideline.md
+10 -10
View File
@@ -1,13 +1,13 @@
# Meldestelle_Pro: Entwicklungs-Guideline
# Meldestelle_Pro: Entwicklung-Guideline
**Status:** Finalisiert & Verbindlich
**Status:** Finalisiert & verbindlich
**Version:** 2.1.0
**Stand:** 15. September 2025
**Stand:** 15. September 2025
## 1. Vision & Architektonische Grundpfeiler
## 1. Vision & architektonische Grundpfeiler
Dieses Dokument definiert die verbindlichen technischen Richtlinien und Qualitätsstandards für das Projekt "
Meldestelle_Pro". Ziel ist die Schaffung einer modernen, skalierbaren und wartbaren Plattform für den Pferdesport.
Dieses Dokument definiert die verbindlichen technischen Richtlinien und Qualitätsstandards für das Projekt "Meldestelle_Pro".
Ziel ist die Schaffung einer modernen, skalierbaren und wartbaren Plattform für den Pferdesport.
Unsere Architektur basiert auf **vier Säulen**:
@@ -50,11 +50,11 @@ Kernpunkte:
## 4. Frontend-Entwicklung & Multiplatform
Detaillierte Frontend-Entwicklungsrichtlinien finden Sie in:
**→ [Web App Guideline](./technology-guides/web-app-guideline.md)**
**→ [Web-App Guideline](./technology-guides/web-app-guideline.md)**
Kernpunkte:
- **MVVM-Pattern:** Model-View-ViewModel für UI-Struktur
- **Kotlin Multiplatform:** Code-Sharing zwischen Desktop und Web
- **Kotlin Multiplatform:** Codesharing zwischen Desktop und Web
- **Compose Multiplatform:** Deklarative UI mit @Composable-Funktionen
- **Feature-basierte Struktur:** Vertikale Schnitte nach Fachlichkeit
@@ -66,7 +66,7 @@ Detaillierte Testing-Standards finden Sie in:
**→ [Testing Standards](./project-standards/testing-standards.md)**
Kernpunkte:
- **Test-Pyramide:** 80%+ Unit-Tests, Integrationstests für externe Systeme
- **Test-Pyramide:** 80 %+ Unit-Tests, Integrationstests für externe Systeme
- **Testcontainers:** Goldstandard für Infrastruktur-Tests
- **Result-Pattern:** Tests für Success- und Failure-Cases
- **Debug-Logs:** `[DEBUG_LOG]`-Präfix für Test-Ausgaben
@@ -76,7 +76,7 @@ Kernpunkte:
## 6. Docker & Infrastructure
Detaillierte Docker- und Infrastruktur-Richtlinien finden Sie in:
**→ [Docker Guidelines](./technology-guides/docker/)**
**→ [Docker Guidelines](./technology-guides/docker)**
Kernpunkte:
- **Docker-Architektur:** Microservices mit Service Discovery
.junie/guidelines/process-guides/trace-bullet-guideline.md
+16 -11
View File
@@ -1,6 +1,7 @@
# Guideline: Zyklus "Tracer Bullet"
---
guideline_type: "process-guide"
scope: "trace-bullet-development-cycle"
audience: ["developers", "ai-assistants", "project-managers"]
@@ -8,12 +9,13 @@ last_updated: "2025-09-15"
dependencies: ["master-guideline.md", "web-app-guideline.md"]
related_files: ["docker-compose.yml", "temp/ping-service/**", "client/**"]
ai_context: "End-to-End-Architektur-Validierungszyklus, Infrastruktur-Tests, Ping-Service-Implementierung"
---
* **Zyklus-Start:** 15. August 2025
* **Zyklus-Start:** 15. August 2025
* **Status:** In Arbeit
* **Basis:** Diese Guideline erweitert die [Master-Guideline](../master-guideline.md)
* **Frontend-Standard:** Alle Web-Frontend-Entwicklung erfolgt gemäß der [Web-App-Guideline](../technology-guides/web-app-guideline.md), die ab sofort der verbindliche Standard ist.
* **Frontend-Standard:** Alle Web-Frontend-Entwicklungen erfolgen gemäß der [Web-App-Guideline](../technology-guides/web-app-guideline.md), die ab sofort verbindlicher Standard ist.
> **🤖 AI-Assistant Hinweis:**
> Der Tracer Bullet Zyklus validiert die End-to-End-Architektur:
@@ -51,13 +53,13 @@ Die folgenden Module und Aufgaben sind Teil dieses Zyklus:
### 2.3. Frontend-Infrastruktur (:client)
* **Aufgabe:** Aufbau einer sauberen Grundstruktur für die Kotlin Multiplatform App nach dem **MVVM-Muster** und Implementierung der **"Ping"**-Funktionalität. Die Umsetzung erfolgt mit **Compose for Web** gemäß der [`web-app-guideline.md`](./web-app-guideline.md).
* **Aufgabe:** Aufbau einer sauberen Grundstruktur für die Kotlin Multiplatform App nach dem **MVVM-Muster** und Implementierung der **"Ping"**-Funktionalität. Die Umsetzung erfolgt mit **Compose for Web** gemäß der [`web-app-guideline.md`](../technology-guides/web-app-guideline.md).
* **Status:** 🔳 In Arbeit.
* **Spezifische Anforderungen & Test-Szenarien:**
* **UI-Komponenten:** Die UI muss einen Button ("Ping Backend") und ein Textfeld zur Statusanzeige enthalten, umgesetzt als `@Composable`-Funktionen.
* **Zustands-Management:** Die UI muss vier Zustände klar und visuell unterscheidbar abbilden:
1. **Initialzustand:** Neutrale Nachricht ("Klicke auf den Button …"), Button aktiv.
2. **Ladezustand:** Lade-Nachricht ("Pinge Backend …"), Button deaktiviert.
1. **Initialzustand:** Neutrale Nachricht ("Klicke auf den Button …"), Button aktiv.
2. **Ladezustand:** Lade-Nachricht ("Pinge Backend …"), Button deaktiviert.
3. **Erfolgszustand:** Positive Antwort ("Antwort vom Backend: pong"), Button aktiv.
4. **Fehlerzustand:** Klare Fehlermeldung ("Fehler: ..."), Button aktiv.
* **Architektur:** Der API-Aufruf muss nach dem **MVVM-Muster** gekapselt sein, wobei die UI (`jsMain`) das ViewModel aus `commonMain` konsumiert.
@@ -68,8 +70,8 @@ Die folgenden Module und Aufgaben sind Teil dieses Zyklus:
ausschließlich der Stabilisierung der technischen Infrastruktur. Es wird keine komplexe Geschäftslogik implementiert.
* **Qualitätsstandards gelten uneingeschränkt:** Auch für diesen technischen Zyklus gelten alle Regeln der
Master-Guideline. Insbesondere:
* **Minimale, aber essentielle Tests:** Für den "Tracer-Bullet"-Zyklus sind nur die **absolut notwendigen Tests** erforderlich, die beweisen, dass die Kernfunktionalität gegeben ist. Komplexere Testsuites sind für die Architektur-Validierung nicht notwendig.
* **Beispiel Monitoring:** Nur ein "Smoke-Test" für den monitoring-server (startet er überhaupt?) ist essentiell für den E2E-Test.
* **Minimale, aber essenzielle Tests:** Für den "Tracer-Bullet"-Zyklus sind nur die **absolut notwendigen Tests** erforderlich, die beweisen, dass die Kernfunktionalität gegeben ist. Komplexere Testsuites sind für die Architektur-Validierung nicht notwendig.
* **Beispiel Monitoring:** Nur ein "Smoke-Test" für den monitoring-server (startet er überhaupt?) ist essenziell für den E2E-Test.
* **Kein `println`:** Es wird ausschließlich der strukturierte Logger verwendet.
* **Dokumentation ist Teil der Aufgabe:** Jedes Modul, das wir überarbeiten, wird mit einer aktualisierten und präzisen
`README.md`-Datei abgeschlossen.
@@ -94,9 +96,10 @@ Dieser Zyklus ist abgeschlossen, wenn **alle** der folgenden Kriterien erfüllt
---
## Status-Update (Stand: 16. August 2025, 10:54 Uhr)
## Status-Update (Stand: 16. August 2025, 10:54 Uhr)
### ✅ **Bereits erledigt:**
1. **Strukturelle Komponenten sind implementiert:**
- Alle `:core` Module (core-domain, core-utils) mit README-CORE.md
- Alle `:infrastructure` Module (auth, cache, event-store, gateway, messaging, monitoring) mit README-INFRASTRUCTURE.md
@@ -104,6 +107,7 @@ Dieser Zyklus ist abgeschlossen, wenn **alle** der folgenden Kriterien erfüllt
- `:client` Module (common-ui, desktop-app, web-app) mit ClientModuleDocumentation.md
### ❌ **Noch offen:**
1. **End-to-End "Tracer Bullet"-Test:** Nicht durchführbar, da docker-compose nicht installiert
2. **Clean Build ohne Warnungen:**
- 5 Testfehler (4 in auth-client, 1 in redis-event-store)
@@ -112,6 +116,7 @@ Dieser Zyklus ist abgeschlossen, wenn **alle** der folgenden Kriterien erfüllt
4. **Guideline-Finalisierung:** Diese Überprüfung abgeschlossen, aber master-guideline.md Status unbekannt
### 🔧 **Nächste Schritte:**
1. Testfehler in auth-client (Performance- und Security-Tests) beheben
2. Testfehler in redis-event-store beheben
3. Kotlin-Warnungen und Deprecation-Warnings eliminieren
@@ -129,8 +134,8 @@ Dieser Zyklus ist abgeschlossen, wenn **alle** der folgenden Kriterien erfüllt
---
**Navigation:**
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
- [Web-App-Guideline](../technology-guides/web-app-guideline.md) - Frontend-Entwicklungsstandard
- [Master-Guideline](../master-guideline.md) - übergeordnete Projektrichtlinien
- [Web-App-Guideline](../technology-guides/web-app-guideline.md) – Frontend-Entwicklungsstandard
- [Architecture-Principles](../project-standards/architecture-principles.md) - Architektur-Grundsätze
- [Docker Guidelines](../technology-guides/docker/) - Infrastructure und Deployment
- [Docker Guidelines](../technology-guides/docker) - Infrastructure und Deployment
- [Testing-Standards](../project-standards/testing-standards.md) - Test-Qualitätssicherung
.junie/guidelines/project-standards/architecture-principles.md
+16 -15
View File
@@ -1,16 +1,17 @@
# Architecture Principles und Grundsätze
---
guideline_type: "project-standards"
scope: "architecture-principles"
guideline_type: "project-standards"scope: "architecture-principles"
audience: ["developers", "architects", "ai-assistants"]
last_updated: "2025-09-15"
dependencies: ["master-guideline.md"]
related_files: ["build.gradle.kts", "settings.gradle.kts", "docker-compose.yml"]
ai_context: "Architektonische Grundlagen, Microservices-Pattern, DDD-Prinzipien, ereignisgesteuerte Architektur und Multiplatform-Strategie"
---
## 🏗️ Vision & Architektonische Grundpfeiler
## 🏗️ Vision & architektonische Grundpfeiler
Dieses Dokument definiert die verbindlichen technischen Richtlinien und Qualitätsstandards für das Projekt "Meldestelle_Pro". Ziel ist die Schaffung einer modernen, skalierbaren und wartbaren Plattform für den Pferdesport.
@@ -34,12 +35,12 @@ Dieses Dokument definiert die verbindlichen technischen Richtlinien und Qualitä
### Architektur-Säulen im Detail
| Säule | Technologie | Zweck | Umsetzung |
|-------|------------|-------|-----------|
| Microservices | Spring Boot, Docker | Modularität & Skalierbarkeit | Service-per-Domain-Pattern |
| DDD | Kotlin, Clean Architecture | Fachlichkeit im Code | Bounded Contexts, Domain Events |
| EDA | Kafka, Events | Entkopplung & Resilienz | Asynchrone Kommunikation |
| KMP | Kotlin Multiplatform | Effizienz & Konsistenz | Shared Business Logic |
| Säule | Technologie | Zweck | Umsetzung |
|---------------|----------------------------|------------------------------|---------------------------------|
| Microservices | Spring Boot, Docker | Modularität & Skalierbarkeit | Service-per-Domain-Pattern |
| DDD | Kotlin, Clean Architecture | Fachlichkeit im Code | Bounded Contexts, Domain Events |
| EDA | Kafka, Events | Entkopplung & Resilienz | Asynchrone Kommunikation |
| KMP | Kotlin Multiplatform | Effizienz & Konsistenz | Shared Business Logic |
## 🔧 Backend-Entwicklungsrichtlinien
@@ -47,7 +48,7 @@ Dieses Dokument definiert die verbindlichen technischen Richtlinien und Qualitä
Jeder fachliche Microservice folgt der 4-Layer-Struktur (`api`, `application`, `domain`, `infrastructure`).
```
```plaintext
service-name/
├── service-name-api/ # REST-Endpoints, DTOs
├── service-name-application/ # Use Cases, Commands, Queries
@@ -120,7 +121,7 @@ value class MemberId(val value: UUID) {
}
}
data class Member private constructor(
data class Member(
val id: MemberId,
val name: String,
val email: Email,
@@ -236,7 +237,7 @@ Das Frontend folgt konsequent dem **Model-View-ViewModel (MVVM)**-Muster und der
### Multiplatform-Struktur
```
```plaintext
client/
├── src/commonMain/kotlin/ # Shared Business Logic
│ ├── domain/ # Domain Models
@@ -330,7 +331,7 @@ fun MemberListScreen(
### Bounded Contexts
```
```plaintext
Meldestelle-Domain/
├── member-context/ # Mitgliederverwaltung
├── tournament-context/ # Turnierverwaltung
@@ -489,7 +490,7 @@ fun createMember(@RequestBody request: CreateMemberRequest): ResponseEntity<Memb
**Status:** Akzeptiert
**Kontext:** Code-Sharing zwischen Desktop und Web
**Kontext:** Codesharing zwischen Desktop und Web
**Entscheidung:** KMP mit Compose Multiplatform
@@ -502,7 +503,7 @@ fun createMember(@RequestBody request: CreateMemberRequest): ResponseEntity<Memb
---
**Navigation:**
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
- [Master-Guideline](../master-guideline.md) - übergeordnete Projektrichtlinien
- [Coding-Standards](./coding-standards.md) - Code-Qualitätsstandards
- [Testing-Standards](./testing-standards.md) - Test-Qualitätssicherung
- [Documentation-Standards](./documentation-standards.md) - Dokumentationsrichtlinien
.junie/guidelines/project-standards/coding-standards.md
+13 -9
View File
@@ -19,7 +19,7 @@ ai_context: "Coding conventions, naming standards, type safety, error handling,
* **Code-Stil:** Offizielle Kotlin Coding Conventions, durch `Detekt` geprüft.
> **🤖 AI-Assistant Hinweis:**
> Alle Kotlin-Code muss den offiziellen Kotlin Coding Conventions entsprechen:
> Alle Kotlin-Code müssen den offiziellen Kotlin Coding Conventions entsprechen:
> - **Detekt-Validierung:** Automatische Code-Style-Prüfung
> - **Java 21+ Kompatibilität:** Nutze moderne Java-Features wo sinnvoll
> - **Multiplatform:** Code sollte plattformübergreifend funktionieren
@@ -69,13 +69,13 @@ logger.info {
### Namenskonventionen-Übersicht
| Element | Convention | Beispiel |
|---------|------------|----------|
| Klassen/Interfaces | PascalCase | `MemberService`, `EventRepository` |
| Funktionen/Variablen | camelCase | `authenticateUser`, `memberRepository` |
| Konstanten | SCREAMING_SNAKE_CASE | `MAX_RETRY_ATTEMPTS` |
| Test-Methoden | Backticks beschreibend | `` `should return Success for valid credentials` `` |
| Enum-Werte | PascalCase | `MemberStatus.ACTIVE` |
| Element | Convention | Beispiel |
|----------------------|------------------------|-----------------------------------------------------|
| Klassen/Interfaces | PascalCase | `MemberService`, `EventRepository` |
| Funktionen/Variablen | camelCase | `authenticateUser`, `memberRepository` |
| Konstanten | SCREAMING_SNAKE_CASE | `MAX_RETRY_ATTEMPTS` |
| Test-Methoden | Backticks beschreibend | `` `should return Success for valid credentials` `` |
| Enum-Werte | PascalCase | `MemberStatus.ACTIVE` |
### Code-Qualitäts-Checkliste
@@ -88,6 +88,7 @@ logger.info {
### Häufige Code-Patterns
#### Typsichere IDs
```kotlin
@JvmInline
value class EntityId(val value: UUID) {
@@ -102,6 +103,7 @@ value class EntityId(val value: UUID) {
```
#### Error-Handling mit Result
```kotlin
interface EntityRepository {
suspend fun findById(id: EntityId): Result<Entity?, RepositoryError>
@@ -116,6 +118,7 @@ when (val result = repository.findById(entityId)) {
```
#### Structured Logging
```kotlin
class EntityService {
private val logger = LoggerFactory.getLogger(EntityService::class.java)
@@ -149,6 +152,7 @@ class EntityService {
```
#### Sealed Class Hierarchie für Fehler
```kotlin
sealed interface DomainError {
val message: String
@@ -210,7 +214,7 @@ potential-bugs:
---
**Navigation:**
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
- [Master-Guideline](../master-guideline.md) - übergeordnete Projektrichtlinien
- [Testing-Standards](./testing-standards.md) - Test-Qualitätsstandards
- [Documentation-Standards](./documentation-standards.md) - Dokumentationsrichtlinien
- [Architecture-Principles](./architecture-principles.md) - Architektur-Grundsätze
.junie/guidelines/project-standards/documentation-standards.md
+30 -7
View File
@@ -1,6 +1,7 @@
# Documentation Standards
---
guideline_type: "project-standards"
scope: "documentation-standards"
audience: ["developers", "ai-assistants", "technical-writers"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["master-guideline.md"]
related_files: ["README*.md", "docs/**", "*.md", "openapi.yaml"]
ai_context: "Documentation language standards, README structure, API documentation, and technical writing guidelines"
---
## 📝 Dokumentationsstandards
@@ -41,39 +43,50 @@ ai_context: "Documentation language standards, README structure, API documentati
# [Projekt/Modul Name]
## Überblick
[Kurze Beschreibung des Zwecks und der Funktionalität]
## Architektur
[Architektonische Entscheidungen und Komponenten-Übersicht]
## Entwicklung
[Setup-Anweisungen für lokale Entwicklung]
### Voraussetzungen
[Erforderliche Tools und Versionen]
### Installation
[Schritt-für-Schritt Setup-Anleitung]
### Konfiguration
[Wichtige Konfigurationsoptionen]
## Tests
[Test-Ausführung und Test-Strategie]
## Deployment
[Deployment-Anweisungen für verschiedene Umgebungen]
## API-Dokumentation
[Links zu API-Docs oder eingebettete Dokumentation]
## Troubleshooting
[Häufige Probleme und Lösungen]
```
### Code-Kommentar-Standards
#### Deutsche Geschäftslogik-Kommentare
```kotlin
/**
* Prüft, ob ein Mitglied für die Anmeldung zu einem Turnier berechtigt ist.
@@ -95,6 +108,7 @@ fun isEligibleForTournament(member: Member, tournament: Tournament): Result<Bool
```
#### Englische technische Kommentare
```kotlin
/**
* Cache implementation using Redis with TTL support
@@ -117,6 +131,7 @@ class RedisCache<T>(
### OpenAPI-Dokumentation Standards
#### Deutsche API-Beschreibungen
```yaml
openapi: 3.0.0
info:
@@ -181,6 +196,7 @@ components:
### Dokumentations-Checkliste
#### README-Dateien
- [ ] **Struktur:** Folgt dem Standard-Template
- [ ] **Sprache:** Auf Deutsch verfasst
- [ ] **Aktualität:** Entspricht dem aktuellen Code-Stand
@@ -189,6 +205,7 @@ components:
- [ ] **Links:** Funktionierende Verweise auf verwandte Dokumentation
#### API-Dokumentation
- [ ] **OpenAPI-Spezifikation:** Vollständig und valide
- [ ] **Deutsche Beschreibungen:** Für alle Endpunkte und Schemas
- [ ] **Beispiele:** Realistische Request/Response-Beispiele
@@ -196,6 +213,7 @@ components:
- [ ] **Authentifizierung:** Sicherheitsanforderungen dokumentiert
#### Code-Kommentare
- [ ] **Geschäftslogik:** Deutsche Kommentare für fachliche Aspekte
- [ ] **Technische Details:** Englische Kommentare für Framework-/Library-Code
- [ ] **Komplexität:** Komplexe Algorithmen sind erklärt
@@ -205,8 +223,8 @@ components:
### Dokumentations-Patterns
#### Architektur-Diagramme
```markdown
## System-Architektur
### System-Architektur
```mermaid
graph TB
@@ -239,16 +257,17 @@ graph TB
TS --> PG
NS --> RD
```
```
#### Feature-Dokumentation
```markdown
## Feature: Turnier-Anmeldung
### Fachlicher Überblick
Die Turnier-Anmeldung ermöglicht es Mitgliedern, sich für Turniere zu registrieren.
### User Stories
- Als Mitglied möchte ich mich für ein Turnier anmelden können
- Als Turnierleiter möchte ich Anmeldungen verwalten können
@@ -260,20 +279,22 @@ Die Turnier-Anmeldung ermöglicht es Mitgliedern, sich für Turniere zu registri
- `DELETE /registrations/{id}` - Anmeldung stornieren
#### Domain-Events
- `TournamentRegistrationCreated` - Bei erfolgreicher Anmeldung
- `TournamentRegistrationCancelled` - Bei Stornierung
### Business Rules
1. Anmeldung nur für aktive Mitglieder möglich
2. Anmeldeschluss muss beachtet werden
3. Maximale Teilnehmerzahl darf nicht überschritten werden
```
#### Troubleshooting-Dokumentation
```markdown
## Häufige Probleme
### Problem: Service startet nicht
**Symptome:** Container bleibt im Status "Restarting"
**Ursachen:**
@@ -287,6 +308,7 @@ Die Turnier-Anmeldung ermöglicht es Mitgliedern, sich für Turniere zu registri
3. Port-Konflikte lösen: `netstat -tulpn | grep :8080`
### Problem: Langsame API-Antworten
**Symptome:** Response-Zeiten > 2 Sekunden
**Debugging:**
@@ -302,16 +324,17 @@ docker-compose exec redis redis-cli info stats
- Database-Indizes überprüfen
- Query-Performance analysieren
- Cache-Hit-Rate optimieren
```
### Versionierung und Updates
#### Dokumentations-Versionierung
- README-Dateien werden mit dem Code versioniert
- API-Dokumentation folgt Semantic Versioning
- Changelog wird für breaking changes geführt
#### Update-Prozess
1. **Code-Änderungen** → README aktualisieren
2. **API-Änderungen** → OpenAPI-Spec anpassen
3. **Architektur-Änderungen** → Diagramme überarbeiten
.junie/guidelines/project-standards/testing-standards.md
+14 -8
View File
@@ -1,6 +1,7 @@
# Testing Standards und Qualitätssicherung
---
guideline_type: "project-standards"
scope: "testing-standards"
audience: ["developers", "ai-assistants"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["master-guideline.md", "coding-standards.md"]
related_files: ["build.gradle.kts", "src/test/**", "testcontainers.properties"]
ai_context: "Testing strategies, test pyramid, tools, coverage requirements, and debugging practices"
---
## 🧪 Testing Standards
@@ -16,7 +18,7 @@ Tests sind ein integraler Bestandteil jedes Features und müssen einen hohen Sta
> **🤖 AI-Assistant Hinweis:**
> Testing-Prinzipien für das Meldestelle-Projekt:
> - **Test-Pyramide:** 80%+ Unit-Tests, Integrationstests für externe Systeme
> - **Test-Pyramide:** 80 %+ Unit-Tests, Integrationstests für externe Systeme
> - **Testcontainers:** Goldstandard für Infrastruktur-Tests
> - **Debug-Logs:** Präfix `[DEBUG_LOG]` für Test-Ausgaben
> - **Result-Pattern:** Tests müssen auch Error-Handling validieren
@@ -208,15 +210,16 @@ fun `should handle complex business scenario`() {
### Test-Kategorien und Werkzeuge
| Test-Typ | Coverage-Ziel | Werkzeuge | Verwendung |
|----------|---------------|-----------|------------|
| Unit-Tests | 80%+ | JUnit 5, MockK, AssertJ | Domänen- & Anwendungslogik |
| Integrationstests | Alle Repositories | Testcontainers, JUnit 5 | Externe Integrationen |
| End-to-End Tests | Kritische User-Journeys | Testcontainers, REST Assured | Vollständige Workflows |
| Test-Typ | Coverage-Ziel | Werkzeuge | Verwendung |
|-------------------|-------------------------|------------------------------|----------------------------|
| Unit-Tests | 80%+ | JUnit 5, MockK, AssertJ | Domänen- & Anwendungslogik |
| Integrationstests | Alle Repositories | Testcontainers, JUnit 5 | Externe Integrationen |
| End-to-End Tests | Kritische User-Journeys | Testcontainers, REST Assured | Vollständige Workflows |
### Testcontainer-Konfiguration
#### PostgreSQL
#### PostgresQL
```kotlin
@Container
private val postgresContainer = PostgreSQLContainer("postgres:16-alpine")
@@ -227,6 +230,7 @@ private val postgresContainer = PostgreSQLContainer("postgres:16-alpine")
```
#### Redis
```kotlin
@Container
private val redisContainer = GenericContainer<Nothing>("redis:7-alpine")
@@ -235,6 +239,7 @@ private val redisContainer = GenericContainer<Nothing>("redis:7-alpine")
```
#### Kafka
```kotlin
@Container
private val kafkaContainer = KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.4.0"))
@@ -242,6 +247,7 @@ private val kafkaContainer = KafkaContainer(DockerImageName.parse("confluentinc/
```
#### Keycloak
```kotlin
@Container
private val keycloakContainer = KeycloakContainer("quay.io/keycloak/keycloak:26.0.7")
@@ -373,7 +379,7 @@ fun `should handle high load efficiently`() {
---
**Navigation:**
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
- [Master-Guideline](../master-guideline.md) - übergeordnete Projektrichtlinien
- [Coding-Standards](./coding-standards.md) - Code-Qualitätsstandards
- [Documentation-Standards](./documentation-standards.md) - Dokumentationsrichtlinien
- [Architecture-Principles](./architecture-principles.md) - Architektur-Grundsätze
.junie/guidelines/technology-guides/docker/docker-architecture.md
+34 -26
View File
@@ -1,6 +1,7 @@
# Docker-Architektur und Services
---
guideline_type: "technology"
scope: "docker-architecture"
audience: ["developers", "ai-assistants", "devops"]
@@ -8,16 +9,19 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "master-guideline.md"]
related_files: ["docker-compose.yml", "docker/versions.toml", "scripts/docker-versions-update.sh"]
ai_context: "Docker-Container-Architektur, Service-Definitionen und zentrale Versionsverwaltung"
---
## 🏗️ Architektur-Überblick
> **📖 Hinweis:** Für einen allgemeinen Überblick über die Docker-Infrastruktur siehe [docker-overview](docker-overview.md).
### Container-Kategorien
```mermaid
graph TB
subgraph "Infrastructure Services"
PG[PostgreSQL]
PG[PostgresQL]
RD[Redis]
KC[Keycloak]
KF[Kafka+Zookeeper]
@@ -51,20 +55,20 @@ graph TB
### Service-Ports Matrix
| Service | Development | Production | Health Check | Debug Port | Version |
|---------|------------|------------|--------------|------------|---------|
| PostgreSQL | 5432 | Internal | pg_isready -U meldestelle -d meldestelle | - | 16-alpine |
| Redis | 6379 | Internal | redis-cli ping | - | 7-alpine |
| Keycloak | 8180 | 8443 (HTTPS) | /health/ready | - | 26.0.7 |
| Kafka | 9092 | Internal | kafka-topics --bootstrap-server localhost:9092 --list | - | 7.4.0 |
| Zookeeper | 2181 | Internal | nc -z localhost 2181 | - | 7.4.0 |
| Consul | 8500 | Internal | /v1/status/leader | - | 1.15 |
| Auth Server | 8081 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Ping Service | 8082 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Monitoring Server | 8083 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Prometheus | 9090 | Internal | /-/healthy | - | v2.54.1 |
| Grafana | 3000 | 3443 (HTTPS) | /api/health | - | 11.3.0 |
| Nginx | - | 80/443 | /health | - | 1.25-alpine |
| Service | Development | Production | Health Check | Debug Port | Version |
|-------------------|-------------|--------------|-------------------------------------------------------|------------|-------------|
| PostgreSQL | 5432 | Internal | pg_isready -U meldestelle -d meldestelle | - | 16-alpine |
| Redis | 6379 | Internal | redis-cli ping | - | 7-alpine |
| Keycloak | 8180 | 8443 (HTTPS) | /health/ready | - | 26.0.7 |
| Kafka | 9092 | Internal | kafka-topics --bootstrap-server localhost:9092 --list | - | 7.4.0 |
| Zookeeper | 2181 | Internal | nc -z localhost 2181 | - | 7.4.0 |
| Consul | 8500 | Internal | /v1/status/leader | - | 1.15 |
| Auth Server | 8081 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Ping Service | 8082 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Monitoring Server | 8083 | Internal | /actuator/health/readiness | 5005 | 1.0.0 |
| Prometheus | 9090 | Internal | /-/healthy | - | v2.54.1 |
| Grafana | 3000 | 3443 (HTTPS) | /api/health | - | 11.3.0 |
| Nginx | - | 80/443 | /health | - | 1.25-alpine |
## 🎯 Zentrale Docker-Versionsverwaltung
@@ -93,18 +97,18 @@ ARG GRADLE_VERSION=9.0.0
```toml
# docker/versions.toml - SINGLE SOURCE OF TRUTH
[versions]
gradle = "9.0.0"
gradle = "9.1.0"
java = "21"
node = "20.12.0"
nginx = "1.25-alpine"
node = "22.21.0"
nginx = "1.28.0-alpine"
prometheus = "v2.54.1"
grafana = "11.3.0"
keycloak = "26.0.7"
keycloak = "26.4.2"
```
### 🏗️ Architektur der zentralen Versionsverwaltung
```
```plaintext
docker/
├── versions.toml # 🎯 Single Source of Truth
├── build-args/ # Auto-generierte Environment Files
@@ -118,10 +122,11 @@ docker/
### 📊 Hierarchische Versionsverwaltung
#### 1. **Globale Versionen** (`docker/build-args/global.env`)
Verwendet von **allen** Dockerfiles:
```bash
# --- Build Tools ---
GRADLE_VERSION=9.0.0
GRADLE_VERSION=9.1.0
JAVA_VERSION=21
# --- Build Metadata ---
@@ -136,7 +141,7 @@ ECLIPSE_TEMURIN_JRE_VERSION=21-jre-alpine
# --- Monitoring & Infrastructure Services ---
DOCKER_PROMETHEUS_VERSION=v2.54.1
DOCKER_GRAFANA_VERSION=11.3.0
DOCKER_KEYCLOAK_VERSION=26.0.7
DOCKER_KEYCLOAK_VERSION=26.4.2
```
#### 2. **Kategorie-spezifische Versionen**
@@ -151,8 +156,8 @@ MEMBERS_SERVICE_PORT=8083
**Clients** (`docker/build-args/clients.env`):
```bash
NODE_VERSION=20.11.0
NGINX_VERSION=1.25-alpine
NODE_VERSION=22.21.0
NGINX_VERSION=1.28.0-alpine
WEB_APP_PORT=4000
DESKTOP_APP_VNC_PORT=5901
```
@@ -201,7 +206,7 @@ AUTH_SERVER_PORT=8087
./scripts/docker-versions-update.sh update grafana 11.3.0
# Keycloak auf neueste Version upgraden
./scripts/docker-versions-update.sh update keycloak 26.0.7
./scripts/docker-versions-update.sh update keycloak 26.4.2
# Alle Environment-Dateien synchronisieren
./scripts/docker-versions-update.sh sync
@@ -210,12 +215,13 @@ AUTH_SERVER_PORT=8087
## 🎯 Für AI-Assistenten: Architektur-Schnellreferenz
### Service-Kategorien
- **Infrastructure:** PostgreSQL, Redis, Keycloak, Kafka, Zookeeper, Consul
- **Infrastructure:** PostgresQL, Redis, Keycloak, Kafka, Zookeeper, Consul
- **Application:** API Gateway, Auth Server, Monitoring Server, Ping Service
- **Clients:** Web App (Port 3000), Desktop App
- **Monitoring:** Prometheus (9090), Grafana (3000), Zipkin, Nginx
### Wichtige Befehle
```bash
# Service-Status prüfen
docker-compose ps
@@ -232,6 +238,7 @@ docker-compose restart <service-name>
```
### Zentrale Konfigurationsdateien
- `docker/versions.toml` - Alle Versionen
- `docker-compose.yml` - Haupt-Services
- `docker-compose.clients.yml` - Client-Anwendungen
@@ -240,6 +247,7 @@ docker-compose restart <service-name>
---
**Navigation:**
- [master-guideline](../../master-guideline.md) – Hauptrichtlinie für das Projekt
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Production](./docker-production.md) - Production-Deployment
.junie/guidelines/technology-guides/docker/docker-development.md
+21 -9
View File
@@ -1,6 +1,7 @@
# Docker-Development Workflow
---
guideline_type: "technology"
scope: "docker-development"
audience: ["developers", "ai-assistants"]
@@ -8,10 +9,16 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "docker-architecture.md"]
related_files: ["docker-compose.yml", "docker-compose.override.yml", "Makefile"]
ai_context: "Entwicklungs-Workflow, Debugging und lokale Entwicklungsumgebung mit Docker"
---
## 🛠️ Development-Workflow
> **📖 Hinweis:** Für einen allgemeinen Überblick über die Docker-Infrastruktur
> siehe [docker-overview](docker-overview.md).
> Für Details zur Container-Architektur siehe [docker-architecture](docker-architecture.md).
> Für Production-Deployment siehe [docker-production](docker-production.md).
### Schnellstart-Befehle
```bash
@@ -116,15 +123,16 @@ curl -s http://localhost:8080/actuator/health | jq
### Häufige Entwicklungsaufgaben
| Aufgabe | Befehl | Beschreibung |
|---------|---------|--------------|
| Umgebung starten | `make dev-up` | Alle Services für Development |
| Service debuggen | `docker-compose exec <service> sh` | Shell im Container |
| Logs verfolgen | `docker-compose logs -f <service>` | Live-Logs anzeigen |
| Service neu bauen | `make service-build SERVICE=<name>` | Einzelnen Service rebuilden |
| Health-Check | `curl localhost:<port>/actuator/health` | Service-Status prüfen |
| Aufgabe | Befehl | Beschreibung |
|-------------------|-----------------------------------------|-------------------------------|
| Umgebung starten | `make dev-up` | Alle Services für Development |
| Service debuggen | `docker-compose exec <service> sh` | Shell im Container |
| Logs verfolgen | `docker-compose logs -f <service>` | Live-Logs anzeigen |
| Service neu bauen | `make service-build SERVICE=<name>` | Einzelnen Service rebuilden |
| Health-Check | `curl localhost:<port>/actuator/health` | Service-Status prüfen |
### Development-URLs
- **Grafana:** http://localhost:3000 (admin/admin)
- **Prometheus:** http://localhost:9090
- **API Gateway:** http://localhost:8080
@@ -132,6 +140,7 @@ curl -s http://localhost:8080/actuator/health | jq
- **Keycloak:** http://localhost:8180
### Debug-Ports
- **Spring-Services:** 5005 (Standard Java Debug)
- **Web-App:** Hot-Reload über Volume-Mapping
- **Client-Apps:** Port 4000 (Web), 5901 (Desktop VNC)
@@ -139,6 +148,7 @@ curl -s http://localhost:8080/actuator/health | jq
### Troubleshooting Development
#### Container startet nicht
```bash
# Container-Status prüfen
docker-compose ps
@@ -154,6 +164,7 @@ docker-compose build --no-cache <service-name>
```
#### Port-Konflikte
```bash
# Ports prüfen
netstat -tulpn | grep :<port>
@@ -163,6 +174,7 @@ docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
```
#### Volume-Probleme
```bash
# Volumes prüfen
docker volume ls
@@ -177,5 +189,5 @@ docker-compose exec <service> ls -la /path/to/volume
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Production](./docker-production.md) - Production-Deployment
- [Docker-Monitoring](./docker-monitoring.md) - Observability
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
- [docker-monitoring](./docker-monitoring.md) - Observability
- [docker-troubleshooting](./docker-troubleshooting.md) - Problemlösung
.junie/guidelines/technology-guides/docker/docker-monitoring.md
+24 -19
View File
@@ -1,6 +1,7 @@
# Docker-Monitoring und Observability
---
guideline_type: "technology"
scope: "docker-monitoring"
audience: ["developers", "devops", "ai-assistants"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "docker-architecture.md"]
related_files: ["docker-compose.yml", "config/monitoring/*", "config/grafana/*", "config/prometheus/*"]
ai_context: "Monitoring-Setup, Prometheus-Metriken, Grafana-Dashboards, Health-Checks und Log-Aggregation"
---
## 📊 Monitoring und Observability
@@ -44,13 +46,13 @@ labels:
### Health Check Matrix
| Service | Endpoint | Erwartung | Timeout |
|---------|----------|-----------|---------|
| API Gateway | `/actuator/health` | `{"status":"UP"}` | 15s |
| Ping Service | `/actuator/health/readiness` | HTTP 200 | 3s |
| PostgreSQL | `pg_isready` | Connection OK | 5s |
| Redis | `redis-cli ping` | PONG | 5s |
| Keycloak | `/health/ready` | HTTP 200 | 5s |
| Service | Endpoint | Erwartung | Timeout |
|--------------|------------------------------|-------------------|---------|
| API Gateway | `/actuator/health` | `{"status":"UP"}` | 15s |
| Ping Service | `/actuator/health/readiness` | HTTP 200 | 3s |
| PostgreSQL | `pg_isready` | Connection OK | 5s |
| Redis | `redis-cli ping` | PONG | 5s |
| Keycloak | `/health/ready` | HTTP 200 | 5s |
### Log Aggregation
@@ -65,6 +67,7 @@ docker-compose logs --follow --tail=100 api-gateway | jq -r '.message'
## 🎯 AI-Assistenten: Monitoring-Schnellreferenz
### Monitoring-URLs
- **Grafana Dashboard:** http://localhost:3000 (admin/admin)
- **Prometheus Targets:** http://localhost:9090/targets
- **Prometheus Metrics:** http://localhost:9090/metrics
@@ -72,13 +75,13 @@ docker-compose logs --follow --tail=100 api-gateway | jq -r '.message'
### Wichtige Metrics
| Metric-Typ | Beispiel | Beschreibung |
|------------|----------|--------------|
| JVM Memory | `jvm_memory_used_bytes` | Speicherverbrauch Java-Services |
| HTTP Requests | `http_requests_total` | API-Request-Zähler |
| Database Connections | `hikaricp_connections` | Pool-Verbindungen |
| Kafka Lag | `kafka_consumer_lag` | Consumer-Verzögerung |
| Custom Business | `meldestelle_registrations_total` | Fachliche KPIs |
| Metric-Typ | Beispiel | Beschreibung |
|----------------------|-----------------------------------|---------------------------------|
| JVM Memory | `jvm_memory_used_bytes` | Speicherverbrauch Java-Services |
| HTTP Requests | `http_requests_total` | API-Request-Zähler |
| Database Connections | `hikaricp_connections` | Pool-Verbindungen |
| Kafka Lag | `kafka_consumer_lag` | Consumer-Verzögerung |
| Custom Business | `meldestelle_registrations_total` | Fachliche KPIs |
### Health-Check Befehle
@@ -115,6 +118,7 @@ docker-compose logs api-gateway | grep -i "took\|duration\|time"
### Dashboard-Setup
#### Infrastructure-Dashboard
```json
{
"dashboard": {
@@ -142,6 +146,7 @@ docker-compose logs api-gateway | grep -i "took\|duration\|time"
```
#### Application-Dashboard
```json
{
"dashboard": {
@@ -245,8 +250,8 @@ scrape_configs:
---
**Navigation:**
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Production](./docker-production.md) - Production-Deployment
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
- [docker-overview](./docker-overview.md) - Grundlagen und Philosophie
- [docker-architecture](./docker-architecture.md) - Container-Services und Struktur
- [docker-development](./docker-development.md) - Entwicklungsworkflow
- [docker-production](./docker-production.md) - Production-Deployment
- [docker-troubleshooting](./docker-troubleshooting.md) - Problemlösung
.junie/guidelines/technology-guides/docker/docker-overview.md
+11 -5
View File
@@ -1,6 +1,7 @@
# Docker-Overview und Philosophie
---
guideline_type: "technology"
scope: "docker-overview"
audience: ["developers", "ai-assistants", "devops"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["master-guideline.md"]
related_files: ["docker-compose.yml", "docker/versions.toml"]
ai_context: "Docker-Philosophie und allgemeine Prinzipien für das Meldestelle-Projekt"
---
## 🚀 Überblick und Philosophie
@@ -29,6 +31,7 @@ Das Meldestelle-Projekt implementiert eine **moderne, sicherheitsorientierte Con
> - Monitoring läuft unter `http://localhost:3001` (Grafana)
### Zentrale Dateien für AI-Referenz
- `docker/versions.toml` - Single Source of Truth für alle Versionen
- `docker-compose.yml` - Haupt-Service-Orchestrierung
- `scripts/docker-versions-update.sh` - Automatische Version-Updates
@@ -37,27 +40,30 @@ Das Meldestelle-Projekt implementiert eine **moderne, sicherheitsorientierte Con
## 📋 Docker-Guidelines Navigation
Für spezifische Docker-Themen siehe:
- [Docker-Architektur](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Production](./docker-production.md) - Production-Deployment
- [Docker-Monitoring](./docker-monitoring.md) - Observability und Überwachung
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
- [docker-architecture](./docker-architecture.md) - Container-Services und Struktur
- [docker-development](./docker-development.md) - Entwicklungsworkflow
- [docker-production](./docker-production.md) - Production-Deployment
- [docker-monitoring](./docker-monitoring.md) - Observability und Überwachung
- [docker-troubleshooting](./docker-troubleshooting.md) - Problemlösung
## Grundprinzipien
### Sicherheitsaspekte
- **Non-Root-Container**: Alle Container laufen mit dediziertem User
- **Minimale Base-Images**: Verwendung schlanker Images (Alpine, Distroless)
- **Security-Scans**: Regelmäßige Vulnerability-Checks
- **Network-Segmentierung**: Isolierte Docker-Networks
### Performance-Optimierung
- **Multi-Stage-Builds**: Schlanke Production-Images
- **Layer-Caching**: Optimale Build-Performance
- **Resource-Limits**: Definierte CPU/Memory-Constraints
- **Health-Checks**: Proaktive Service-Überwachung
### Wartbarkeit
- **Standardisierte Templates**: Konsistente Dockerfile-Struktur
- **Zentrale Konfiguration**: Environment-basierte Konfiguration
- **Dokumentation**: Umfassende README-Dateien pro Service
.junie/guidelines/technology-guides/docker/docker-production.md
+16 -12
View File
@@ -1,6 +1,7 @@
# Docker-Production Deployment
---
guideline_type: "technology"
scope: "docker-production"
audience: ["developers", "devops", "ai-assistants"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "docker-architecture.md"]
related_files: ["docker-compose.yml", "config/nginx/nginx.prod.conf", "config/ssl/*"]
ai_context: "Production-Deployment, Security-Hardening, SSL/TLS-Konfiguration und Ressourcenverwaltung"
---
## 🚀 Production-Deployment
@@ -136,12 +138,14 @@ services:
## 🎯 AI-Assistenten: Production-Schnellreferenz
### Production-Domains
- **API:** api.meldestelle.at (HTTPS)
- **Auth:** auth.meldestelle.at (HTTPS)
- **Monitoring:** monitor.meldestelle.at (HTTPS)
- **Metrics:** metrics.meldestelle.at (HTTPS)
### Security-Checkliste
- [ ] SSL/TLS-Zertifikate installiert und gültig
- [ ] Alle Passwörter mit `openssl rand -base64 32` generiert
- [ ] Nginx Security Headers konfiguriert
@@ -151,13 +155,13 @@ services:
### Production-Befehle
| Aufgabe | Befehl | Beschreibung |
|---------|---------|--------------|
| Zertifikat erneuern | `certbot renew` | Let's Encrypt Zertifikate |
| SSL-Status prüfen | `openssl s_client -connect api.meldestelle.at:443` | SSL-Verbindung testen |
| Resource-Usage | `docker stats` | Container-Ressourcen |
| Security-Scan | `docker scan <image>` | Vulnerability Check |
| Log-Rotation | `docker system prune -f` | Alte Logs bereinigen |
| Aufgabe | Befehl | Beschreibung |
|---------------------|----------------------------------------------------|---------------------------|
| Zertifikat erneuern | `certbot renew` | Let's Encrypt Zertifikate |
| SSL-Status prüfen | `openssl s_client -connect api.meldestelle.at:443` | SSL-Verbindung testen |
| Resource-Usage | `docker stats` | Container-Ressourcen |
| Security-Scan | `docker scan <image>` | Vulnerability Check |
| Log-Rotation | `docker system prune -f` | Alte Logs bereinigen |
### Environment-Variablen Validierung
@@ -219,8 +223,8 @@ curl -s https://monitor.meldestelle.at/api/health | jq '.database'
---
**Navigation:**
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Monitoring](./docker-monitoring.md) - Observability
- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung
- [docker-overview](./docker-overview.md) - Grundlagen und Philosophie
- [docker-architecture](./docker-architecture.md) - Container-Services und Struktur
- [docker-development](./docker-development.md) - Entwicklungsworkflow
- [docker-monitoring](./docker-monitoring.md) - Observability
- [docker-troubleshooting](./docker-troubleshooting.md) - Problemlösung
.junie/guidelines/technology-guides/docker/docker-troubleshooting.md
+17 -12
View File
@@ -1,6 +1,7 @@
# Docker-Troubleshooting und Best Practices
---
guideline_type: "technology"
scope: "docker-troubleshooting"
audience: ["developers", "devops", "ai-assistants"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["docker-overview.md", "docker-architecture.md", "docker-development.md"]
related_files: ["docker-compose.yml", "scripts/validate-docker-consistency.sh", "scripts/docker-versions-update.sh"]
ai_context: "Fehlerbehebung häufiger Docker-Probleme, Debug-Kommandos und umfassende Best Practices"
---
## 🔧 Troubleshooting
@@ -85,29 +87,32 @@ docker-compose logs -f --tail=50 SERVICE_NAME
### Häufige Befehle
| Problem | Befehl | Beschreibung |
|---------|---------|--------------|
| Port belegt | `netstat -tulpn \| grep :<port>` | Port-Nutzung prüfen |
| Service startet nicht | `docker-compose logs <service>` | Service-Logs anzeigen |
| Container hängt | `docker stats` | Ressourcenverbrauch |
| DNS-Probleme | `docker-compose exec <service> nslookup <target>` | DNS-Resolution testen |
| Disk voll | `docker system prune -a --volumes` | Cleanup durchführen |
| Problem | Befehl | Beschreibung |
|-----------------------|---------------------------------------------------|-----------------------|
| Port belegt | `netstat -tulpn \| grep :<port>` | Port-Nutzung prüfen |
| Service startet nicht | `docker-compose logs <service>` | Service-Logs anzeigen |
| Container hängt | `docker stats` | Ressourcenverbrauch |
| DNS-Probleme | `docker-compose exec <service> nslookup <target>` | DNS-Resolution testen |
| Disk voll | `docker system prune -a --volumes` | Cleanup durchführen |
### Debug-Workflows
#### Service startet nicht
1. `docker-compose ps` - Status prüfen
2. `docker-compose logs <service>` - Logs analysieren
3. `docker-compose exec <service> sh` - Container inspizieren
4. Health-Check-Endpoint testen
#### Performance-Probleme
1. `docker stats` - Ressourcenverbrauch
2. `docker-compose top` - Prozess-Übersicht
3. JVM-Parameter optimieren
4. Resource-Limits anpassen
#### Netzwerk-Probleme
1. `docker network ls` - Netzwerke auflisten
2. `docker-compose exec <service> ping <target>` - Connectivity testen
3. Consul Service-Discovery prüfen
@@ -292,8 +297,8 @@ docker-compose up -d && make test
---
**Navigation:**
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
- [Docker-Production](./docker-production.md) - Production-Deployment
- [Docker-Monitoring](./docker-monitoring.md) - Observability
- [docker-overview](./docker-overview.md) - Grundlagen und Philosophie
- [docker-architecture](./docker-architecture.md) - Container-Services und Struktur
- [docker-development](./docker-development.md) - Entwicklungsworkflow
- [docker-production](./docker-production.md) - Production-Deployment
- [docker-monitoring](./docker-monitoring.md) - Observability
.junie/guidelines/technology-guides/web-app-guideline.md
+26 -8
View File
@@ -1,6 +1,7 @@
# Client-App-Richtlinie (Compose Multiplatform)
---
guideline_type: "technology"
scope: "web-app-multiplatform"
audience: ["developers", "ai-assistants", "frontend-developers"]
@@ -8,6 +9,7 @@ last_updated: "2025-09-15"
dependencies: ["master-guideline.md", "project-standards/architecture-principles.md"]
related_files: ["client/build.gradle.kts", "client/src/commonMain/", "client/src/wasmJsMain/", "client/src/jvmMain/"]
ai_context: "Compose Multiplatform-Entwicklung, MVVM-Pattern, KMP-Architektur, Desktop- und Web-Client-Entwicklung"
---
## 1. Einleitung
@@ -25,11 +27,11 @@ Das Hauptziel ist die maximale Wiederverwendung von Code zwischen den Desktop- u
## 2. Grundprinzipien
### Deklarative UI mit Composables
### Deklarative UI mit Composable
Die gesamte Benutzeroberfläche wird als Baum von `@Composable`-Funktionen deklariert. Dies ist derselbe Ansatz, der auch bei Jetpack Compose für Android verwendet wird.
- **Zustandslosigkeit:** Composables sollten bevorzugt zustandslos sein. Sie erhalten Daten als Parameter und geben Ereignisse über Lambda-Funktionen (Callbacks) nach oben weiter.
- **Zustandslosigkeit:** Composable sollten bevorzugt zustandslos sein. Sie erhalten Daten als Parameter und geben Ereignisse über Lambda-Funktionen (Callbacks) nach oben weiter.
- **Wiederverwendbarkeit:** Erstellen Sie kleine, spezialisierte und wiederverwendbare Composables. Vermeiden Sie monolithische UI-Funktionen.
- **Vorschau:** Nutzen Sie `@Preview`-Annotationen (sofern von der IDE unterstützt), um UI-Komponenten isoliert zu entwickeln und zu visualisieren.
@@ -46,15 +48,18 @@ Der UI-Zustand (State) wird explizit verwaltet.
Das Styling erfolgt plattformspezifisch, aber mit gemeinsamen Prinzipien:
#### Gemeinsame Styling-Prinzipien (commonMain)
- **Compose Material Design**: Nutzen Sie Material3-Komponenten und Theming für konsistente UI.
- **Gemeinsame Designsystem**: Definieren Sie gemeinsame Farben, Typografie und Spacing in `commonMain`.
- **Gemeinsames Designsystem**: Definieren Sie gemeinsame Farben, Typografie und Spacing in `commonMain`.
- **Responsive Design**: Berücksichtigen Sie verschiedene Bildschirmgrößen (Desktop-Fenster vs. Browser-Viewports).
#### Web-spezifisches Styling (wasmJsMain)
- **CSS-Integration**: Web-spezifische Styling-Anforderungen können über CSS in den Resources behandelt werden.
- **Browser-Kompatibilität**: Berücksichtigen Sie Web-spezifische Rendering-Unterschiede.
#### Desktop-spezifisches Styling (jvmMain)
- **Native Look & Feel**: Desktop-Anwendungen sollten sich nativ anfühlen.
- **Fenster-Management**: Berücksichtigen Sie Desktop-spezifische UI-Patterns (Menüleisten, etc.).
@@ -71,12 +76,14 @@ fun AppTheme(content: @Composable () -> Unit) {
```
### Navigation
Die Navigation wird plattformunabhängig in `commonMain` implementiert:
- **ViewModel-basierte Navigation**: Ein `StateFlow` oder `mutableState` im ViewModel repräsentiert die aktuelle Route/Screen.
- **Gemeinsamer Router**: Ein zentraler `Router`-Composable in `commonMain` reagiert auf Zustandsänderungen und rendert den entsprechenden Screen.
- **Plattformspezifische Einstiegspunkte**: Desktop und Web haben separate `main.kt`-Dateien, aber nutzen denselben gemeinsamen App-Composable.
## 3. Projekt- und Code-Struktur
Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und plattformspezifischer Implementation (`jvmMain`, `wasmJsMain`) getrennt.
### Source Sets
@@ -89,12 +96,12 @@ Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und
- **`client/src/jvmMain`** (Desktop-Plattform):
- **`main.kt`**: Der Einstiegspunkt der Desktop-Anwendung.
- **Desktop-spezifische Code**: Plattformspezifische Implementierungen und Integrationen.
- **Desktop-spezifischer Code**: Plattformspezifische Implementierungen und Integrationen.
- **Desktop Dependencies**: `compose.desktop.currentOs`, Coroutines für Swing.
- **`client/src/wasmJsMain`** (Web-Plattform):
- **`main.kt`**: Der Einstiegspunkt der Web-Anwendung (WebAssembly).
- **Web-spezifische Code**: Browser-spezifische Implementierungen.
- **Web-spezifischer Code**: Browser-spezifische Implementierungen.
- **Platform-spezifische Implementierungen**: Web-APIs und Browser-Integrationen.
- **`client/src/wasmJsMain/resources`**:
@@ -102,6 +109,7 @@ Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und
- **Statische Assets**: Bilder, Schriftarten und andere statische Dateien für die Web-Version.
### Shared Module Integration
- **`core/commonMain`** (oder äquivalente `shared`-Module):
- **Repositories/Services**: Code für den Datenzugriff (z.B. Ktor-HTTP-Clients zum Aufrufen des Backends).
- **Business-Logik**: Plattformunabhängige Geschäftslogik, die von allen Client-Plattformen genutzt wird.
@@ -109,6 +117,7 @@ Die Codebasis ist klar zwischen plattformunabhängiger Logik (`commonMain`) und
## 4. Entwicklung und Ausführung
### Desktop-Entwicklung
Für die Desktop-Anwendung stehen folgende Gradle-Tasks zur Verfügung:
```shell script
@@ -123,6 +132,7 @@ Für die Desktop-Anwendung stehen folgende Gradle-Tasks zur Verfügung:
```
### Web-Entwicklung mit Hot-Reload
Für die Web-Anwendung mit automatischer Neuladung bei Änderungen:
```shell script
@@ -131,6 +141,7 @@ Für die Web-Anwendung mit automatischer Neuladung bei Änderungen:
```
#### Docker-Setup für Web-Entwicklung
Das Docker-Setup ist spezifisch für die Web-Entwicklung konfiguriert (wie in `README-DOCKER.md` beschrieben):
```shell script
@@ -144,26 +155,31 @@ Der Dienst ist dann unter dem in der `docker-compose.clients.yml` konfigurierten
### Produktions-Builds
#### Desktop-Distribution
```shell script
# Erstellt native Distributionen für alle konfigurierten Plattformen
./gradlew :client:packageDistributionForCurrentOS
```
#### Web-Distribution
```shell script
# Erstellt optimierte WebAssembly-Artefakte für die Produktion
./gradlew :client:wasmJsBrowserDistribution
```
Das Docker-Image für die Web-Produktion (`Dockerfile` im `client`-Verzeichnis) sollte den `wasmJsBrowserDistribution`-Task nutzen, um die finalen Artefakte zu bauen.
## 5. Plattformspezifische Besonderheiten
### Desktop (jvmMain)
- **Fenster-Management**: Nutzen Sie Compose Desktop-APIs für Fensteroperationen.
- **System-Integration**: Zugriff auf Desktop-spezifische Features (Dateisystem, Notifications, etc.).
- **Performance**: Desktop-Apps können mehr Ressourcen nutzen als Web-Apps.
### Web (wasmJsMain)
- **Browser-APIs**: Zugriff auf Web-APIs erfolgt über `external`-Deklarationen.
- **Bundle-Size**: Achten Sie auf die Größe der WebAssembly-Bundles für optimale Ladezeiten.
- **SEO und Accessibility**: Berücksichtigen Sie Web-spezifische Anforderungen.
@@ -171,17 +187,20 @@ Das Docker-Image für die Web-Produktion (`Dockerfile` im `client`-Verzeichnis)
## 6. Dos and Don'ts
### Multiplatform Best Practices
- **DO**: Die gesamte UI-Logik (State-Management, Datenabruf, Validierung) in `commonMain` implementieren.
- **DO**: Kleine, wiederverwendbare und zustandslose Composables in `commonMain` erstellen.
- **DO**: Kleine wiederverwendbare und zustandslose Composable in `commonMain` erstellen.
- **DO**: Material3 und gemeinsames Theming für konsistente UI zwischen Plattformen verwenden.
- **DO**: Events von der UI über Lambda-Funktionen an die ViewModels in `commonMain` weiterleiten.
- **DO**: Plattformspezifische Features über `expect`/`actual`-Mechanismus abstrahieren.
### Platform-Specific Guidelines
- **DO** (Desktop): Native Look & Feel und Desktop-UI-Patterns verwenden.
- **DO** (Web): Web-Standards und Accessibility-Guidelines befolgen.
### Don'ts
- **DON'T**: Geschäftslogik, API-Aufrufe oder komplexe Zustandsmanipulationen direkt in `@Composable`-Funktionen schreiben.
- **DON'T**: Plattformspezifische Code direkt in `commonMain` verwenden ohne `expect`/`actual`.
- **DON'T** (Web): Den DOM direkt manipulieren. Compose Multiplatform verwaltet das Rendering. Falls Interaktion mit externen Bibliotheken nötig ist, nutzen Sie `external`-Mechanismen sauber gekapselt.
@@ -190,9 +209,8 @@ Das Docker-Image für die Web-Produktion (`Dockerfile` im `client`-Verzeichnis)
---
**Navigation:**
- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien
- [Master-Guideline](../master-guideline.md) - übergeordnete Projektrichtlinien
- [Architecture-Principles](../project-standards/architecture-principles.md) - Architektur-Grundsätze
- [Coding-Standards](../project-standards/coding-standards.md) - Code-Qualitätsstandards
- [Testing-Standards](../project-standards/testing-standards.md) - Test-Qualitätssicherung
- [Trace-Bullet-Guideline](../process-guides/trace-bullet-guideline.md) - Entwicklungszyklus