diff --git a/.gemini/README.md b/.gemini/README.md new file mode 100644 index 00000000..6b27e4d1 --- /dev/null +++ b/.gemini/README.md @@ -0,0 +1,35 @@ +# Gemini – Projekt-Entry-Point + +Dieses Verzeichnis enthält die **kurze Start-Anweisung** für Gemini (parallel/extern), damit Ergebnisse konsistent zur Projektstrategie entstehen. + +## Single Source of Truth + +* **Projektwissen & Entscheidungen:** `docs/` +* `.junie/` ist nur Tooling/Guardrails, keine zweite Wahrheit. + +## Startreihenfolge (Pflicht) + +1. `docs/README.md` +2. `docs/03_Agents/README.md` (Artefakt-Vertrag) +3. Relevanter technischer Bereich (pro System): + * Architektur: `docs/01_Architecture/` + * Backend (Services): `docs/04_Backend/Services/` + * Frontend: `docs/05_Frontend/` + * Infrastruktur: `docs/06_Infrastructure/` + +## Output-Regel (Anti-Wissensverlust) + +Jede Gemini-Session endet mit **genau einem** Artefakt in `docs/`: + +* `ADR` (`docs/01_Architecture/adr/`) +* `Reference` (passender Bereich) +* `How-to / Runbook` (passender Bereich) +* `Journal Entry` (`docs/99_Journal/`) + +## Technische Wahrheit „pro System“ + +Für Services gilt: Eine stabile, nicht-datierte Seite unter `docs/04_Backend/Services/` ist der Einstieg. +Zeitlich datierte Detailanalysen liegen unter `docs/90_Reports/`. + +Beispiel: +* Ping-Service: `docs/04_Backend/Services/ping-service.md` diff --git a/.junie/AUTOMATION-FEATURES.md b/.junie/AUTOMATION-FEATURES.md deleted file mode 100644 index 7fde1970..00000000 --- a/.junie/AUTOMATION-FEATURES.md +++ /dev/null @@ -1,410 +0,0 @@ -# Meldestelle Guidelines Automatisierung - Feature-Dokumentation - -**Version:** 1.0.0 -**Datum:** 15. September 2025 -**Status:** ✅ Vollständig implementiert - ---- - -## 🎯 Überblick - -Basierend auf den vorherigen Optimierungen wurde das `.junie` Guidelines-System um umfassende Automatisierungsfeatures erweitert. Diese Dokumentation beschreibt alle neuen Tools, Scripts und Integrationen für die automatische Validierung, Template-Erstellung und CI/CD-Pipeline-Integration. - -## 🛠️ Implementierte Features - -### 1. 🔗 Automatisierte Link-Validierung - -**Script:** `.junie/scripts/validate-links.sh` - -#### Funktionen -- **Cross-Referenz-Validierung** basierend auf `cross-refs.json` -- **YAML-Metadaten-Konsistenz** Prüfung -- **Markdown-Link-Validierung** (intern und extern) -- **Template-Struktur-Validierung** - -#### Verwendung - -```bash -# Vollständige Validierung -./.junie/scripts/validate-links.sh - -# Schnelle Validierung (für Development) -./.junie/scripts/validate-links.sh --quick - -# Hilfe anzeigen -./.junie/scripts/validate-links.sh --help -``` - -#### Validierungs-Modi - -| Modus | Beschreibung | Verwendung | -|-------|--------------|------------| -| **Standard** | Vollständige Validierung aller Links und Strukturen | Production, vor Releases | -| **Quick** | Nur Cross-Referenzen und YAML-Metadaten | Development, häufige Checks | -| **Help** | Zeigt alle verfügbaren Optionen | Dokumentation | - -#### Ausgabe-Beispiel - -``` -🔍 Meldestelle Guidelines Link-Validierung -================================================== -✅ 'README.md' - Cross-Referenzen validiert -✅ 'master-guideline.md' - Cross-Referenzen validiert -✅ 'docker-overview.md' - Cross-Referenzen validiert -================================================== -📊 Validierungs-Ergebnisse: - Fehler: 0 - Warnungen: 0 -✅ Alle Validierungen erfolgreich! 🎉 -``` - -### 2. 📋 Template-System für neue Guidelines - -**Script:** `.junie/scripts/create-guideline.sh` - -#### Verfügbare Templates -- **Project-Standard** (`project-standard-template.md`) -- **Technology-Guide** (`technology-guideline-template.md`) -- **Process-Guide** (`process-guide-template.md`) - -#### Verwendung - -```bash -# Neue Project-Standard Guideline -./.junie/scripts/create-guideline.sh project-standard security-standards security-practices - -# Neue Technology-Guide Guideline -./.junie/scripts/create-guideline.sh technology monitoring-standards monitoring-best-practices - -# Neue Process-Guide Guideline -./.junie/scripts/create-guideline.sh process-guide deployment-workflow deployment-automation - -# Dry-Run (keine Dateien ändern) -./.junie/scripts/create-guideline.sh technology test-guide test-scope --dry-run -``` - -#### Template-Verarbeitung - -Das Script führt folgende Aktionen durch: - -1. **Template-Verarbeitung** - - Kopiert das entsprechende Template - - Ersetzt Platzhalter (`{{NAME}}`, `{{SCOPE}}`, `{{DATE}}`, `{{TYPE}}`) - - Generiert korrekte YAML-Metadaten - -2. **Automatische Integration** - - Platziert die Datei im korrekten Verzeichnis - - Führt Validierung der neuen Guideline durch - - Zeigt nächste Schritte für manuelle Updates - -3. **Qualitätssicherung** - - Prüft Template-Verfügbarkeit - - Verhindert Überschreibung bestehender Dateien - - Validiert die erstellte Guideline - -#### Template-Struktur - -Jedes Template enthält: -- **Standardisierte YAML-Header** mit Platzhaltern -- **Deutsche Lokalisierung** aller Metadaten -- **AI-Assistant-optimierte** Strukturen -- **Konsistente Navigation** Links -- **Vordefinierte Sektionen** für spezielle Guideline-Typen - -### 3. 🚀 CI/CD-Integration - -**GitHub Actions:** `.github/workflows/guidelines-validation.yml` - -#### Trigger-Ereignisse -- Push auf Guidelines-Dateien (`.junie/**/*.md`, `.junie/**/*.json`, `.junie/scripts/**`) -- Pull Requests mit Guidelines-Änderungen - -#### Validierungs-Pipeline - -```yaml -Jobs: - validate-guidelines: - - YAML-Header Validierung - - Cross-Referenzen und Links - - Versions-Konsistenz - - Template-Struktur - - JSON-Konfiguration - - Script-Berechtigungen - - Validierungs-Report - - advanced-link-check: - - Node.js markdown-link-check - - Erweiterte Link-Validierung - - Konfigurierbare Ignore-Patterns -``` - -#### Features der CI/CD-Integration - -- **Automatische Validierung** bei jedem Push/PR -- **Pull Request Kommentare** mit Validierungs-Reports -- **Multi-Stage Validierung** (Basic + Advanced) -- **Robuste Fehlerbehandlung** mit detaillierten Berichten -- **Konfigurierbare Link-Checks** für lokale URLs - -#### Beispiel-Report - -```markdown -# Guidelines Validation Report - -**Datum:** 2025-09-15 -**Commit:** abc123... -**Branch:** feature/new-guidelines - -## Zusammenfassung -- ✅ YAML-Syntax validiert -- ✅ Cross-Referenzen geprüft -- ✅ Template-Struktur validiert - -## Statistiken -- **Aktive Guidelines:** 14 -- **Templates verfügbar:** 3 -- **Validierungs-Scripts:** 3 -``` - -### 4. 🔒 Pre-commit Hook - -**Script:** `.junie/scripts/pre-commit-guidelines.sh` - -#### Installation - -```bash -# Automatische Installation (empfohlen) -ln -s ../../.junie/scripts/pre-commit-guidelines.sh .git/hooks/pre-commit - -# Manuelle Installation -cp .junie/scripts/pre-commit-guidelines.sh .git/hooks/pre-commit -chmod +x .git/hooks/pre-commit -``` - -#### Validierungs-Schritte - -1. **Change-Detection** - Erkennt Guidelines-Änderungen -2. **Staging-Area-Extraktion** - Validiert committete Dateien -3. **YAML-Syntax** - Prüft YAML-Header-Syntax -4. **Metadaten-Vollständigkeit** - Überprüft erforderliche Felder -5. **JSON-Validierung** - Prüft Konfigurationsdateien -6. **Datum-Aktualität** - Warnt bei veralteten Daten -7. **Script-Berechtigungen** - Validiert ausführbare Scripts -8. **Link-Validierung** - Schnelle Cross-Referenz-Checks - -#### Pre-commit Ausgabe - -``` -🔍 Pre-commit Guidelines Validation... -====================================== -📝 Geänderte Guidelines-Dateien: - - .junie/guidelines/master-guideline.md - - .junie/guidelines/README.md - -🔄 Extrahiere Staging-Area-Dateien... -📋 Prüfe YAML-Syntax... -🏷️ Prüfe erforderliche Metadaten... -🔧 Prüfe JSON-Konfiguration... -📅 Prüfe Datum-Aktualität... -🔗 Schnelle Link-Validierung... - -✅ Pre-commit Guidelines Validation erfolgreich! - - YAML-Syntax: OK - - Metadaten: OK - - JSON-Konfiguration: OK -🚀 Commit kann fortgesetzt werden... -``` - -## 🔧 Konfiguration und Anpassung - -### Link-Validierung Konfiguration - -**Datei:** `.junie/link-check-config.json` (automatisch erstellt) - -```json -{ - "ignorePatterns": [ - {"pattern": "^http://localhost"}, - {"pattern": "^https://localhost"}, - {"pattern": "^http://127.0.0.1"} - ], - "timeout": "10s", - "retryOn429": true, - "retryCount": 3 -} -``` - -### Cross-Referenz-Matrix - -**Datei:** `.junie/guidelines/_meta/cross-refs.json` - -```json -{ - "cross_references": { - "master-guideline.md": { - "references_to": ["project-standards/coding-standards.md"], - "referenced_by": ["README.md"] - } - }, - "validation_rules": { - "mandatory_metadata": ["guideline_type", "scope", "audience"], - "supported_audiences": ["developers", "ai-assistants", "devops"] - } -} -``` - -### Versions-Management - -**Datei:** `.junie/guidelines/_meta/versions.json` - -```json -{ - "guidelines": { - "master-guideline.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "master" - } - } -} -``` - -## 🎯 Workflow-Integration - -### Entwicklungs-Workflow - -1. **Lokale Entwicklung** - ```bash - # Neue Guideline erstellen - ./.junie/scripts/create-guideline.sh technology monitoring monitoring-setup - - # Lokale Validierung - ./.junie/scripts/validate-links.sh --quick - - # Commit (Pre-commit Hook aktiviert) - git add . && git commit -m "Add monitoring guideline" - ``` - -2. **CI/CD-Pipeline** - - Push triggert GitHub Actions Workflow - - Automatische Validierung aller Guidelines - - Pull Request erhält Validierungs-Report - - Merge nur bei erfolgreicher Validierung - -3. **Maintenance-Tasks** - ```bash - # Vollständige Validierung - ./.junie/scripts/validate-links.sh - - # Template-System testen - ./.junie/scripts/create-guideline.sh --help - - # Pre-commit Hook testen - ./.junie/scripts/pre-commit-guidelines.sh - ``` - -## 📈 Erfolgs-Metriken - -### Quantitative Verbesserungen - -| Metrik | Vorher | Nachher | Verbesserung | -|--------|--------|---------|--------------| -| **Manuelle Validierung** | 30 Min | 2 Min | 93% Reduktion | -| **Template-Erstellung** | 45 Min | 3 Min | 93% Reduktion | -| **Link-Konsistenz** | 70% | 100% | 30% Verbesserung | -| **CI/CD-Integration** | 0% | 100% | Vollautomatisiert | - -### Qualitative Verbesserungen - -- **🔄 Proaktive Fehlererkennung** vor Commit/Merge -- **📋 Konsistente Guideline-Struktur** durch Templates -- **🚀 Reduzierte Wartungszeit** durch Automatisierung -- **👥 Verbesserte Developer-Experience** durch sofortiges Feedback -- **🤖 AI-Assistant-Optimierung** durch strukturierte Validierung - -## 🚨 Troubleshooting - -### Häufige Probleme - -#### Pre-commit Hook schlägt fehl -```bash -# Problem: Script nicht ausführbar -chmod +x .junie/scripts/pre-commit-guidelines.sh - -# Problem: YAML-Syntax-Fehler -# Prüfe YAML-Header in betroffener Guideline -sed -n '/^---$/,/^---$/p' .junie/guidelines/problematic-file.md -``` - -#### Link-Validierung zeigt Fehler -```bash -# Vollständige Validierung mit Details -./.junie/scripts/validate-links.sh - -# Cross-Referenz-Matrix prüfen -jq . .junie/guidelines/_meta/cross-refs.json -``` - -#### Template-System funktioniert nicht -```bash -# Template-Verfügbarkeit prüfen -ls -la .junie/guidelines/_templates/ - -# Berechtigungen prüfen -chmod +x .junie/scripts/create-guideline.sh -``` - -#### GitHub Actions schlagen fehl -- Prüfe `.github/workflows/guidelines-validation.yml` Syntax -- Validiere lokale Scripts vor Push: `./junie/scripts/validate-links.sh` -- Überprüfe Branch-Protection-Rules - -### Debug-Commands - -```bash -# Script-Debugging aktivieren -bash -x .junie/scripts/validate-links.sh - -# YAML-Validierung einzelner Datei -python3 -c "import yaml; yaml.safe_load(open('file.yaml'))" - -# JSON-Syntax prüfen -jq empty .junie/guidelines/_meta/cross-refs.json - -# Git Hook Status -ls -la .git/hooks/pre-commit -``` - -## 🔮 Nächste Entwicklungsstufe - -### Geplante Erweiterungen - -1. **Erweiterte Link-Validierung** - - External Link Health Checks - - Automated Link Rotation Detection - - Performance Metrics für Validation - -2. **Template-System V2** - - Interaktive Template-Auswahl - - Custom Template Support - - Automated Cross-Reference Updates - -3. **CI/CD Enhancements** - - Automated Performance Benchmarking - - Integration mit Code Quality Gates - - Notification System für Teams - -4. **Monitoring Dashboard** - - Guidelines Health Metrics - - Usage Analytics - - Automated Reporting - ---- - -**Implementierung Status:** ✅ Vollständig -**Testing:** ✅ Erfolgreich -**Dokumentation:** ✅ Umfassend -**CI/CD Integration:** ✅ Einsatzbereit - -Die Meldestelle Guidelines Automatisierung stellt einen modernen Standard für selbst-validierende Dokumentationssysteme dar und kann als Referenz-Implementierung für andere Projekte verwendet werden. diff --git a/.junie/IMPLEMENTATION-REPORT.md b/.junie/IMPLEMENTATION-REPORT.md deleted file mode 100644 index 7d191cb6..00000000 --- a/.junie/IMPLEMENTATION-REPORT.md +++ /dev/null @@ -1,348 +0,0 @@ -# Meldestelle Guidelines Automatisierung - Abschluss-Report - -**Projekt:** Guidelines Automatisierung & CI/CD-Integration -**Version:** 1.0.0 -**Abschlussdatum:** 15. September 2025 -**Status:** ✅ Vollständig implementiert und getestet - ---- - -## 🎯 Projektziele und Erfolg - -### Ursprüngliche Anforderungen -1. ✅ Automatisierte Link-Validierung implementieren -2. ✅ Template-System erweitern -3. ✅ CI/CD-Integration vorbereiten -4. ✅ Testing und Dokumentation - -**Alle Ziele wurden erfolgreich erreicht und übertroffen.** - ---- - -## 🛠️ Implementierte Lösungen - -### 1. 🔗 Automatisierte Link-Validierung - -**Implementiert:** `.junie/scripts/validate-links.sh` - -#### Features -- ✅ Cross-Referenz-Validierung basierend auf `cross-refs.json` -- ✅ YAML-Metadaten-Konsistenz-Prüfung -- ✅ Schnell-Modus für häufige Validierungen -- ✅ Umfassende Fehlerberichterstattung -- ✅ Template-Struktur-Validierung - -#### Testergebnisse -``` -📊 Validierungs-Ergebnisse: - Fehler: 0 - Warnungen: 0 -✅ Alle Validierungen erfolgreich! 🎉 -``` - -**Erfolg:** 100% Validierung aller 14 aktiven Guidelines ohne Fehler. - -### 2. 📋 Template-System für neue Guidelines - -**Implementiert:** `.junie/scripts/create-guideline.sh` - -#### Templates -- ✅ **Project-Standard-Template** - Vollständig funktionsfähig -- ✅ **Technology-Guide-Template** - Getestet und validiert -- ✅ **Process-Guide-Template** - Einsatzbereit - -#### Funktionalitäten -- ✅ **Dry-Run-Modus** für sichere Tests -- ✅ **Automatische Platzhalter-Ersetzung** -- ✅ **Deutsche Lokalisierung** aller Metadaten -- ✅ **Integrierte Validierung** neuer Guidelines -- ✅ **Benutzerfreundliche Hilfe-Texte** - -#### Test-Verifikation -``` -✅ Neue Guideline erstellt: .junie/guidelines/technology-guides/monitoring-standards.md -✅ Validierung erfolgreich! -✅ Guideline-Erstellung erfolgreich abgeschlossen! -``` - -**Erfolg:** Template-System reduziert Erstellungszeit um 93% (45 Min → 3 Min). - -### 3. 🚀 CI/CD-Integration - -**Implementiert:** `.github/workflows/guidelines-validation.yml` - -#### Pipeline-Features -- ✅ **Multi-Stage Validierung** (Basic + Advanced) -- ✅ **YAML-Syntax-Validierung** mit Python -- ✅ **Cross-Referenz-Checks** -- ✅ **Versions-Konsistenz-Prüfung** -- ✅ **Template-Struktur-Validierung** -- ✅ **JSON-Konfiguration-Checks** -- ✅ **Script-Berechtigungen-Validierung** -- ✅ **Erweiterte Link-Checks** mit Node.js -- ✅ **Pull Request Kommentare** mit detaillierten Reports - -#### Trigger-Konfiguration -- ✅ Push auf `.junie/**/*.md`, `.junie/**/*.json`, `.junie/scripts/**` -- ✅ Pull Requests mit Guidelines-Änderungen -- ✅ Robuste Fehlerbehandlung mit Exit-Codes - -**Erfolg:** Vollautomatisierte CI/CD-Pipeline für proaktive Qualitätssicherung. - -### 4. 🔒 Pre-commit Hook - -**Implementiert:** `.junie/scripts/pre-commit-guidelines.sh` - -#### Validierungs-Pipeline -- ✅ **Change-Detection** - Erkennt Guidelines-Änderungen -- ✅ **Staging-Area-Extraktion** - Validiert committete Dateien -- ✅ **YAML-Syntax-Prüfung** - Verhindert Syntax-Fehler -- ✅ **Metadaten-Vollständigkeit** - Überprüft erforderliche Felder -- ✅ **JSON-Validierung** - Prüft Konfigurationsdateien -- ✅ **Datum-Aktualität** - Warnt bei veralteten Daten -- ✅ **Script-Berechtigungen** - Validiert ausführbare Scripts -- ✅ **Link-Validierung** - Schnelle Cross-Referenz-Checks - -#### Installation -```bash -# Einfache Symlink-Installation -ln -s ../../.junie/scripts/pre-commit-guidelines.sh .git/hooks/pre-commit -``` - -**Erfolg:** Proaktive lokale Validierung verhindert fehlerhafte Commits. - ---- - -## 📊 Quantitative Erfolgs-Metriken - -### Performance-Verbesserungen - -| Prozess | Vorher | Nachher | Verbesserung | -|---------|--------|---------|--------------| -| **Manuelle Guidelines-Validierung** | 30 Min | 2 Min | 93% Zeitreduktion | -| **Neue Guideline erstellen** | 45 Min | 3 Min | 93% Zeitreduktion | -| **Link-Konsistenz-Rate** | 70% | 100% | 30% Verbesserung | -| **YAML-Fehler vor Commit** | Häufig | 0% | 100% Eliminierung | -| **Template-Konsistenz** | 60% | 100% | 40% Verbesserung | - -### System-Metriken - -| Metrik | Wert | Bemerkung | -|--------|------|-----------| -| **Aktive Guidelines** | 14 | Alle vollständig validiert | -| **Verfügbare Templates** | 3 | Project, Technology, Process | -| **Validierungs-Scripts** | 3 | Alle funktionsfähig | -| **CI/CD-Jobs** | 2 | Basic + Advanced Validation | -| **Automatisierungsgrad** | 95% | Nur minimale manuelle Schritte | - -### Qualitäts-Metriken - -| Bereich | Status | Beschreibung | -|---------|--------|--------------| -| **Cross-Referenz-Integrität** | ✅ 100% | Alle Links validiert | -| **YAML-Metadaten-Konsistenz** | ✅ 100% | Einheitliche Struktur | -| **Template-Adherence** | ✅ 100% | Alle Guidelines folgen Standards | -| **CI/CD-Pipeline-Stabilität** | ✅ 100% | Robuste Fehlerbehandlung | -| **Dokumentations-Abdeckung** | ✅ 100% | Umfassende Benutzer-Docs | - ---- - -## 🏗️ Architektur-Übersicht - -### Implementierte Struktur - -``` -.junie/ -├── AUTOMATION-FEATURES.md # 🆕 Umfassende Feature-Dokumentation -├── IMPLEMENTATION-REPORT.md # 🆕 Dieser Abschluss-Report -├── OPTIMIZATION-SUMMARY.md # ✓ Vorherige Optimierungen -├── guidelines/ -│ ├── _meta/ # ✓ Zentrale Metadaten-Verwaltung -│ │ ├── versions.json # ✓ Versionskontrolle -│ │ └── cross-refs.json # ✓ Cross-Referenz-Matrix -│ ├── _templates/ # 🆕 Template-System -│ │ ├── project-standard-template.md -│ │ ├── technology-guideline-template.md -│ │ └── process-guide-template.md -│ └── _archived/ # ✓ Archivierte Guidelines -└── scripts/ # 🆕 Automatisierungs-Scripts - ├── validate-links.sh # 🆕 Link-Validierung - ├── create-guideline.sh # 🆕 Template-System - └── pre-commit-guidelines.sh # 🆕 Pre-commit Hook - -.github/workflows/ -└── guidelines-validation.yml # 🆕 CI/CD-Pipeline -``` - -### Integration-Punkte - -1. **Lokale Entwicklung** - - Pre-commit Hook → Sofortiges Feedback - - Validate-Links Script → Schnelle Validierung - - Template-System → Effiziente Guideline-Erstellung - -2. **CI/CD-Pipeline** - - GitHub Actions → Automatische Validierung - - Pull Request Comments → Transparente Reports - - Multi-Stage Validation → Umfassende Qualitätskontrolle - -3. **Maintainer-Tools** - - Cross-Reference-Matrix → Abhängigkeits-Management - - Versions-Management → Konsistente Updates - - Template-Verwaltung → Standardisierte Strukturen - ---- - -## 🎉 Qualitative Verbesserungen - -### Entwickler-Experience - -#### Vorher -- ❌ Manuelle Link-Validierung fehleranfällig -- ❌ Inkonsistente Guideline-Strukturen -- ❌ Zeitaufwändige Template-Erstellung -- ❌ Späte Fehlerentdeckung bei CI/CD -- ❌ Keine automatisierte Qualitätskontrolle - -#### Nachher -- ✅ **Vollautomatisierte Validierung** mit sofortigem Feedback -- ✅ **Konsistente Template-basierte** Guideline-Erstellung -- ✅ **Proaktive Fehlererkennung** vor Commit -- ✅ **Transparente CI/CD-Integration** mit detaillierten Reports -- ✅ **Selbst-validierende** Dokumentationsarchitektur - -### AI-Assistant-Optimierung - -#### Verbesserungen -- ✅ **Strukturierte Metadaten** für bessere Kontextverständnis -- ✅ **Deutsche ai_context-Felder** für lokalisierte Prompts -- ✅ **Konsistente Navigation-Pfade** zwischen Guidelines -- ✅ **Validierte Cross-Referenzen** für zuverlässige Verweise -- ✅ **Template-basierte Konsistenz** für vorhersagbare Strukturen - -### Wartbarkeit - -#### Erreichte Ziele -- ✅ **Single Source of Truth** für alle Konfigurationen -- ✅ **Modulare Script-Architektur** für einfache Erweiterungen -- ✅ **Automatisierte Konsistenz-Checks** reduzieren manuellen Aufwand -- ✅ **Umfassende Dokumentation** für selbsterklärende Systeme -- ✅ **Future-proof Architektur** für weitere Optimierungen - ---- - -## 🔧 Deployment und Installation - -### Sofort verfügbar -- ✅ **Alle Scripts** sind ausführbar und getestet -- ✅ **GitHub Actions Workflow** ist einsatzbereit -- ✅ **Templates** sind funktionsfähig -- ✅ **Dokumentation** ist vollständig - -### Installation für Entwickler - -```bash -# 1. Pre-commit Hook installieren (empfohlen) -ln -s ../../.junie/scripts/pre-commit-guidelines.sh .git/hooks/pre-commit - -# 2. Schnelle Validierung testen -./.junie/scripts/validate-links.sh --quick - -# 3. Template-System ausprobieren -./.junie/scripts/create-guideline.sh --help - -# 4. Erste neue Guideline erstellen -./.junie/scripts/create-guideline.sh technology monitoring monitoring-setup -``` - -### Automatische Aktivierung -- ✅ **GitHub Actions** werden automatisch bei Push/PR getriggert -- ✅ **Validierungs-Reports** erscheinen automatisch in Pull Requests -- ✅ **Link-Checks** laufen bei jeder Guidelines-Änderung - ---- - -## 📈 Geschäftswert und ROI - -### Zeitersparnis (pro Monat) -- **Manuelle Validierung:** 8h → 0.5h = **7.5h gespart** -- **Guideline-Erstellung:** 6h → 0.5h = **5.5h gespart** -- **Fehlerkorrektur:** 4h → 0.5h = **3.5h gespart** -- **Gesamt:** **16.5h/Monat** Zeitersparnis - -### Qualitätsverbesserungen -- **Zero-Defect-Guidelines:** 100% Validierung vor Produktiveinsatz -- **Konsistente Dokumentation:** Einheitliche Strukturen und Metadaten -- **Proaktive Qualitätskontrolle:** Fehler werden vor Integration erkannt -- **Automatisierte Compliance:** Guidelines folgen automatisch Standards - -### Skalierbarkeit -- **Template-System:** Neue Guidelines in 3 Minuten statt 45 Minuten -- **Validierungs-Pipeline:** Skaliert automatisch mit Guidelines-Anzahl -- **CI/CD-Integration:** Null zusätzlicher Aufwand bei Team-Wachstum -- **Maintenance-Overhead:** 95% Reduktion durch Automatisierung - ---- - -## 🚀 Nächste Schritte und Empfehlungen - -### Sofortmaßnahmen (empfohlen) -1. **Pre-commit Hook installieren** für alle Entwickler -2. **GitHub Actions aktivieren** (bereits konfiguriert) -3. **Template-System nutzen** für neue Guidelines -4. **Validierung integrieren** in täglichen Workflow - -### Mittelfristige Optimierungen -1. **External Link Health Checks** für vollständige Link-Validierung -2. **Performance Metrics** für Validierungs-Geschwindigkeit -3. **Custom Template Support** für spezielle Anwendungsfälle -4. **Automated Cross-Reference Updates** für Metadaten-Sync - -### Langfristige Vision -1. **Guidelines Health Dashboard** für Management-Übersicht -2. **Integration mit Code Quality Gates** für Release-Pipeline -3. **AI-assisted Guideline Generation** basierend auf Code-Patterns -4. **Multi-Project Template Sharing** für Organisation-weite Standards - ---- - -## 🎯 Fazit und Bewertung - -### Projekt-Erfolg: ✅ Überragend - -**Alle ursprünglichen Ziele wurden nicht nur erreicht, sondern erheblich übertroffen:** - -1. **Automatisierte Link-Validierung** → **Vollständiges Validierungs-Framework** -2. **Template-System erweitern** → **Umfassendes Template-Ecosystem** -3. **CI/CD-Integration vorbereiten** → **Production-ready Pipeline** -4. **Testing und Dokumentation** → **Beispielhafte Dokumentations-Architektur** - -### Technische Exzellenz - -- **Zero-Defect Implementation:** Alle Scripts funktionieren fehlerfrei -- **Comprehensive Testing:** Alle Komponenten wurden erfolgreich getestet -- **Future-Proof Architecture:** Erweiterbar und wartbar designed -- **Documentation Excellence:** Umfassende Benutzer- und Entwickler-Docs - -### Geschäftswert - -- **93% Zeitreduktion** bei Guidelines-Management-Aufgaben -- **100% Automatisierung** der Qualitätskontrolle -- **Null zusätzlicher Maintenance-Overhead** durch selbst-validierende Architektur -- **Skalierbare Foundation** für zukünftiges Wachstum - -### Innovationsgrad - -**Diese Implementierung stellt einen neuen Standard dar für:** -- Selbst-validierende Dokumentationssysteme -- Template-basierte Content-Generierung -- CI/CD-integrierte Qualitätskontrolle -- AI-Assistant-optimierte Strukturen - ---- - -**Die Meldestelle Guidelines Automatisierung ist damit erfolgreich abgeschlossen und produktionsreif deployiert. Das System kann als Referenz-Implementierung für andere Projekte dienen und demonstriert Best Practices für moderne Dokumentations-Infrastrukturen.** - -**Status:** ✅ **ERFOLGREICH ABGESCHLOSSEN** -**Qualität:** ⭐⭐⭐⭐⭐ **EXZELLENT** -**Bereit für:** 🚀 **PRODUCTION DEPLOYMENT** diff --git a/.junie/OPTIMIZATION-SUMMARY.md b/.junie/OPTIMIZATION-SUMMARY.md deleted file mode 100644 index 4c4b59df..00000000 --- a/.junie/OPTIMIZATION-SUMMARY.md +++ /dev/null @@ -1,171 +0,0 @@ -# .junie Guidelines Optimierung - Zusammenfassung - -**Datum:** 15. September 2025 -**Status:** ✅ Vollständig implementiert -**Bearbeitet von:** Junie AI-Assistant - ---- - -## 🎯 Zielsetzung - -Basierend auf der vorherigen Analyse wurden alle identifizierten Probleme des `.junie` Guidelines-Systems behoben und eine moderne, wartbare Dokumentationsarchitektur implementiert. - -## 📊 Quantitative Verbesserungen - -### Dateigröße und Redundanz -- **Eliminiert:** 69KB redundante Dokumentation (docker-guideline.md) -- **Reduziert:** 95% Wartungsredundanz durch Elimination doppelter Inhalte -- **Archiviert:** 1 große monolithische Datei → Modularisierung beibehalten - -### Konsistenz und Standardisierung -- **Standardisiert:** 14 aktive Guidelines mit einheitlichen YAML-Headern -- **Vereinheitlicht:** Alle Daten auf Version 2.1.0 (2025-09-15) -- **Übersetzt:** Alle ai_context-Felder ins Deutsche -- **Korrigiert:** YAML-Syntax-Fehler in README.md - -## 🏗️ Strukturelle Verbesserungen - -### Neue Architektur-Komponenten - -```plaintext -.junie/guidelines/ -├── _archived/ # 🆕 Archivierte Guidelines -│ └── docker-guideline-v3.0.1-archived-2025-09-15.md -├── _meta/ # 🆕 Zentrale Metadaten-Verwaltung -│ ├── versions.json # 🆕 Zentrale Versionsverwaltung -│ └── cross-refs.json # 🆕 Cross-Referenz-Matrix -├── _templates/ # 🆕 Template-System -│ └── technology-guideline-template.md # 🆕 Standard-Template -├── README.md (optimiert) -├── master-guideline.md (optimiert) -├── project-standards/ (4 Guidelines optimiert) -├── technology-guides/ -│ ├── web-app-guideline.md (optimiert) -│ └── docker/ (6 Guidelines optimiert) -└── process-guides/ (1 Guideline optimiert) -``` - -### Zentrale Metadaten-Verwaltung - -#### versions.json - -- **14 aktive Guidelines** vollständig dokumentiert -- **1 archivierte Guideline** mit Archivierungsgrund -- **Abhängigkeits-Matrix** für alle Guidelines -- **Statistiken** über Optimierungen - -#### cross-refs.json - -- **Vollständige Cross-Referenz-Matrix** aller Guidelines -- **Navigation-Workflows** für häufige Anwendungsfälle -- **Link-Validierung** Infrastruktur vorbereitet -- **Abhängigkeits-Analyse** implementiert - -## 🔄 Durchgeführte Optimierungen - -### Phase 1: Cleanup und Archivierung -✅ -1. **Redundanz eliminiert:** docker-guideline.md (69 KB) archiviert -2. **Verzeichnisstruktur:** _archived/ für historische Referenzen erstellt -3. **YAML-Syntax korrigiert:** README.md Zeile 114 behoben -4. **Versionierung vereinheitlicht:** Alle Guidelines auf 2.1.0 - -### Phase 2: Strukturelle Verbesserungen - -1. **Metadaten standardisiert:** 14 Guidelines mit deutschen ai_context-Feldern -2. **Datum aktualisiert:** Einheitlich auf 2025-09-15 -3. **Konsistenz gewährleistet:** YAML-Header in allen Guidelines - -### Phase 3: Erweiterte Architektur -✅ -1. **_meta/ Verzeichnis:** Zentrale Metadaten-Verwaltung -2. **versions.json:** Umfassende Versionskontrolle -3. **cross-refs.json:** Cross-Referenz-Matrix mit Navigation-Workflows -4. **_templates/ Verzeichnis:** Standard-Template für neue Guidelines - -## 🚀 Qualitative Verbesserungen - -### Wartbarkeit - -- **Single Source of Truth:** Zentrale Metadaten-Verwaltung -- **Template-System:** Konsistente neue Guidelines -- **Cross-Referenz-Matrix:** Automatisierte Link-Validierung möglich -- **Modulare Struktur:** Beibehaltung der bewährten Docker-Guides-Modularität - -### Entwickler-Experience - -- **Deutsche Sprache:** Alle Metadaten und Beschreibungen lokalisiert -- **Klare Navigation:** Verbesserte Cross-Referenzen zwischen Guidelines -- **AI-Optimierung:** Strukturierte Metadaten für bessere KI-Kompatibilität -- **Schnelle Orientierung:** README.md als zentraler Einstiegspunkt optimiert - -### KI-Assistant-Kompatibilität - -- **Strukturierte Metadaten:** Einheitliche YAML-Header -- **Deutsche ai_context-Felder:** Besseres Verständnis für deutsche KI-Prompts -- **Navigation-Workflows:** Vordefinierte Pfade für häufige Aufgaben -- **Quick-Reference-Tabellen:** Optimiert für AI-Assistant-Nutzung - -## 📈 Zukunftssicherheit - -### Automatisierung (vorbereitet) - -- **Link-Validierung:** cross-refs.json als Basis implementiert -- **Version-Checks:** versions.json für automatisierte Updates -- **Konsistenz-Prüfung:** Template-System für einheitliche neue Guidelines -- **CI/CD-Integration:** Metadaten-Struktur für Pipeline-Integration - -### Skalierbarkeit - -- **Template-System:** Einfache Erstellung neuer Guidelines -- **Modular aufgebaut:** Einfache Integration neuer Technologie-Bereiche -- **Archivierung-Workflow:** Etablierter Prozess für veraltete Guidelines -- **Metadaten-getrieben:** Flexible Erweiterung der Verwaltungslogik - -## ✅ Erfolgs-Metriken - -### Quantitativ - -- **-69KB:** Dateigröße-Reduktion durch Redundanz-Elimination -- **+4 neue Strukturkomponenten:** _archived/, _meta/, cross-refs.json, template -- **14 Guidelines:** Vollständig standardisiert und optimiert -- **100% Konsistenz:** Einheitliche Versionierung und Metadaten - -### Qualitativ - -- **🚀 50% schnellere Navigation** durch modulare Docker-Guides -- **🤖 90% bessere AI-Kompatibilität** durch strukturierte Metadaten -- **🔧 95% einfachere Wartung** durch zentrale Versionsverwaltung -- **📚 100% deutsche Lokalisierung** aller Guidelines-Metadaten - -## 🎉 Fazit - -Die `.junie` Guidelines wurden erfolgreich von einem redundanten, inkonsistenten System zu einer **modernen, wartbaren und zukunftssicheren Dokumentationsarchitektur** transformiert. - -### Haupterfolge - -1. **Redundanz eliminiert:** Monolithische Docker-Guideline durch modulare Guides ersetzt -2. **Konsistenz erreicht:** Alle Guidelines standardisiert und auf deutsche Sprache umgestellt -3. **Wartbarkeit verbessert:** Zentrale Metadaten-Verwaltung und Template-System implementiert -4. **Zukunftssicherheit:** Basis für Automatisierung und weitere Skalierung geschaffen - -Die optimierte `.junie` Struktur ist nun ein **beispielhaftes modernes Dokumentationssystem**, das sowohl für Menschen als auch KI-Assistenten optimal nutzbar ist und als Referenz für andere Projekte dienen kann. - ---- - -**Nächste Schritte (optional):** -- Implementierung automatisierter Link-Validierung basierend auf cross-refs.json -- Erstellung weiterer Templates für project-standards und process-guides -- Integration in CI/CD-Pipeline für automatische Konsistenz-Checks - - -## Nachträge 2025-10-31 - -- README.md erweitert: Zentrale Projekt-Guidelines und Docker-Guides direkt verlinkt (bessere Navigation für Entwickler und KI-Assistenten). -- Docker-Guides Cross-Links harmonisiert: Link-Bezeichner vereinheitlicht (lowercase) und fehlende Querverweise ergänzt in: - - docker-development.md → Verweis auf docker-production ergänzt - - docker-monitoring.md → expliziter Verweis auf docker-overview - - docker-overview.md → expliziter Verweis auf docker-architecture - - docker-production.md → expliziter Verweis auf docker-overview - - docker-troubleshooting.md → expliziter Verweis auf docker-overview -- Link-Validierung ausgeführt (.junie/scripts/validate-links.sh): Alle Cross-Referenzen und YAML-Metadaten valide, keine offenen Warnungen. diff --git a/.junie/README.md b/.junie/README.md new file mode 100644 index 00000000..b541a709 --- /dev/null +++ b/.junie/README.md @@ -0,0 +1,21 @@ +# `.junie/` – Tooling für Docs-as-Code + +Dieses Verzeichnis enthält **nur Tooling/Guardrails** für das Projekt. + +**Wichtig:** Die **Single Source of Truth** für Projektwissen ist `docs/`. +In `.junie/` liegen **keine verbindlichen Projektregeln** und keine zweite Dokumentationswelt. + +## Scripts + +* `./.junie/scripts/validate-links.sh` + * Prüft Markdown-Links in `docs/**/*.md` auf gebrochene relative Links. + * Schlägt fehl, wenn veraltete Pfade (z.B. `docs/00_Domain/`, `docs/adr/`) im Text vorkommen. + +* `./.junie/scripts/check-docs-drift.sh` + * Sehr schlanke Drift-Checks gegen die aktuelle Doku-Struktur (z.B. Konsistenz-Checks in Architektur/ADRs/C4). + +* `./.junie/scripts/markdown-autofix.sh` + * Hilfsscript für Markdown-Formatierung. + +* `./.junie/scripts/render-plantuml.sh` + * Rendern von PlantUML-Diagrammen (wenn genutzt). diff --git a/.junie/guidelines/README.md b/.junie/guidelines/README.md deleted file mode 100644 index 77674bde..00000000 --- a/.junie/guidelines/README.md +++ /dev/null @@ -1,172 +0,0 @@ -# Meldestelle Project Guidelines - -**Version:** 2.1.0 -**Last Updated:** 2025-09-15 -**Status:** Reorganized & AI-Optimized - ---- - -## 📋 Overview - -This directory contains the comprehensive development guidelines for the Meldestelle project. The guidelines have been restructured into a hierarchical, AI-assistant-optimized format for better navigation, maintainability, and usability. - -> **🤖 AI-Assistant Note:** -> All guidelines now include structured metadata headers and AI-specific hints for optimal assistant interaction: -> - **Metadata:** Each file has guideline_type, scope, audience, and dependencies -> - **AI Context:** Specific context information for better AI understanding -> - **Cross-References:** Consistent navigation links between related guidelines -> - **Quick Reference:** AI-optimized tables and checklists - -## 🗂️ Guidelines Structure - -### 📊 Master Guideline - -- **[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 | - -### 🔧 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 | - -### 🔄 Process Guides -Development process and workflow guidelines: - -- **[Trace Bullet Guideline](./process-guides/trace-bullet-guideline.md)** - End-to-end architecture validation cycle - -## 🎯 Quick Navigation for AI Assistants - -### 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 | - -### Key Architectural Decisions - -1. **Microservices Architecture** - See [Architecture Principles](./project-standards/architecture-principles.md) -2. **Domain-Driven Design** - See [Architecture Principles](./project-standards/architecture-principles.md) -3. **Event-Driven Architecture** - See [Architecture Principles](./project-standards/architecture-principles.md) -4. **Kotlin Multiplatform** - See [Web App Guideline](./technology-guides/web-app-guideline.md) -5. **Docker-First Infrastructure** - See [Docker Overview](./technology-guides/docker/docker-overview.md) - -### 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 | - -## 🚀 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 - -## 🤖 Automatisierung und Validierung - -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 (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` - -**Detaillierte Dokumentation:** [AUTOMATION-FEATURES.md](../AUTOMATION-FEATURES.md) - -## 📝 Guideline Metadata Format - -All guidelines follow this metadata structure for AI optimization: - -```yaml ---- -guideline_type: "project-standards" # oder "technology" oder "process-guide" -scope: "specific-area-identifier" -audience: ["developers", "ai-assistants", "architects", "devops", "project-managers"] -last_updated: "YYYY-MM-DD" -dependencies: ["list-of-related-guidelines"] -related_files: ["relevant-project-files"] -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 -- Content follows documentation standards - ---- - -**Last Restructuring:** 2025-09-13 - Complete hierarchical reorganization with AI optimization -**Next Review:** As needed based on project evolution - -**Questions or suggestions?** Update this README.md or reach out to the development team. diff --git a/.junie/guidelines/_archived/docker-guideline-v3.0.1-archived-2025-09-15.md b/.junie/guidelines/_archived/docker-guideline-v3.0.1-archived-2025-09-15.md deleted file mode 100644 index 84491ca2..00000000 --- a/.junie/guidelines/_archived/docker-guideline-v3.0.1-archived-2025-09-15.md +++ /dev/null @@ -1,2445 +0,0 @@ -# Docker-Guidelines für das Meldestelle-Projekt - -> **Version:** 3.0.1 -> **Datum:** 13. September 2025 -> **Autor:** Meldestelle Development Team -> **Letzte Aktualisierung:** 🎯 ZENTRALE DOCKER-VERSIONSVERWALTUNG vollständig optimiert - Single Source of Truth mit neuesten Monitoring-Versionen (Prometheus v2.54.1, Grafana 11.3.0, Keycloak 26.0.7), erweiterte Script-Funktionalität und vollautomatisierte Version-Updates - ---- - -## 🚀 Überblick und Philosophie - -Das Meldestelle-Projekt implementiert eine **moderne, sicherheitsorientierte Containerisierungsstrategie** basierend auf bewährten DevOps-Praktiken und Production-Ready-Standards. Unsere Docker-Architektur ist darauf ausgelegt: - -- **Sicherheit first**: Alle Container laufen als Non-Root-User -- **Optimale Performance**: Multi-stage Builds mit Layer-Caching -- **Observability**: Umfassendes Monitoring und Health-Checks -- **Skalierbarkeit**: Microservices-ready mit Service Discovery -- **Wartbarkeit**: Standardisierte Templates und klare Konventionen - ---- - -## 📋 Inhaltsverzeichnis - -1. [Architektur-Überblick](#architektur-überblick) -2. [Zentrale Konfigurationsverwaltung - Single Source of Truth](#zentrale-konfigurationsverwaltung) 🆕 -3. [Zentrale Docker-Versionsverwaltung](#zentrale-docker-versionsverwaltung) -4. [Zentrale Port-Verwaltung](#zentrale-port-verwaltung) -5. [Environment-Overrides Vereinheitlichung](#environment-overrides-vereinheitlichung) -6. [Docker-Compose Template-System](#docker-compose-template-system) -7. [Validierung und Konsistenz-Checks](#validierung-und-konsistenz-checks) -8. [IDE-Integration](#ide-integration) -9. [Dockerfile-Standards](#dockerfile-standards) -10. [Docker-Compose Organisation](#docker-compose-organisation) -11. [Development-Workflow](#development-workflow) -12. [Production-Deployment](#production-deployment) -13. [Monitoring und Observability](#monitoring-und-observability) -14. [Troubleshooting](#troubleshooting) -15. [Best Practices](#best-practices) - ---- - -## 🏗️ Architektur-Überblick - -### Container-Kategorien - -```mermaid -graph TB - subgraph "Infrastructure Services" - PG[PostgresQL] - RD[Redis] - KC[Keycloak] - KF[Kafka+Zookeeper] - CS[Consul] - end - - subgraph "Application Services" - GW[API Gateway] - AS[Auth Server] - MS[Monitoring Server] - PS[Ping Service] - end - - subgraph "Client Applications" - WA[Web App] - DA[Desktop App - Native] - end - - subgraph "Monitoring Stack" - PR[Prometheus] - GR[Grafana] - ZK[Zipkin] - NX[Nginx - Prod] - end - - Infrastructure --> Application - Application --> Client - Monitoring --> Infrastructure - Monitoring --> Application -``` - -### 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 | - ---- - -## 🎯 Zentrale Konfigurationsverwaltung - Single Source of Truth - -### Überblick und Revolution - -**Version 4.0.0** führt eine bahnbrechende Neuerung ein: die **zentrale Verwaltung aller Konfigurationswerte** in einer einzigen Master-Datei. Diese eliminiert **38+ Port-Redundanzen** und **72+ Spring-Profile-Duplikate** vollständig. - -#### Das Problem vor Version 4.0.0 - -```bash -# Massive Redundanz über 100+ Dateien verteilt: -gradle.properties: services.port.ping=8082 -docker-compose.services.yaml: SERVER_PORT: ${PING_SERVICE_PORT:-8082} -dockerfiles/services/ping: EXPOSE 8082 -scripts/test/integration: ping-service:8082 -config/monitoring/prometheus: - targets: ['ping-service:8082'] -infrastructure/README: port = 8082 -# ... und 32 weitere Stellen! -``` - -#### Die Lösung: Zentrale Master-Konfiguration - -```toml -# config/central.toml - ABSOLUTE SINGLE SOURCE OF TRUTH -[ports] -ping-service = 8082 -members-service = 8083 -horses-service = 8084 -# Einmalig definiert, überall verfügbar - -[spring-profiles.defaults] -infrastructure = "default" -services = "docker" -clients = "dev" -# Nie wieder inkonsistente Profile-Namen -``` - -### 🏗️ Architektur der zentralen Konfigurationsverwaltung - -```plaintext -config/ -├── central.toml # 🎯 ABSOLUTE SINGLE SOURCE OF TRUTH -├── README.md # Dokumentation -└── examples/ # Verwendungsbeispiele - -scripts/ -└── config-sync.sh # ⚙️ Automatische Synchronisation - -# Synchronisierte Dateien (automatisch aktualisiert): -├── gradle.properties # ✓ Ports synchronisiert -├── docker-compose*.yml # ✓ Alle Ports + Profile -├── config/.env.template # ✓ Environment Variables -├── docker/build-args/*.env # ✓ Build Arguments -├── config/monitoring/*.yml # ✓ Prometheus Targets -└── scripts/test/*.sh # ✓ Test-Endpunkte -``` - -### 📊 Konfigurationsbereiche - -#### 1. **Port-Management** – eliminiert 38+ Redundanzen - -```toml -[ports] -# --- Infrastructure Services --- -api-gateway = 8081 -auth-server = 8087 -monitoring-server = 8088 - -# --- Application Services --- -ping-service = 8082 -members-service = 8083 -horses-service = 8084 -events-service = 8085 -masterdata-service = 8086 - -# --- External Infrastructure --- -postgres = 5432 -redis = 6379 -consul = 8500 -prometheus = 9090 -grafana = 3000 -``` - -#### 2. **Spring-Profile-Management** – eliminiert 72+ Duplikate - -```toml -[spring-profiles] -default = "default" -development = "dev" -docker = "docker" -production = "prod" -test = "test" - -[spring-profiles.defaults] -infrastructure = "default" -services = "docker" -clients = "dev" -``` - -#### 3. **Service-Discovery** - Standardisiert URLs - -```toml -[services.ping-service] -name = "ping-service" -port = 8082 -internal-host = "ping-service" -external-host = "localhost" -internal-url = "http://ping-service:8082" -external-url = "http://localhost:8082" -health-endpoint = "/actuator/health/readiness" -metrics-endpoint = "/actuator/prometheus" -``` - -#### 4. **Health-Check-Standardisierung** - -```toml -[health-checks.defaults] -interval = "15s" -timeout = "5s" -retries = 3 -start-period = "30s" - -[health-checks.production] -interval = "10s" -timeout = "3s" -retries = 3 -start-period = "20s" -``` - -### 🛠️ Verwendung der zentralen Konfigurationsverwaltung - -#### Automatisierte Synchronisation mit `scripts/config-sync.sh` - -```bash -# Alle Konfigurationsdateien synchronisieren -./scripts/config-sync.sh sync - -# Aktuelle Konfiguration anzeigen -./scripts/config-sync.sh status - -# Nur gradle.properties synchronisieren -./scripts/config-sync.sh gradle - -# Nur Docker Compose Dateien synchronisieren -./scripts/config-sync.sh compose - -# Validierung der zentralen Konfiguration -./scripts/config-sync.sh validate -``` - -#### Ports ändern – ein Befehl, überall aktualisiert - -```bash -# 1. config/central.toml bearbeiten -[ports] -ping-service = 8092 # Geändert von 8082 - -# 2. Alle Dateien automatisch synchronisieren -./scripts/config-sync.sh sync - -# Ergebnis: 38+ Dateien automatisch aktualisiert: -# ✓ gradle.properties: services.port.ping=8092 -# ✓ docker-compose.services.yaml: SERVER_PORT: ${PING_SERVICE_PORT:-8092} -# ✓ dockerfiles/services/ping-service/Dockerfile: EXPOSE 8092 -# ✓ scripts/test/integration-test.sh: ping-service:8092 -# ✓ config/monitoring/prometheus.dev.yml: - targets: ['ping-service:8092'] -# ✓ Und 33 weitere Dateien automatisch! -``` - -#### Spring-Profile ändern – Konsistenz garantiert - -```bash -# 1. Zentral in config/central.toml ändern -[spring-profiles.defaults] -services = "production" # Geändert von "docker" - -# 2. Synchronisieren -./scripts/config-sync.sh sync - -# Ergebnis: 72+ Referenzen automatisch aktualisiert: -# ✓ Alle Dockerfiles mit korrektem SPRING_PROFILES_ACTIVE -# ✓ Docker Compose Dateien mit richtigen Defaults -# ✓ Build-Argument-Dateien synchronisiert -# ✓ Keine inkonsistenten Profile-Namen mehr möglich! -``` - -### 🔄 Entwickler-Workflow mit zentraler Konfiguration - -#### **Neuen Service hinzufügen** - -```bash -# 1. Port in central.toml definieren -[ports] -new-service = 8090 - -[services.new-service] -name = "new-service" -port = 8090 -# ... weitere Service-Eigenschaften - -# 2. Alle Konfigurationen synchronisieren -./scripts/config-sync.sh sync - -# 3. Service ist jetzt überall verfügbar! -``` - -#### **Umgebung wechseln** - -```bash -# Development → Production Profile-Wechsel -# 1. config/central.toml anpassen -[spring-profiles.defaults] -services = "prod" - -# 2. Synchronisieren -./scripts/config-sync.sh sync - -# Alle Services verwenden jetzt "prod" Profile! -``` - -#### **Monitoring hinzufügen** - -```bash -# Neuer Service automatisch in Prometheus überwacht: -# 1. Service in central.toml definieren -# 2. config-sync.sh sync ausführen -# 3. Prometheus-Konfiguration automatisch aktualisiert! -``` - -### 🎉 Vorteile der zentralen Konfigurationsverwaltung - -#### **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** -✅ -```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** -✅ -- 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] -future-service = 8099 - -# Nach Synchronisation automatisch in: -# - gradle.properties -# - docker-compose.yaml -# - Monitoring-Konfiguration -# - Test-Scripts -# - Environment-Files -``` - -#### **Fehlerreduktion** ✅ - -- Keine Tippfehler bei Port-Definitionen -- Keine vergessenen Aktualisierungen -- Automatische Backup-Erstellung vor Änderungen -- Rollback-Möglichkeiten durch Backups - -### 📚 Best Practices für zentrale Konfigurationsverwaltung - -#### **DO: Zentrale Konfiguration verwenden** - -```bash -# ✅ RICHTIG - Zentrale Konfiguration -./scripts/config-sync.sh sync - -# ✅ RICHTIG - Status vor Änderungen prüfen -./scripts/config-sync.sh status - -# ✅ RICHTIG - Validierung vor Deployment -./scripts/config-sync.sh validate -``` - -#### **DON'T: Manuelle Datei-Bearbeitung** - -```bash -# ❌ FALSCH - Nie mehr manuelle Port-Änderungen -vim docker-compose.yaml # Änderungen gehen verloren! - -# ✅ RICHTIG - Zentrale Änderung + Synchronisation -vim config/central.toml -./scripts/config-sync.sh sync -``` - -#### **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 -4. **Validieren** vor wichtigen Deployments -5. **Backup-Dateien** bei Problemen für Rollback nutzen - -### 🔧 Erweiterte Funktionen - -#### **Selective Synchronisation** - -```bash -# Nur bestimmte Bereiche synchronisieren -./scripts/config-sync.sh gradle # Nur gradle.properties -./scripts/config-sync.sh compose # Nur Docker Compose -./scripts/config-sync.sh env # Nur Environment-Dateien -./scripts/config-sync.sh monitoring # Nur Monitoring-Config -./scripts/config-sync.sh tests # Nur Test-Scripts -``` - -#### **Backup und Rollback** - -```bash -# Alle Backups anzeigen -ls -la *.bak.* - -# Rollback bei Problemen -cp gradle.properties.bak.20250915_103927 gradle.properties -``` - -#### **Dry-Run Modus** - -```bash -# Änderungen anzeigen ohne Ausführung -./scripts/config-sync.sh sync --dry-run -``` - -### 🚀 Integration in CI/CD - -#### **Automatische Konsistenz-Checks** - -```yaml -# GitHub Actions Pipeline -- name: Validate Configuration Consistency - run: | - ./scripts/config-sync.sh validate - ./scripts/config-sync.sh sync --dry-run -``` - -#### **Pre-Commit Hooks** - -```bash -# .git/hooks/pre-commit -#!/bin/bash -./scripts/config-sync.sh validate || exit 1 -``` - -### 🎯 Migration bestehender Projekte - -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 -3. **Backups prüfen** und validieren -4. **Entwickler-Workflow** anpassen - -Das System integriert sich nahtlos in die bestehende Docker-Versionsverwaltung und erweitert diese um umfassende Konfigurationsverwaltung. - ---- - -## 🎯 Zentrale Docker-Versionsverwaltung - -### Überblick und Motivation - -**Version 3.0.0** führt eine revolutionäre Änderung in der Docker-Versionsverwaltung ein: die **zentrale Verwaltung aller Build-Argumente** analog zum bewährten `gradle/libs.versions.toml` System. - -#### Das Problem vor Version 3.0.0 - -```dockerfile -# BEFORE: Redundante Hardcodierung in 12+ Dockerfiles -ARG GRADLE_VERSION=9.2.1 -# ... 9 weitere Male identisch wiederholt! -``` - -#### Die Lösung: Single Source of Truth - -```toml -# docker/versions.toml - SINGLE SOURCE OF TRUTH -[versions] -gradle = "9.2.1" -java = "25" -node = "24.12.0" -nginx = "1.25-alpine" -prometheus = "v2.54.1" -grafana = "11.3.0" -keycloak = "26.0.7" -``` - -### 🏗️ Architektur der zentralen Versionsverwaltung - -```plaintext -docker/ -├── versions.toml # 🎯 Single Source of Truth -├── build-args/ # Auto-generierte Environment Files -│ ├── global.env # Globale Build-Argumente -│ ├── services.env # dockerfiles/services/* -│ ├── clients.env # dockerfiles/clients/* -│ └── infrastructure.env # dockerfiles/infrastructure/* -└── README.md # Dokumentation -``` - -### 📊 Hierarchische Versionsverwaltung - -#### 1. **Globale Versionen** (`docker/build-args/global.env`) - -Verwendet von **allen** Dockerfiles: -```bash -# --- Build Tools --- -GRADLE_VERSION=9.2.1 -JAVA_VERSION=25 - -# --- Build Metadata --- -BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') -VERSION=1.0.0 - -# --- Common Base Images --- -ALPINE_VERSION=3.19 -ECLIPSE_TEMURIN_JDK_VERSION=21-jdk-alpine -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 -``` - -#### 2. **Kategorie-spezifische Versionen** - -**Services** (`docker/build-args/services.env`): -```bash -SPRING_PROFILES_ACTIVE=docker -SERVICE_PORT=8080 -PING_SERVICE_PORT=8082 -MEMBERS_SERVICE_PORT=8083 -``` - -**Clients** (`docker/build-args/clients.env`): -```bash -NODE_VERSION=24.12.0 -NGINX_VERSION=1.25-alpine -WEB_APP_PORT=4000 -DESKTOP_APP_VNC_PORT=5901 -``` - -**Infrastructure** (`docker/build-args/infrastructure.env`): -```bash -SPRING_PROFILES_ACTIVE=default -GATEWAY_PORT=8081 -AUTH_SERVER_PORT=8087 -``` - -### 🛠️ Verwendung der zentralen Versionsverwaltung - -#### Automatisierte Builds mit `scripts/docker-build.sh` - -```bash -# Alle Services mit zentralen Versionen bauen -./scripts/docker-build.sh services - -# Client-Anwendungen bauen -./scripts/docker-build.sh clients - -# Komplettes System bauen -./scripts/docker-build.sh all - -# Aktuelle Versionen anzeigen -./scripts/docker-build.sh --versions -``` - -#### Versionen aktualisieren mit `scripts/docker-versions-update.sh` - -```bash -# Aktuelle Versionen anzeigen -./scripts/docker-versions-update.sh show - -# Java auf Version 22 upgraden -./scripts/docker-versions-update.sh update java 25 - -# Gradle auf 9.2.1 upgraden -./scripts/docker-versions-update.sh update gradle 9.2.1 - -# Prometheus auf neueste Version upgraden -./scripts/docker-versions-update.sh update prometheus v2.54.1 - -# Grafana auf neueste Version upgraden -./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 - -# Alle Environment-Dateien synchronisieren -./scripts/docker-versions-update.sh sync -``` - -### 📋 Dockerfile Template-System Version 3.0.0 - -#### Neue Template-Struktur - -```dockerfile -# === CENTRALIZED BUILD ARGUMENTS === -# Values sourced from docker/versions.toml and docker/build-args/ -# Global arguments (docker/build-args/global.env) -ARG GRADLE_VERSION -ARG JAVA_VERSION -ARG BUILD_DATE -ARG VERSION - -# Category-specific arguments (docker/build-args/services.env) -ARG SPRING_PROFILES_ACTIVE -ARG SERVICE_PATH=. -ARG SERVICE_NAME=spring-boot-service -ARG SERVICE_PORT=8080 -``` - -#### Docker-Compose Integration - -```yaml -api-gateway: - build: - context: . - dockerfile: dockerfiles/infrastructure/gateway/Dockerfile - args: - # Zentrale Versionen via Environment-Variablen - GRADLE_VERSION: ${DOCKER_GRADLE_VERSION:-9.2.1} - JAVA_VERSION: ${DOCKER_JAVA_VERSION:-25} - BUILD_DATE: ${BUILD_DATE} - VERSION: ${DOCKER_APP_VERSION:-1.0.0} - SPRING_PROFILES_ACTIVE: ${DOCKER_SPRING_PROFILES_DEFAULT:-default} -``` - -### 🎉 Vorteile der zentralen Versionsverwaltung - -#### **DRY-Prinzip Durchsetzung** -✅ -- **Vor Version 3.0.0**: `GRADLE_VERSION=9.2.1` in 12 Dockerfiles -- **Ab Version 3.0.0**: `gradle = "9.2.1"` **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 -./scripts/docker-versions-update.sh update gradle 9.2.1 -``` - -#### **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 -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 -``` - -### 📚 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 - -# ✅ RICHTIG - Automatisierte Builds -./scripts/docker-build.sh all -``` - -#### **DON'T: Manuelle Dockerfile-Bearbeitung** - -```dockerfile -# ❌ FALSCH - Nie mehr hardcodierte Versionen -ARG GRADLE_VERSION=9.2.1 - -# ✅ RICHTIG - Zentrale Referenz -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 -4. **Kategorien-spezifische** Build-Argumente korrekt zuordnen - -### 🚀 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/ - -# 2. Service-spezifische Parameter anpassen (Port, Name, etc.) -# 3. Bauen mit zentralen Versionen -./scripts/docker-build.sh services -``` - -#### **Versionen projekt-weit upgraden** - -```bash -# 1. Java-Version upgraden (betrifft ALLE Services) -./scripts/docker-versions-update.sh update java 22 - -# 2. Automatisch alle Services neu bauen -./scripts/docker-build.sh all - -# 3. Testen und committen -``` - -#### **Version-Status prüfen** - -```bash -# Aktuelle zentrale Versionen anzeigen -./scripts/docker-versions-update.sh show - -# Build-Environment-Status prüfen -./scripts/docker-build.sh --versions -``` - ---- - -## 🔌 Zentrale Port-Verwaltung - -### Überblick - -Mit **Version 3.1.0** führen wir ein revolutionäres Feature ein: die **zentrale Port-Verwaltung** über `docker/versions.toml`. Dieses System eliminiert Port-Konflikte und schafft eine einheitliche Port-Registry für alle Services. - -### 🎯 Single Source of Truth für Ports - -```toml -# docker/versions.toml - Port-Registry -[service-ports] -# --- Infrastructure Services --- -api-gateway = 8081 -auth-server = 8087 -monitoring-server = 8088 - -# --- Application Services --- -ping-service = 8082 -members-service = 8083 -horses-service = 8084 -events-service = 8085 -masterdata-service = 8086 - -# --- External Services --- -postgres = 5432 -redis = 6379 -keycloak = 8180 -consul = 8500 -zookeeper = 2181 -kafka = 9092 - -# --- Monitoring Stack --- -prometheus = 9090 -grafana = 3000 - -# --- Client Applications --- -web-app = 4000 -desktop-app-vnc = 5901 -desktop-app-novnc = 6080 -``` - -### 🏗️ Port-Range-Management - -```toml -[port-ranges] -# --- Automatische Port-Zuweisung --- -infrastructure = "8081-8088" -services = "8082-8099" -monitoring = "9090-9099" -clients = "4000-4099" -vnc = "5901-5999" -debug = "5005-5009" - -# --- Reserved Ranges --- -system-reserved = "0-1023" -ephemeral = "32768-65535" -``` - -### ⚡ Automatische Port-Integration - -#### Docker-Compose Integration - -```yaml -# Ports werden automatisch aus versions.toml gelesen -api-gateway: - ports: - - "${GATEWAY_PORT:-8081}:8081" - environment: - - SERVER_PORT=${GATEWAY_PORT:-8081} - -ping-service: - ports: - - "${PING_SERVICE_PORT:-8082}:8082" - environment: - - SERVER_PORT=${PING_SERVICE_PORT:-8082} -``` - -#### Script-basierte Port-Validierung - -```bash -# scripts/validate-port-conflicts.sh -#!/bin/bash -validate_port_conflicts() { - local used_ports=($(grep -o '[0-9]\{4,5\}' docker/versions.toml | sort -n)) - - for port in "${used_ports[@]}"; do - if netstat -tulpn 2>/dev/null | grep -q ":$port "; then - echo "⚠️ Port $port ist bereits belegt!" - fi - done -} -``` - -### 📊 Port-Registry Vorteile - -1. **Keine Konflikte**: Automatische Port-Konflikt-Erkennung -2. **Skalierbarkeit**: Einfaches Hinzufügen neuer Services -3. **Dokumentation**: Selbst-dokumentierende Port-Zuweisungen -4. **Konsistenz**: Einheitliche Port-Konventionen -5. **Automatisierung**: Script-basierte Port-Verwaltung - ---- - -## ⚙️ Environment-Overrides Vereinheitlichung - -### Zentrale Environment-Konfiguration - -**Version 3.1.0** standardisiert Environment-Overrides für verschiedene Deployment-Szenarien: - -```toml -# docker/versions.toml - Environment-spezifische Konfigurationen -[environments.development] -spring-profiles = "dev" -debug-enabled = true -log-level = "DEBUG" -health-check-interval = "30s" -health-check-timeout = "5s" -health-check-retries = 3 -health-check-start-period = "40s" -resource-limits = false -jvm-debug-port = 5005 -hot-reload = true - -[environments.production] -spring-profiles = "prod" -debug-enabled = false -log-level = "INFO" -health-check-interval = "15s" -health-check-timeout = "3s" -health-check-retries = 3 -health-check-start-period = "30s" -resource-limits = true -jvm-debug-port = false -hot-reload = false -security-headers = true -tls-enabled = true - -[environments.testing] -spring-profiles = "test" -debug-enabled = true -log-level = "DEBUG" -health-check-interval = "10s" -health-check-timeout = "5s" -health-check-retries = 2 -health-check-start-period = "20s" -resource-limits = false -jvm-debug-port = 5005 -hot-reload = false -ephemeral-storage = true -test-containers = true -``` - -### 🚀 Environment-basierte Deployments - -#### Development Environment - -```bash -# Development mit Hot-Reload und Debug -export DOCKER_ENVIRONMENT=development -docker-compose -f docker-compose.yaml -f docker-compose.dev.yml up -d -``` - -#### Production Environment - -```bash -# Production mit Security und Resource-Limits -export DOCKER_ENVIRONMENT=production -docker-compose -f docker-compose.prod.yml up -d -``` - -#### Testing Environment - -```bash -# Testing mit schnellen Health-Checks -export DOCKER_ENVIRONMENT=testing -docker-compose -f docker-compose.test.yml up -d -``` - -### ⚙️ Automatische Environment-Anpassung - -```bash -# scripts/apply-environment.sh -#!/bin/bash -apply_environment_settings() { - local env=${1:-development} - - # Aus versions.toml lesen und anwenden - case $env in - "development") - export DEBUG=true - export LOG_LEVEL=DEBUG - export SPRING_PROFILES_ACTIVE=dev - ;; - "production") - export DEBUG=false - export LOG_LEVEL=INFO - export SPRING_PROFILES_ACTIVE=prod - ;; - "testing") - export DEBUG=true - export LOG_LEVEL=DEBUG - export SPRING_PROFILES_ACTIVE=test - ;; - esac -} -``` - ---- - -## 📝 Docker-Compose Template-System - -### Template-basierte Compose-Generierung - -**Version 3.1.0** führt ein mächtiges Template-System ein, das Docker-Compose-Dateien aus zentralen Konfigurationen generiert: - -```bash -# scripts/generate-compose-files.sh -#!/bin/bash -generate_service_definition() { - local service=$1 - local category=$2 - local port=$(get_service_port $service) - - cat << EOF - $service: - build: - context: . - dockerfile: dockerfiles/$category/$service/Dockerfile - args: -$(generate_build_args_for_category $category) - container_name: meldestelle-$service - ports: - - "$port:$port" - environment: -$(generate_environment_vars_for_service $service) - networks: - - meldestelle-network - healthcheck: - test: ["CMD", "curl", "--fail", "http://localhost:$port/actuator/health"] - interval: \${HEALTH_CHECK_INTERVAL:-15s} - timeout: \${HEALTH_CHECK_TIMEOUT:-3s} - retries: \${HEALTH_CHECK_RETRIES:-3} - start_period: \${HEALTH_CHECK_START_PERIOD:-30s} - restart: unless-stopped -EOF -} -``` - -### 🎯 Service-Kategorien Templates - -#### Services Template - -```bash -generate_services_compose() { - local services=($(get_services_from_toml)) - - echo "# Generated from docker/versions.toml" - echo "services:" - - for service in "${services[@]}"; do - generate_service_definition "$service" "services" - done -} -``` - -#### Infrastructure Template - -```bash -generate_infrastructure_compose() { - local infrastructure=($(get_infrastructure_from_toml)) - - for infra in "${infrastructure[@]}"; do - generate_service_definition "$infra" "infrastructure" - done -} -``` - -### 📊 Template-System Vorteile - -1. **DRY-Prinzip**: Keine Duplikation in Compose-Dateien -2. **Konsistenz**: Einheitliche Service-Definitionen -3. **Skalierbarkeit**: Einfaches Hinzufügen neuer Services -4. **Wartbarkeit**: Zentrale Template-Verwaltung -5. **Automatisierung**: Script-basierte Generierung - ---- - -## ✅ Validierung und Konsistenz-Checks - -### Automatisierte Docker-Konsistenz-Prüfung - -**Version 3.1.0** implementiert umfassende Validierungstools: - -```bash -# scripts/validate-docker-consistency.sh -#!/bin/bash -validate_dockerfile_args() { - echo "🔍 Validating Dockerfile ARG usage..." - - for dockerfile in $(find dockerfiles -name "Dockerfile"); do - echo "Checking $dockerfile..." - - # Prüfe ARG-Deklarationen - grep "^ARG " "$dockerfile" | while read arg_line; do - local arg_name=$(echo "$arg_line" | cut -d' ' -f2 | cut -d'=' -f1) - validate_arg_in_toml "$arg_name" "$dockerfile" - done - done -} - -validate_compose_versions() { - echo "🔍 Validating docker-compose version references..." - - for compose_file in docker-compose*.yml; do - echo "Checking $compose_file..." - - # Prüfe ${DOCKER_*_VERSION} Referenzen - grep -o '\${DOCKER_[^}]*}' "$compose_file" | sort -u | while read var_ref; do - validate_version_mapping "$var_ref" "$compose_file" - done - done -} - -validate_port_assignments() { - echo "🔍 Validating port assignments..." - - # Prüfe Port-Duplikate - local ports=($(grep -o '[0-9]\{4,5\}' docker/versions.toml | sort)) - local unique_ports=($(printf '%s\n' "${ports[@]}" | sort -u)) - - if [ ${#ports[@]} -ne ${#unique_ports[@]} ]; then - echo "❌ Duplicate ports found in versions.toml!" - return 1 - fi - - echo "✅ No port conflicts detected" -} -``` - -### 🏗️ Build-Validierung - -```bash -validate_build_consistency() { - echo "🔍 Validating build consistency..." - - # Template-Konsistenz prüfen - for template in dockerfiles/templates/*.Dockerfile; do - validate_template_args "$template" - done - - # Service-spezifische Dockerfiles prüfen - for service_dockerfile in dockerfiles/{services,infrastructure,clients}/*/Dockerfile; do - validate_service_dockerfile "$service_dockerfile" - done - - echo "✅ Build consistency validation complete" -} -``` - -### 🛠️ Kontinuierliche Validierung - -```bash -# .github/workflows/docker-validation.yml (Beispiel) -name: Docker Consistency Validation - -on: [push, pull_request] - -jobs: - validate-docker: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Validate Docker Consistency - run: | - chmod +x scripts/validate-docker-consistency.sh - ./scripts/validate-docker-consistency.sh - - name: Validate Build Args - run: | - ./scripts/docker-versions-update.sh sync - git diff --exit-code docker/build-args/ -``` - ---- - -## 🔧 IDE-Integration - -### VS Code Integration - -**Version 3.1.0** bietet umfassende IDE-Unterstützung: - -**Datei:** `.vscode/settings.json` - -```json -{ - "yaml.schemas": { - "./docker/schemas/versions-schema.json": "docker/versions.toml" - }, - "files.associations": { - "docker/versions.toml": "toml", - "docker-compose*.yml": "dockercompose" - }, - "docker.defaultBuildArgs": { - "GRADLE_VERSION": "${config:docker.gradleVersion}", - "JAVA_VERSION": "${config:docker.javaVersion}" - }, - "docker.composeCommand": "docker-compose", - "docker.composeFiles": [ - "docker-compose.yaml", - "docker-compose.services.yaml", - "docker-compose.frontend.yaml" - ] -} -``` - -### 📋 JSON Schema für TOML-Validierung - -**Datei:** `docker/schemas/versions-schema.json` - -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Docker Versions TOML Schema", - "type": "object", - "properties": { - "versions": { - "type": "object", - "properties": { - "gradle": { - "type": "string", - "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$", - "description": "Gradle version" - }, - "java": { - "type": "string", - "enum": ["17", "21", "22"], - "description": "Java LTS version" - }, - "prometheus": { - "type": "string", - "pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+$", - "description": "Prometheus version with 'v' prefix" - }, - "grafana": { - "type": "string", - "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$", - "description": "Grafana version" - } - }, - "required": ["gradle", "java"], - "additionalProperties": true - }, - "service-ports": { - "type": "object", - "patternProperties": { - ".*": { - "type": "integer", - "minimum": 1024, - "maximum": 65535 - } - } - }, - "environments": { - "type": "object", - "properties": { - "development": {"$ref": "#/definitions/environment"}, - "production": {"$ref": "#/definitions/environment"}, - "testing": {"$ref": "#/definitions/environment"} - } - } - }, - "definitions": { - "environment": { - "type": "object", - "properties": { - "spring-profiles": {"type": "string"}, - "debug-enabled": {"type": "boolean"}, - "log-level": {"enum": ["DEBUG", "INFO", "WARN", "ERROR"]}, - "resource-limits": {"type": "boolean"} - } - } - } -} -``` - -### 🚀 IntelliJ IDEA Integration - -```xml - - - - - - -``` - -### ⚡ Auto-Completion und Hints - -#### VS Code Tasks - -**Datei:** `.vscode/tasks.json` - -```json -{ - "version": "2.0.0", - "tasks": [ - { - "label": "Docker: Show Versions", - "type": "shell", - "command": "./scripts/docker-versions-update.sh", - "args": ["show"], - "group": "build", - "presentation": { - "echo": true, - "reveal": "always" - } - }, - { - "label": "Docker: Validate Consistency", - "type": "shell", - "command": "./scripts/validate-docker-consistency.sh", - "group": "build" - }, - { - "label": "Docker: Build All Services", - "type": "shell", - "command": "./scripts/docker-build.sh", - "args": ["all"], - "group": "build" - } - ] -} -``` - -### 🔧 Development Shortcuts - -#### Command Palette Commands - -**Datei:** `.vscode/settings.json` (erweiterte Konfiguration) - -```json -{ - "workbench.commandPalette.history": 100, - "terminal.integrated.profiles.linux": { - "Docker Commands": { - "path": "bash", - "args": ["-c", "echo 'Docker utilities loaded'; bash"] - } - }, - "docker.enableDockerComposeLanguageService": true, - "docker.enableDockerfileLanguageService": true -} -``` - ---- - -## 🐳 Dockerfile-Standards - -### Template-Struktur - -Alle Dockerfiles folgen einem standardisierten Template-System: - -```plaintext -dockerfiles/ -├── templates/ -│ ├── spring-boot-service.Dockerfile # Backend-Services -│ ├── kotlin-multiplatform-web.Dockerfile # Web-Client -│ └── monitoring-service.Dockerfile # Monitoring-Services -├── clients/ -│ ├── web-app/Dockerfile # Web-App (nginx) -│ └── desktop-app/Dockerfile # Desktop-App (VNC/X11) -├── infrastructure/ -│ ├── gateway/Dockerfile # API Gateway -│ ├── auth-server/Dockerfile # Auth Server -│ └── monitoring-server/Dockerfile # Monitoring Server -└── services/ - ├── members-service/Dockerfile # Domain Services (wenn reaktiviert) - ├── horses-service/Dockerfile - ├── events-service/Dockerfile - └── masterdata-service/Dockerfile -``` - -### Dockerfile-Architektur & Konsistenz-Richtlinien ✅ RESOLVED - -**AKTUELLER STATUS (Version 2.1):** -- ✅ Alle Dockerfiles folgen der konsistenten `dockerfiles/` Struktur -- ✅ API Gateway Dockerfile: `dockerfiles/infrastructure/gateway/Dockerfile` -- ✅ Keine Architektur-Ausnahmen mehr - alle Services folgen dem gleichen Muster -- ✅ Docker-Compose Referenzen nutzen konsistent die `dockerfiles/` Pfade - -**RICHTLINIEN ZUR VERMEIDUNG VON INKONSISTENZEN:** - -1. **Konsistenz-Prinzip:** ALLE Dockerfiles müssen unter `dockerfiles/` organisiert sein -2. **Keine Ausnahmen:** Kein Service darf außerhalb dieser Struktur platziert werden -3. **Vorhersagbarkeit:** Entwickler finden Dockerfiles immer am gleichen Ort -4. **Einheitliche Referenzierung:** Alle docker-compose.yml Dateien referenzieren `dockerfiles/` - -**Struktur-Kategorien:** -- `dockerfiles/templates/` - Wiederverwendbare Templates -- `dockerfiles/clients/` - Frontend-Anwendungen -- `dockerfiles/infrastructure/` - Infrastructure Services (inkl. Gateway) -- `dockerfiles/services/` - Domain Services - -**WICHTIG:** Bei neuen Services oder Refactoring IMMER die konsistente Struktur befolgen! - -### ✨ Neue Optimierungen (Version 2.0) - -#### BuildKit Cache Mounts ✅ IMPLEMENTIERT - -Alle Dockerfiles verwenden jetzt **BuildKit cache mounts** für optimale Build-Performance: - -```dockerfile -# Download dependencies with cache mount -RUN --mount=type=cache,target=/home/gradle/.gradle/caches \ - --mount=type=cache,target=/home/gradle/.gradle/wrapper \ - ./gradlew dependencies --no-daemon --info - -# Build application with cache mount -RUN --mount=type=cache,target=/home/gradle/.gradle/caches \ - --mount=type=cache,target=/home/gradle/.gradle/wrapper \ - ./gradlew bootJar --no-daemon --info -``` - -**Vorteile:** -- Gradle Dependencies werden zwischen Builds gecacht -- Signifikant reduzierte Build-Zeiten -- Bessere Resource-Effizienz in CI/CD-Pipelines - -#### Tini Init System ✅ IMPLEMENTIERT - -Alle Runtime-Container verwenden jetzt **tini** als Init-System: - -```dockerfile -# Installation in Alpine -RUN apk add --no-cache tini - -# Verwendung im Entrypoint -ENTRYPOINT ["tini", "--", "sh", "-c", "exec java $JAVA_OPTS -jar app.jar"] -``` - -**Vorteile:** -- Proper signal handling für Container -- Zombie-Process cleanup -- Graceful shutdown support - -#### Enhanced Security Hardening ✅ IMPLEMENTIERT - -Alle Container implementieren erweiterte Sicherheitspraktiken: - -```dockerfile -# Alpine security updates -RUN apk update && apk upgrade && \ - apk add --no-cache curl tzdata tini && \ - rm -rf /var/cache/apk/* - -# Non-root user with proper permissions -RUN addgroup -g ${APP_GID} -S ${APP_GROUP} && \ - adduser -u ${APP_UID} -S ${APP_USER} -G ${APP_GROUP} && \ - chown -R ${APP_USER}:${APP_GROUP} /app && \ - chmod -R 750 /app -``` - ---- - -### Spring Boot Service Template - -**Datei:** `dockerfiles/templates/spring-boot-service.Dockerfile` - -```dockerfile -# syntax=docker/dockerfile:1.8 - -# =================================================================== -# Multi-stage Dockerfile Template for Spring Boot Services -# Features: Security hardening, monitoring support, optimal caching, BuildKit cache mounts -# =================================================================== - -# Build arguments for flexibility -ARG GRADLE_VERSION=9.0.0 -ARG JAVA_VERSION=21 -ARG SPRING_PROFILES_ACTIVE=default -ARG SERVICE_PATH=. -ARG SERVICE_NAME=spring-boot-service -ARG SERVICE_PORT=8080 - -# =================================================================== -# Build Stage -# =================================================================== -FROM gradle:${GRADLE_VERSION}-jdk${JAVA_VERSION}-alpine AS builder - -# Re-declare build arguments for this stage -ARG SERVICE_PATH=. -ARG SERVICE_NAME=spring-boot-service -ARG SERVICE_PORT=8080 -ARG SPRING_PROFILES_ACTIVE=default - -LABEL stage=builder -LABEL service="${SERVICE_NAME}" -LABEL maintainer="Meldestelle Development Team" - -WORKDIR /workspace - -# Gradle optimizations for containerized builds -ENV GRADLE_OPTS="-Dorg.gradle.caching=true \ - -Dorg.gradle.daemon=false \ - -Dorg.gradle.parallel=true \ - -Dorg.gradle.configureondemand=true \ - -Xmx2g" - -# Copy gradle wrapper and configuration files first for optimal caching -COPY gradlew gradlew.bat gradle.properties settings.gradle.kts ./ -COPY gradle/ gradle/ - -# Copy platform dependencies (changes less frequently) -COPY platform/ platform/ - -# Copy root build configuration -COPY build.gradle.kts ./ - -# Copy service-specific files last (changes most frequently) -COPY ${SERVICE_PATH}/build.gradle.kts ${SERVICE_PATH}/ -COPY ${SERVICE_PATH}/src/ ${SERVICE_PATH}/src/ - -# Download and cache dependencies with BuildKit cache mount -RUN --mount=type=cache,target=/home/gradle/.gradle/caches \ - --mount=type=cache,target=/home/gradle/.gradle/wrapper \ - ./gradlew :${SERVICE_NAME}:dependencies --no-daemon --info - -# Build the application with optimizations and build cache -RUN --mount=type=cache,target=/home/gradle/.gradle/caches \ - --mount=type=cache,target=/home/gradle/.gradle/wrapper \ - ./gradlew :${SERVICE_NAME}:bootJar --no-daemon --info \ - -Pspring.profiles.active=${SPRING_PROFILES_ACTIVE} - -# =================================================================== -# Runtime Stage -# =================================================================== -FROM eclipse-temurin:${JAVA_VERSION}-jre-alpine AS runtime - -# Build arguments for runtime stage -ARG BUILD_DATE -ARG SPRING_PROFILES_ACTIVE=default -ARG SERVICE_NAME=spring-boot-service -ARG SERVICE_PORT=8080 - -# Enhanced metadata -LABEL service="${SERVICE_NAME}" \ - version="1.0.0" \ - description="Containerized Spring Boot microservice" \ - maintainer="Meldestelle Development Team" \ - java.version="${JAVA_VERSION}" \ - spring.profiles.active="${SPRING_PROFILES_ACTIVE}" \ - build.date="${BUILD_DATE}" - -# Build arguments for user configuration -ARG APP_USER=appuser -ARG APP_GROUP=appgroup -ARG APP_UID=1001 -ARG APP_GID=1001 - -WORKDIR /app - -# Update Alpine packages, install tools, create user and directories in one layer -RUN apk update && \ - apk upgrade && \ - apk add --no-cache \ - curl \ - tzdata && \ - rm -rf /var/cache/apk/* && \ - addgroup -g ${APP_GID} -S ${APP_GROUP} && \ - adduser -u ${APP_UID} -S ${APP_USER} -G ${APP_GROUP} -h /app -s /bin/sh && \ - mkdir -p /app/logs /app/tmp && \ - chown -R ${APP_USER}:${APP_GROUP} /app - -# Copy the built JAR from builder stage with proper ownership -COPY --from=builder --chown=${APP_USER}:${APP_GROUP} \ - /workspace/${SERVICE_PATH}/build/libs/*.jar app.jar - -# Switch to non-root user -USER ${APP_USER} - -# Expose application port and debug port -EXPOSE ${SERVICE_PORT} 5005 - -# Enhanced health check with better configuration -HEALTHCHECK --interval=15s --timeout=3s --start-period=40s --retries=3 \ - CMD curl -fsS --max-time 2 http://localhost:${SERVICE_PORT}/actuator/health/readiness || exit 1 - -# Optimized JVM settings for Spring Boot 3.x with Java 25 and monitoring support -ENV JAVA_OPTS="-XX:MaxRAMPercentage=80.0 \ - -XX:+UseG1GC \ - -XX:+UseStringDeduplication \ - -XX:+UseContainerSupport \ - -Djava.security.egd=file:/dev/./urandom \ - -Djava.awt.headless=true \ - -Dfile.encoding=UTF-8 \ - -Duser.timezone=Europe/Vienna \ - -Dmanagement.endpoints.web.exposure.include=health,info,metrics,prometheus \ - -Dmanagement.endpoint.health.show-details=always \ - -Dmanagement.metrics.export.prometheus.enabled=true" - -# Spring Boot configuration -ENV SPRING_OUTPUT_ANSI_ENABLED=ALWAYS \ - SPRING_PROFILES_ACTIVE=${SPRING_PROFILES_ACTIVE} \ - SERVER_PORT=${SERVICE_PORT} \ - LOGGING_LEVEL_ROOT=INFO - -# Enhanced entrypoint with conditional debug support and better logging -ENTRYPOINT ["sh", "-c", "\ - echo 'Starting ${SERVICE_NAME} with Java ${JAVA_VERSION}...'; \ - echo 'Active Spring profiles: ${SPRING_PROFILES_ACTIVE}'; \ - if [ \"${DEBUG:-false}\" = \"true\" ]; then \ - echo 'DEBUG mode enabled - remote debugging available on port 5005'; \ - exec java ${JAVA_OPTS} -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar; \ - else \ - echo 'Starting application in production mode'; \ - exec java ${JAVA_OPTS} -jar app.jar; \ - fi"] -``` - -### Web-Client Template - -**Datei:** `dockerfiles/templates/kotlin-multiplatform-web.Dockerfile` - -```dockerfile -# =================================================================== -# Multi-stage Dockerfile for Kotlin Multiplatform Web Client -# =================================================================== - -# =================================================================== -# Build Stage - Kotlin/JS Compilation -# =================================================================== -FROM gradle:8.14-jdk21-alpine AS kotlin-builder - -WORKDIR /workspace - -# Copy build configuration -COPY gradlew gradlew.bat gradle.properties settings.gradle.kts ./ -COPY gradle/ gradle/ -COPY build.gradle.kts ./ - -# Copy client modules -COPY client/ client/ -COPY platform/ platform/ - -# Build web application -RUN ./gradlew :client:web-app:jsBrowserProductionWebpack --no-daemon - -# =================================================================== -# Production Stage - Nginx serving -# =================================================================== -FROM nginx:alpine AS runtime - -# Security and system setup -RUN apk update && \ - apk add --no-cache curl && \ - rm -rf /var/cache/apk/* - -# Copy built web application -COPY --from=kotlin-builder /workspace/client/web-app/build/dist/ /usr/share/nginx/html/ - -# Copy nginx configuration -COPY client/web-app/nginx.conf /etc/nginx/nginx.conf - -# Health check -HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \ - CMD curl -f http://localhost:80/ || exit 1 - -EXPOSE 80 - -# Start nginx -CMD ["nginx", "-g", "daemon off;"] -``` - ---- - -## 🚀 Moderne Docker-Features und Optimierungen - -### BuildKit Cache Mounts - -Unsere Templates nutzen moderne **BuildKit Cache Mounts** für optimale Build-Performance: - -```dockerfile -# BuildKit Cache Mount für Gradle Dependencies -RUN --mount=type=cache,target=/home/gradle/.gradle/caches \ - --mount=type=cache,target=/home/gradle/.gradle/wrapper \ - ./gradlew :${SERVICE_NAME}:dependencies --no-daemon --info -``` - -**Vorteile:** -- **Erheblich schnellere Builds**: Dependencies werden zwischen Builds gecacht -- **Geringerer Netzwerk-Traffic**: Erneute Downloads werden vermieden -- **Konsistente Build-Zeiten**: Vorhersagbare Performance auch bei häufigen Builds -- **CI/CD Optimierung**: Drastische Reduktion der Pipeline-Laufzeiten - -### Docker Syntax und Versioning - -```dockerfile -# Verwendung der neuesten Dockerfile-Syntax für erweiterte Features -# syntax=docker/dockerfile:1.8 -``` - -**Moderne Features:** -- **Cache Mounts**: Persistente Build-Caches zwischen Container-Builds -- **Secret Mounts**: Sichere Übertragung von Build-Secrets ohne Layer-Persistierung -- **SSH Mounts**: Sichere Git-Repository-Zugriffe während des Builds -- **Multi-Platform Builds**: Unterstützung für ARM64 und AMD64 Architekturen - -### Container Testing und Validation - -**Automatisierte Dockerfile-Tests mit `test-dockerfile.sh`:** - -```bash -# Vollständige Template-Validierung -./test-dockerfile.sh - -# Tests umfassen: -# 1. Dockerfile-Syntax-Validierung -# 2. ARG-Deklarationen-Prüfung -# 3. Build-Tests mit Default-Argumenten -# 4. Build-Tests mit Custom-Argumenten -# 5. Container-Startup-Verifikation -# 6. Service-Health-Checks -``` - -**Test-Kategorien:** -- **Syntax-Tests**: Docker-Parser-Validierung ohne vollständigen Build -- **Build-Tests**: Vollständige Container-Builds mit verschiedenen Parametern -- **Runtime-Tests**: Container-Startup und Service-Health-Prüfungen -- **Cleanup-Tests**: Automatische Bereinigung von Test-Artefakten - ---- - -## 🎼 Docker-Compose Organisation - -### Multi-Environment Strategie - -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 -├── docker-compose.clients.yml # 🆕 Client Applications -└── docker-compose.override.yml # 🆕 Local Development Overrides -``` - -### Verwendungsszenarien - -#### 🏠 Lokale Entwicklung - vollständiges System - -```bash -# Alle Services einschließlich Clients -docker-compose \ - -f docker-compose.yaml \ - -f docker-compose.services.yaml \ - -f docker-compose.frontend.yaml \ - up -d - -# Nur Infrastructure für Backend-Entwicklung -docker-compose -f docker-compose.yaml up -d postgres redis kafka consul zipkin - -# Mit Debug-Unterstützung für Service-Entwicklung -DEBUG=true SPRING_PROFILES_ACTIVE=docker \ -docker-compose -f docker-compose.yaml -f docker-compose.services.yaml up -d - -# Mit Live-Reload für Frontend-Entwicklung -docker-compose -f docker-compose.yaml -f docker-compose.override.yml up -d -``` - -#### 🔧 Erweiterte Umgebungskonfiguration - -**Beispiel für Auth-Server Konfiguration:** - -```yaml -# Erweiterte Environment-Variablen aus docker-compose.services.yaml -auth-server: - environment: - # Spring Boot Configuration - - SPRING_PROFILES_ACTIVE=docker - - SERVER_PORT=8081 - - DEBUG=false - - # Service Discovery - - SPRING_CLOUD_CONSUL_HOST=consul - - SPRING_CLOUD_CONSUL_PORT=8500 - - # Database Configuration mit Connection Pooling - - SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/meldestelle - - SPRING_DATASOURCE_HIKARI_MAXIMUM_POOL_SIZE=10 - - SPRING_DATASOURCE_HIKARI_MINIMUM_IDLE=5 - - # Redis Configuration mit Timeout-Einstellungen - - SPRING_REDIS_HOST=redis - - SPRING_REDIS_TIMEOUT=2000ms - - SPRING_REDIS_LETTUCE_POOL_MAX_ACTIVE=8 - - # Security & JWT Configuration - - JWT_SECRET=meldestelle-auth-secret-key-change-in-production - - JWT_EXPIRATION=86400 - - JWT_REFRESH_EXPIRATION=604800 - - # Monitoring & Observability - - MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE=health,info,metrics,prometheus,configprops - - MANAGEMENT_ENDPOINT_HEALTH_SHOW_DETAILS=always - - MANAGEMENT_TRACING_SAMPLING_PROBABILITY=0.1 - - MANAGEMENT_ZIPKIN_TRACING_ENDPOINT=http://zipkin:9411/api/v2/spans - - # Performance Tuning - - JAVA_OPTS=-XX:MaxRAMPercentage=75.0 -XX:+UseG1GC - - LOGGING_LEVEL_AT_MOCODE=DEBUG - - # Resource Constraints - deploy: - resources: - limits: - memory: 512M - cpus: '1.0' - reservations: - memory: 256M - cpus: '0.5' -``` - -#### 🚀 Production Deployment - -```bash -# Production - Optimiert und sicher -docker-compose \ - -f docker-compose.prod.yml \ - -f docker-compose.services.yaml \ - up -d - -# Mit spezifischen Environment-Variablen -export POSTGRES_PASSWORD=$(openssl rand -base64 32) -export REDIS_PASSWORD=$(openssl rand -base64 32) -docker-compose -f docker-compose.prod.yml up -d -``` - -#### 🧪 Testing Environment - -```bash -# Nur notwendige Services für Tests -docker-compose -f docker-compose.yaml up -d postgres redis -./gradlew test - -# End-to-End Tests -docker-compose -f docker-compose.yaml -f docker-compose.services.yaml up -d -./gradlew :client:web-app:jsTest -``` - -### Service-Abhängigkeiten - -```yaml -# Typische Service-Abhängigkeiten in unserer Architektur -depends_on: - postgres: - condition: service_healthy - consul: - condition: service_healthy - redis: - condition: service_healthy -``` - ---- - -## 🛠️ Development-Workflow - -### Schnellstart-Befehle - -```bash -# 🚀 Komplettes Development-Setup -make dev-up # Startet alle Development-Services -make dev-down # Stoppt alle Services -make dev-logs # Zeigt Logs aller Services -make dev-restart # Neustart aller Services - -# 🔧 Service-spezifische Befehle -make service-build SERVICE=ping-service # Service neu bauen -make service-logs SERVICE=ping-service # Service-Logs anzeigen -make service-restart SERVICE=ping-service # Service neustarten -``` - -**Makefile-Beispiel:** - -```makefile -# Development commands -.PHONY: dev-up dev-down dev-logs dev-restart - -dev-up: - docker-compose -f docker-compose.yml -f docker-compose.services.yml up -d - @echo "🚀 Development environment started" - @echo "📊 Grafana: http://localhost:3000 (admin/admin)" - @echo "🔍 Prometheus: http://localhost:9090" - @echo "🚪 API Gateway: http://localhost:8080" - -dev-down: - docker-compose -f docker-compose.yml -f docker-compose.services.yml down - -dev-logs: - docker-compose -f docker-compose.yml -f docker-compose.services.yml logs -f - -dev-restart: - $(MAKE) dev-down - $(MAKE) dev-up - -# Service-specific commands -service-build: - @test -n "$(SERVICE)" || (echo "❌ SERVICE parameter required"; exit 1) - docker-compose -f docker-compose.yml -f docker-compose.services.yml build $(SERVICE) - -service-logs: - @test -n "$(SERVICE)" || (echo "❌ SERVICE parameter required"; exit 1) - docker-compose logs -f $(SERVICE) - -service-restart: - @test -n "$(SERVICE)" || (echo "❌ SERVICE parameter required"; exit 1) - docker-compose -f docker-compose.yml -f docker-compose.services.yml restart $(SERVICE) -``` - -### Hot-Reload Development - -**docker-compose.override.yml** für optimierte Entwicklung: - -```yaml -# Development overrides für Hot-Reload -version: '3.8' - -services: - web-client: - volumes: - - ./client/web-app/src:/app/src:ro - - ./client/common-ui/src:/app/common-ui/src:ro - environment: - - NODE_ENV=development - command: npm run dev - - ping-service: - environment: - - DEBUG=true - - SPRING_DEVTOOLS_RESTART_ENABLED=true - ports: - - "5005:5005" # Debug-Port - volumes: - - ./temp/ping-service/src:/workspace/src:ro -``` - -### Debugging von Services - -```bash -# Service im Debug-Modus starten -docker-compose -f docker-compose.yaml up -d ping-service -docker-compose exec ping-service sh - -# Logs in Echtzeit verfolgen -docker-compose logs -f ping-service api-gateway - -# Health-Check Status prüfen -curl -s http://localhost:8082/actuator/health | jq -curl -s http://localhost:8080/actuator/health | jq -``` - ---- - -## 🚀 Production-Deployment - -### Security Hardening - -Unsere Production-Konfiguration implementiert umfassende Sicherheitsmaßnahmen: - -#### 🔒 SSL/TLS Everywhere - -```bash -# TLS-Zertifikate vorbereiten -mkdir -p config/ssl/{postgres,redis,keycloak,grafana,prometheus,nginx} - -# Let's Encrypt Zertifikate generieren -certbot certonly --dns-route53 -d api.meldestelle.at -certbot certonly --dns-route53 -d auth.meldestelle.at -certbot certonly --dns-route53 -d monitor.meldestelle.at -``` - -#### 🛡️ Environment Variables - -**Erforderliche Production-Variablen:** - -```bash -# Datenschutz und Sicherheit -export POSTGRES_USER=meldestelle_prod -export POSTGRES_PASSWORD=$(openssl rand -base64 32) -export POSTGRES_DB=meldestelle_prod -export REDIS_PASSWORD=$(openssl rand -base64 32) - -# Keycloak Admin -export KEYCLOAK_ADMIN=admin -export KEYCLOAK_ADMIN_PASSWORD=$(openssl rand -base64 32) -export KC_DB_PASSWORD=${POSTGRES_PASSWORD} -export KC_HOSTNAME=auth.meldestelle.at - -# Monitoring -export GF_SECURITY_ADMIN_USER=admin -export GF_SECURITY_ADMIN_PASSWORD=$(openssl rand -base64 32) -export GRAFANA_HOSTNAME=monitor.meldestelle.at -export PROMETHEUS_HOSTNAME=metrics.meldestelle.at - -# Kafka Security -export KAFKA_BROKER_ID=1 -export KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181 -``` - -#### 🌐 Reverse Proxy Configuration - -**nginx.prod.conf** Beispiel: - -```nginx -upstream api_backend { - server api-gateway:8080; - keepalive 32; -} - -upstream auth_backend { - server keycloak:8443; - keepalive 32; -} - -upstream monitoring_backend { - server grafana:3443; - keepalive 32; -} - -server { - listen 443 ssl http2; - server_name api.meldestelle.at; - - ssl_certificate /etc/ssl/nginx/api.meldestelle.at.crt; - ssl_certificate_key /etc/ssl/nginx/api.meldestelle.at.key; - - # Security headers - add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; - add_header X-Frame-Options DENY always; - add_header X-Content-Type-Options nosniff always; - add_header Referrer-Policy strict-origin-when-cross-origin always; - - location / { - proxy_pass http://api_backend; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } -} -``` - -### Resource Limits - -Alle Production-Services haben definierte Resource-Limits: - -```yaml -# Beispiel für Resource-Management -services: - postgres: - deploy: - resources: - limits: - memory: 1G - cpus: '0.5' - reservations: - memory: 512M - cpus: '0.25' - - api-gateway: - deploy: - resources: - limits: - memory: 512M - cpus: '0.5' - reservations: - memory: 256M - cpus: '0.25' -``` - ---- - -## 📊 Monitoring und Observability - -### Prometheus Metrics - -Alle Services exposieren standardisierte Metrics: - -```yaml -# Service-Labels für Prometheus Autodiscovery -labels: - - "prometheus.scrape=true" - - "prometheus.port=8080" - - "prometheus.path=/actuator/prometheus" - - "prometheus.service=${SERVICE_NAME}" -``` - -### Grafana Dashboards - -**Vorgefertigte Dashboards:** - -- **Infrastructure Overview**: CPU, Memory, Disk, Network -- **Spring Boot Services**: JVM Metrics, HTTP Requests, Circuit Breaker -- **Database Performance**: PostgreSQL Connections, Query Performance -- **Message Queue**: Kafka Consumer Lag, Throughput -- **Business Metrics**: Application-spezifische KPIs - -### 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 | - -### Log Aggregation - -```bash -# Centralized logging mit ELK Stack (optional) -docker-compose -f docker-compose.yaml -f docker-compose.logging.yml up -d - -# Log-Parsing für strukturierte Logs -docker-compose logs --follow --tail=100 api-gateway | jq -r '.message' -``` - ---- - -## 🔧 Troubleshooting - -### Häufige Probleme und Lösungen - -#### 🚫 Port-Konflikte - -```bash -# Überprüfe, welche Ports verwendet werden -netstat -tulpn | grep :8080 -lsof -i :8080 - -# Stoppe konfligierende Services -docker-compose down -sudo systemctl stop apache2 # Falls Apache läuft -``` - -#### 🐌 Langsame Startup-Zeiten - -```bash -# Überprüfe Container-Ressourcen -docker stats - -# Health-Check Logs analysieren -docker-compose logs ping-service | grep health - -# Java Startup optimieren -export JAVA_OPTS="$JAVA_OPTS -XX:TieredStopAtLevel=1 -noverify" -``` - -#### 💾 Disk-Space Probleme - -```bash -# Docker-Cleanup -docker system prune -a --volumes -docker volume prune - -# Log-Rotation für Container -docker-compose logs --tail=1000 > /dev/null # Truncate logs -``` - -#### 🌐 Service Discovery Issues - -```bash -# Consul Status prüfen -curl -s http://localhost:8500/v1/health/state/any | jq - -# Service Registration überprüfen -curl -s http://localhost:8500/v1/catalog/services | jq - -# DNS-Resolution testen -docker-compose exec api-gateway nslookup ping-service -``` - -### Debug-Kommandos - -```bash -# Container introspection -docker-compose exec SERVICE_NAME sh -docker-compose exec postgres psql -U meldestelle -d meldestelle - -# Live-Monitoring -docker-compose top -watch -n 1 'docker-compose ps' - -# Memory und CPU-Usage -docker stats $(docker-compose ps -q) - -# Detailed service logs -docker-compose logs -f --tail=50 SERVICE_NAME -``` - ---- - -## ✅ Best Practices - -### 🔐 Security Best Practices - -1. **Non-Root Users**: Alle Container laufen mit dedizierten Non-Root-Usern -2. **Minimal Base Images**: Alpine Linux für kleinste Angriffsfläche -3. **Secrets Management**: Externe Secret-Stores für Production -4. **Network Isolation**: Dedizierte Docker-Networks -5. **Regular Updates**: Automatische Security-Updates für Base Images - -### ⚡ Performance Best Practices - -1. **Multi-Stage Builds**: Minimale Runtime-Images -2. **Layer Caching**: Optimale COPY-Reihenfolge in Dockerfiles -3. **Resource Limits**: Definierte Memory und CPU-Limits -4. **Health Checks**: Proaktive Container-Health-Überwachung -5. **JVM Tuning**: Container-aware JVM-Settings - -### 🧹 Wartung Best Practices - -1. **Version Pinning**: Explizite Image-Versionen in Production -2. **Backup Strategies**: Automatische Volume-Backups -3. **Log Rotation**: Begrenzte Log-Datei-Größen -4. **Documentation**: Aktuelle README-Dateien pro Service -5. **Testing**: Automatisierte Container-Tests - -### 🎯 Zentrale Verwaltung Best Practices (Version 3.2.0) - -#### **Single Source of Truth Prinzipien** - -```bash -# ✅ RICHTIG - Zentrale Version-Updates -./scripts/docker-versions-update.sh update java 22 -./scripts/docker-versions-update.sh sync - -# ❌ FALSCH - Manuelle Bearbeitung von Dockerfiles -vim dockerfiles/services/ping-service/Dockerfile # Version hardcoden -``` - -#### **Port-Verwaltung Richtlinien** - -1. **Immer zentrale Port-Registry verwenden**: - ```toml - # docker/versions.toml - Port-Definitionen - [service-ports] - new-service = 8089 # Nächster verfügbarer Port - ``` - -2. **Port-Konflikte vor Deployment prüfen**: - ```bash - ./scripts/validate-docker-consistency.sh - ``` - -3. **Port-Ranges einhalten**: - - Infrastructure: 8081-8088 - - Services: 8082-8099 - - Monitoring: 9090-9099 - - Clients: 4000-4099 - -#### **Environment-Overrides Standards** - -1. **Environment-spezifische Konfigurationen nutzen**: - ```bash - # Development - export DOCKER_ENVIRONMENT=development - - # Production - export DOCKER_ENVIRONMENT=production - ``` - -2. **Konsistente Health-Check-Konfigurationen**: - ```toml - [environments.production] - health-check-interval = "15s" - health-check-timeout = "3s" - health-check-retries = 3 - ``` - -#### **Template-System Richtlinien** - -1. **Compose-Files aus Templates generieren**: - ```bash - # Automatische Generierung bevorzugen - ./scripts/generate-compose-files.sh - - # Manuelle Bearbeitung nur bei spezifischen Anpassungen - ``` - -2. **Service-Kategorien korrekt zuordnen**: - - `services/`: Domain-Services (ping, members, horses) - - `infrastructure/`: Platform-Services (gateway, auth, monitoring) - - `clients/`: Frontend-Anwendungen (web-app, desktop-app) - -#### **Validierung und Konsistenz** - -1. **Regelmäßige Konsistenz-Prüfungen**: - ```bash - # Bei jedem Build - ./scripts/validate-docker-consistency.sh - - # In CI/CD Pipeline integrieren - ``` - -2. **Build-Args Konsistenz**: - ```dockerfile - # ✅ RICHTIG - Zentrale Referenz - ARG GRADLE_VERSION - ARG JAVA_VERSION - - # ❌ FALSCH - Hardcodierte Versionen - ARG GRADLE_VERSION=9.0.0 - ``` - -#### **IDE-Integration Best Practices** - -1. **JSON Schema für Validierung aktivieren**: - ```json - { - "yaml.schemas": { - "./docker/schemas/versions-schema.json": "docker/versions.toml" - } - } - ``` - -2. **Automatisierte Tasks nutzen**: - - Docker: Show Versions - - Docker: Validate Consistency - - Docker: Build All Services - -### 🚀 Entwickler-Workflow Best Practices (Version 3.2.0) - -#### **Neuen Service hinzufügen** - -```bash -# 1. Port in versions.toml reservieren -echo "new-service = 8089" >> docker/versions.toml - -# 2. Template-basierten Service erstellen -cp dockerfiles/templates/spring-boot-service.Dockerfile \ - dockerfiles/services/new-service/Dockerfile - -# 3. Compose-Definition generieren -./scripts/generate-compose-files.sh - -# 4. Konsistenz validieren -./scripts/validate-docker-consistency.sh - -# 5. Build und Test -./scripts/docker-build.sh services -``` - -#### **Version-Updates Workflow** - -```bash -# 1. Zentrale Version aktualisieren -./scripts/docker-versions-update.sh update java 22 - -# 2. Environment-Files synchronisieren (automatisch) -# 3. Alle Services neu bauen -./scripts/docker-build.sh all - -# 4. Tests ausführen -docker-compose -f docker-compose.test.yml up -d -./gradlew test - -# 5. Commit und Deploy -git add docker/versions.toml docker/build-args/ -git commit -m "Update Java to version 22" -``` - -#### **Production-Deployment Workflow** - -```bash -# 1. Environment auf Production setzen -export DOCKER_ENVIRONMENT=production - -# 2. Production-spezifische Validierung -./scripts/validate-docker-consistency.sh - -# 3. Security-Konfiguration anwenden -./scripts/apply-environment.sh production - -# 4. Production-Build -docker-compose -f docker-compose.prod.yml build - -# 5. Health-Check-basiertes Deployment -docker-compose -f docker-compose.prod.yml up -d -``` - -### 📦 Build Best Practices - -```dockerfile -# ✅ Gute Praktiken -FROM eclipse-temurin:21-jre-alpine AS runtime -RUN apk update && apk upgrade && rm -rf /var/cache/apk/* -USER 1001:1001 -HEALTHCHECK --interval=30s CMD curl -f http://localhost:8080/health || exit 1 -``` - -```dockerfile -# ❌ Zu vermeidende Praktiken -FROM ubuntu:latest -RUN apt-get update -USER root -``` -**Probleme:** Zu große Base-Image, keine Versionierung, fehlende Cleanup, Sicherheitsrisiko durch Root-User, keine Health Checks - ---- - -## 📚 Weiterführende Ressourcen - -### Interne Dokumentation - -- `README.md` - Projekt-Überblick -- `README-ENV.md` - Environment-Setup -- `README-PRODUCTION.md` - Production-Deployment -- `infrastructure/*/README.md` - Service-spezifische Dokumentation - -### Externe Referenzen - -- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/) -- [Spring Boot Container Images](https://spring.io/guides/topicals/spring-boot-docker/) -- [Alpine Linux Security](https://alpinelinux.org/about/) -- [Prometheus Monitoring](https://prometheus.io/docs/guides/multi-target-exporter/) - -### Tools und Utilities - -```bash -# Nützliche Entwicklungstools -brew install docker-compose # macOS -apt-get install docker-compose-plugin # Ubuntu -pip install docker-compose # Python - -# Container-Debugging -brew install dive # Docker-Image-Layer-Analyse -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 | -| | | • **✅ 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 25 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 | - ---- - -## 🤝 Beitragen - -Änderungen an den Docker-Guidelines sollten über Pull Requests eingereicht und vom Team reviewed werden. Bei Fragen oder Verbesserungsvorschlägen bitte ein Issue erstellen. - -**Kontakt:** Meldestelle Development Team diff --git a/.junie/guidelines/_meta/cross-refs.json b/.junie/guidelines/_meta/cross-refs.json deleted file mode 100644 index 015b1201..00000000 --- a/.junie/guidelines/_meta/cross-refs.json +++ /dev/null @@ -1,217 +0,0 @@ -{ - "meta": { - "last_updated": "2025-09-15", - "description": "Cross-Referenz-Matrix für Meldestelle Guidelines", - "purpose": "Link-Validierung und Abhängigkeits-Management" - }, - "cross_references": { - "master-guideline.md": { - "references_to": [ - "project-standards/coding-standards.md", - "project-standards/architecture-principles.md", - "technology-guides/web-app-guideline.md", - "project-standards/testing-standards.md", - "technology-guides/docker/", - "project-standards/documentation-standards.md" - ], - "referenced_by": [ - "project-standards/architecture-principles.md", - "project-standards/coding-standards.md", - "project-standards/documentation-standards.md", - "project-standards/testing-standards.md", - "technology-guides/web-app-guideline.md", - "technology-guides/docker/docker-overview.md", - "process-guides/trace-bullet-guideline.md" - ] - }, - "README.md": { - "references_to": [ - "master-guideline.md", - "project-standards/coding-standards.md", - "project-standards/testing-standards.md", - "project-standards/documentation-standards.md", - "project-standards/architecture-principles.md", - "technology-guides/web-app-guideline.md", - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-architecture.md", - "technology-guides/docker/docker-development.md", - "technology-guides/docker/docker-production.md", - "technology-guides/docker/docker-monitoring.md", - "technology-guides/docker/docker-troubleshooting.md", - "process-guides/trace-bullet-guideline.md" - ], - "referenced_by": [] - }, - "project-standards/architecture-principles.md": { - "references_to": [ - "master-guideline.md" - ], - "referenced_by": [ - "README.md", - "master-guideline.md", - "technology-guides/web-app-guideline.md" - ] - }, - "project-standards/coding-standards.md": { - "references_to": [ - "master-guideline.md" - ], - "referenced_by": [ - "README.md", - "master-guideline.md" - ] - }, - "project-standards/documentation-standards.md": { - "references_to": [ - "master-guideline.md" - ], - "referenced_by": [ - "README.md", - "master-guideline.md" - ] - }, - "project-standards/testing-standards.md": { - "references_to": [ - "master-guideline.md" - ], - "referenced_by": [ - "README.md", - "master-guideline.md" - ] - }, - "technology-guides/web-app-guideline.md": { - "references_to": [ - "master-guideline.md", - "project-standards/architecture-principles.md" - ], - "referenced_by": [ - "README.md", - "master-guideline.md", - "process-guides/trace-bullet-guideline.md" - ] - }, - "technology-guides/docker/docker-overview.md": { - "references_to": [ - "master-guideline.md", - "technology-guides/docker/docker-architecture.md", - "technology-guides/docker/docker-development.md", - "technology-guides/docker/docker-production.md", - "technology-guides/docker/docker-monitoring.md", - "technology-guides/docker/docker-troubleshooting.md" - ], - "referenced_by": [ - "README.md", - "master-guideline.md", - "technology-guides/docker/docker-architecture.md", - "technology-guides/docker/docker-development.md", - "technology-guides/docker/docker-production.md", - "technology-guides/docker/docker-monitoring.md", - "technology-guides/docker/docker-troubleshooting.md" - ] - }, - "technology-guides/docker/docker-architecture.md": { - "references_to": [ - "technology-guides/docker/docker-overview.md", - "master-guideline.md" - ], - "referenced_by": [ - "README.md", - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-development.md", - "technology-guides/docker/docker-production.md", - "technology-guides/docker/docker-monitoring.md", - "technology-guides/docker/docker-troubleshooting.md" - ] - }, - "technology-guides/docker/docker-development.md": { - "references_to": [ - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-architecture.md", - "technology-guides/docker/docker-production.md", - "technology-guides/docker/docker-monitoring.md", - "technology-guides/docker/docker-troubleshooting.md" - ], - "referenced_by": [ - "README.md", - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-troubleshooting.md" - ] - }, - "technology-guides/docker/docker-production.md": { - "references_to": [ - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-architecture.md" - ], - "referenced_by": [ - "README.md", - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-development.md" - ] - }, - "technology-guides/docker/docker-monitoring.md": { - "references_to": [ - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-architecture.md" - ], - "referenced_by": [ - "README.md", - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-development.md" - ] - }, - "technology-guides/docker/docker-troubleshooting.md": { - "references_to": [ - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-architecture.md", - "technology-guides/docker/docker-development.md" - ], - "referenced_by": [ - "README.md", - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-development.md" - ] - }, - "process-guides/trace-bullet-guideline.md": { - "references_to": [ - "master-guideline.md", - "technology-guides/web-app-guideline.md" - ], - "referenced_by": [ - "README.md" - ] - } - }, - "link_validation": { - "last_check": "2025-09-15", - "broken_links": [], - "orphaned_guidelines": [], - "circular_dependencies": [], - "validation_status": "OK" - }, - "navigation_paths": { - "common_workflows": { - "new_developer_onboarding": [ - "README.md", - "master-guideline.md", - "project-standards/architecture-principles.md", - "project-standards/coding-standards.md", - "technology-guides/docker/docker-development.md" - ], - "frontend_development": [ - "technology-guides/web-app-guideline.md", - "project-standards/architecture-principles.md", - "project-standards/coding-standards.md" - ], - "docker_setup": [ - "technology-guides/docker/docker-overview.md", - "technology-guides/docker/docker-architecture.md", - "technology-guides/docker/docker-development.md" - ], - "troubleshooting": [ - "technology-guides/docker/docker-troubleshooting.md", - "technology-guides/docker/docker-development.md", - "technology-guides/docker/docker-monitoring.md" - ] - } - } -} diff --git a/.junie/guidelines/_meta/versions.json b/.junie/guidelines/_meta/versions.json deleted file mode 100644 index ea07cc58..00000000 --- a/.junie/guidelines/_meta/versions.json +++ /dev/null @@ -1,143 +0,0 @@ -{ - "meta": { - "last_updated": "2025-09-15", - "version_schema": "1.0.0", - "description": "Zentrale Versionsverwaltung für alle Meldestelle Guidelines" - }, - "guidelines": { - "master-guideline.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "master", - "scope": "project-overview", - "dependencies": [] - }, - "README.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "navigation", - "scope": "guidelines-overview", - "dependencies": [] - }, - "project-standards/architecture-principles.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "project-standards", - "scope": "architecture-principles", - "dependencies": ["master-guideline.md"] - }, - "project-standards/coding-standards.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "project-standards", - "scope": "coding-standards", - "dependencies": ["master-guideline.md"] - }, - "project-standards/documentation-standards.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "project-standards", - "scope": "documentation-standards", - "dependencies": ["master-guideline.md"] - }, - "project-standards/testing-standards.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "project-standards", - "scope": "testing-standards", - "dependencies": ["master-guideline.md"] - }, - "technology-guides/web-app-guideline.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "technology", - "scope": "web-app-multiplatform", - "dependencies": ["master-guideline.md", "architecture-principles.md"] - }, - "technology-guides/docker/docker-overview.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "technology", - "scope": "docker-overview", - "dependencies": ["master-guideline.md"] - }, - "technology-guides/docker/docker-architecture.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "technology", - "scope": "docker-architecture", - "dependencies": ["docker-overview.md", "master-guideline.md"] - }, - "technology-guides/docker/docker-development.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "technology", - "scope": "docker-development", - "dependencies": ["docker-overview.md", "docker-architecture.md"] - }, - "technology-guides/docker/docker-production.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "technology", - "scope": "docker-production", - "dependencies": ["docker-overview.md", "docker-architecture.md"] - }, - "technology-guides/docker/docker-monitoring.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "technology", - "scope": "docker-monitoring", - "dependencies": ["docker-overview.md", "docker-architecture.md"] - }, - "technology-guides/docker/docker-troubleshooting.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "technology", - "scope": "docker-troubleshooting", - "dependencies": ["docker-overview.md", "docker-architecture.md", "docker-development.md"] - }, - "process-guides/trace-bullet-guideline.md": { - "version": "2.1.0", - "status": "aktiv", - "last_updated": "2025-09-15", - "type": "process-guide", - "scope": "trace-bullet-development-cycle", - "dependencies": ["master-guideline.md", "web-app-guideline.md"] - } - }, - "archived": { - "_archived/docker-guideline-v3.0.1-archived-2025-09-15.md": { - "version": "3.0.1", - "status": "archiviert", - "archived_date": "2025-09-15", - "reason": "Redundant zu modularen Docker-Guides", - "type": "technology", - "scope": "docker-monolithic" - } - }, - "statistics": { - "total_guidelines": 14, - "active_guidelines": 14, - "archived_guidelines": 1, - "last_optimization": "2025-09-15", - "optimization_details": { - "eliminated_redundancy": "69KB (docker-guideline.md)", - "standardized_headers": "14 Guidelines", - "unified_version": "2.1.0", - "language": "Deutsch" - } - } -} diff --git a/.junie/guidelines/_templates/process-guide-template.md b/.junie/guidelines/_templates/process-guide-template.md deleted file mode 100644 index 8cd42950..00000000 --- a/.junie/guidelines/_templates/process-guide-template.md +++ /dev/null @@ -1,165 +0,0 @@ -# {{NAME}} - Prozess-Richtlinie - ---- - -guideline_type: "process-guide" -scope: "{{SCOPE}}" -audience: ["developers", "ai-assistants", "project-managers"] -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 - -Dieser Guide beschreibt den standardisierten Workflow für {{SCOPE}} im Meldestelle-Projekt. - -> **🤖 AI-Assistant Hinweis:** -> Dieser Prozess ist optimiert für Effizienz und Qualitätssicherung: -> - **Eingabe:** [Was wird als Input benötigt] -> - **Ausgabe:** [Was wird als Output produziert] -> - **Dauer:** [Geschätzte Zeitdauer] -> - **Beteiligte:** [Rollen und Verantwortlichkeiten] - -## 📋 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] -- [ ] [Stakeholder informiert] - -## ⚠️ Häufige Fallstricke - -### 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] - -**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] - -## 🔧 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] | - -### Optionale Tools - -| 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] - -## 🚨 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] - -## 📋 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 -- [ ] Stakeholder informiert - -## 🔗 Navigation - -- [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}} -**Nächste Überprüfung:** [Datum oder Trigger] -**Verantwortlicher:** [Name/Team] diff --git a/.junie/guidelines/_templates/project-standard-template.md b/.junie/guidelines/_templates/project-standard-template.md deleted file mode 100644 index e39ef0da..00000000 --- a/.junie/guidelines/_templates/project-standard-template.md +++ /dev/null @@ -1,92 +0,0 @@ -# {{NAME}} - Standards und Richtlinien - ---- - -guideline_type: "project-standards" -scope: "{{SCOPE}}" -audience: ["developers", "ai-assistants", "architects"] -last_updated: "{{DATE}}" -dependencies: ["master-guideline.md"] -related_files: [] -ai_context: "{{SCOPE}}-Standards und Best Practices für das Meldestelle-Projekt" - ---- - -## 🎯 Überblick - -Diese Richtlinie definiert die verbindlichen Standards und Best Practices für {{SCOPE}} im Meldestelle-Projekt. - -> **🤖 AI-Assistant Hinweis:** -> Diese Standards sind verbindlich für alle {{SCOPE}}-Entscheidungen und -Implementierungen. -> - **Scope:** {{SCOPE}} -> - **Verbindlich:** Ja, alle Entwickler müssen diese Standards befolgen -> - **Updates:** Bei Änderungen wird last_updated aktualisiert - -## 📋 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 [Weiteres Problem] - -**Ursache:** [Warum tritt es auf] -**Lösung:** [konkrete Lösung] - -## 📊 Checkliste - -- [ ] Grundprinzipien verstanden und akzeptiert -- [ ] Implementierungsrichtlinien befolgt -- [ ] Qualitätssicherung durchgeführt -- [ ] Dokumentation aktualisiert -- [ ] Code-Review abgeschlossen - -## 🔗 Navigation - -- [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}} -**Nächste Überprüfung:** [Bei Bedarf oder regelmäßig] diff --git a/.junie/guidelines/_templates/technology-guideline-template.md b/.junie/guidelines/_templates/technology-guideline-template.md deleted file mode 100644 index 34611b22..00000000 --- a/.junie/guidelines/_templates/technology-guideline-template.md +++ /dev/null @@ -1,117 +0,0 @@ -# [TECHNOLOGIE-NAME] Guidelines - ---- - -guideline_type: "technology" -scope: "[spezifischer-bereich-identifier]" -audience: ["developers", "ai-assistants", "devops"] -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 - -[Kurze Einführung in die Technologie und ihre Rolle im Meldestelle-Projekt] - -### Grundprinzipien - -- **Prinzip 1**: Beschreibung -- **Prinzip 2**: Beschreibung -- **Prinzip 3**: Beschreibung - -> **🤖 AI-Assistant Hinweis:** -> [Wichtige Informationen für KI-Assistenten, URLs, Ports, etc.] - -## 📋 [HAUPTBEREICH 1] - -### [Unterbereich 1.1] - -[Detaillierte Beschreibung mit Code-Beispielen] - -```bash -# Beispiel-Befehle -[command-examples] -``` - -### [Unterbereich 1.2] - -[Weitere technische Details] - -## 🎯 AI-Assistenten: [TECHNOLOGIE]-Schnellreferenz - -### Häufige Aufgaben - -| Aufgabe | Befehl | Beschreibung | -|----------|-------------|----------------| -| [Task 1] | `[command]` | [Beschreibung] | -| [Task 2] | `[command]` | [Beschreibung] | -| [Task 3] | `[command]` | [Beschreibung] | - -### Wichtige URLs/Endpoints -- **[Service 1]:** http://localhost:[PORT] -- **[Service 2]:** http://localhost:[PORT] -- **[Monitoring]:** http://localhost:[PORT] - -### Debug-Commands - -```bash -# [Debug-Zweck] -[debug-commands] - -# [Troubleshooting-Zweck] -[troubleshooting-commands] -``` - -## 🔧 [HAUPTBEREICH 2] - -### [Konfiguration/Setup] - -[Konfigurationsdetails mit Beispielen] - -### [Best Practices] - -1. **[Practice 1]:** [Beschreibung] -2. **[Practice 2]:** [Beschreibung] -3. **[Practice 3]:** [Beschreibung] - -## 📊 Monitoring und Observability - -[Monitoring-spezifische Informationen, falls relevant] - -### Metrics - -| Metric | Typ | Beschreibung | -|-----------------|-------|----------------| -| `[metric_name]` | [Typ] | [Beschreibung] | - -## 🚨 Troubleshooting - -### Häufige Probleme - -#### [Problem 1] - -```bash -# Diagnose -[diagnostic-commands] - -# Lösung -[solution-commands] -``` - -#### [Problem 2] - -[Weitere Problemlösungen] - ---- - -**Navigation:** -- [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 - ---- - -> **Basis-Prinzipien:** Diese Guidelines erweitern die [Master-Guideline](../master-guideline.md) um [TECHNOLOGIE]-spezifische Aspekte und folgen den allgemeinen Projektstandards. diff --git a/.junie/guidelines/master-guideline.md b/.junie/guidelines/master-guideline.md deleted file mode 100644 index 4385fb66..00000000 --- a/.junie/guidelines/master-guideline.md +++ /dev/null @@ -1,98 +0,0 @@ -# Meldestelle_Pro: Entwicklung-Guideline - -**Status:** Finalisiert & verbindlich -**Version:** 2.1.0 -**Stand:** 15. September 2025 - -## 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. - -Unsere Architektur basiert auf **vier Säulen**: - -1. **Modularität & Skalierbarkeit** durch eine **Microservices-Architektur** -2. **Fachlichkeit im Code** durch **Domain-Driven Design (DDD)** -3. **Entkopplung & Resilienz** durch eine **ereignisgesteuerte Architektur (EDA)** -4. **Effizienz & Konsistenz** durch eine **Multiplattform-Client-Strategie (KMP)** - -> **Grundsatz:** Jede Code-Änderung muss diese vier Grundprinzipien respektieren. - ---- - -## 2. Coding Standards & Code-Qualität - -Detaillierte Coding-Standards und Qualitätsrichtlinien finden Sie in: -**→ [Coding Standards](./project-standards/coding-standards.md)** - -Kernpunkte: -- **Primärsprache:** Kotlin (JVM/Multiplatform) mit Java 25+ Kompatibilität -- **Namenskonventionen:** PascalCase für Klassen, camelCase für Funktionen -- **Value Classes:** Typsichere Wrapper für primitive Typen -- **Result-Pattern:** Für erwartbare Geschäftsfehler -- **Structured Logging:** Mit Korrelations-IDs - ---- - -## 3. Architecture Principles & Backend-Entwicklung - -Detaillierte Architektur-Prinzipien und Backend-Entwicklungsrichtlinien finden Sie in: -**→ [Architecture Principles](./project-standards/architecture-principles.md)** - -Kernpunkte: -- **Clean Architecture:** 4-Layer-Struktur (api, application, domain, infrastructure) -- **DDD:** Domain-Driven Design mit Bounded Contexts -- **EDA:** Event-Driven Architecture mit Kafka -- **Repository-Pattern:** Alle Methoden verwenden Result-Pattern - ---- - -## 4. Frontend-Entwicklung & Multiplatform - -Detaillierte Frontend-Entwicklungsrichtlinien finden Sie in: -**→ [Web-App Guideline](./technology-guides/web-app-guideline.md)** - -Kernpunkte: -- **MVVM-Pattern:** Model-View-ViewModel für UI-Struktur -- **Kotlin Multiplatform:** Codesharing zwischen Desktop und Web -- **Compose Multiplatform:** Deklarative UI mit @Composable-Funktionen -- **Feature-basierte Struktur:** Vertikale Schnitte nach Fachlichkeit - ---- - -## 5. Testing Standards - -Detaillierte Testing-Standards finden Sie in: -**→ [Testing Standards](./project-standards/testing-standards.md)** - -Kernpunkte: -- **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 - ---- - -## 6. Docker & Infrastructure - -Detaillierte Docker- und Infrastruktur-Richtlinien finden Sie in: -**→ [Docker Guidelines](./technology-guides/docker)** - -Kernpunkte: -- **Docker-Architektur:** Microservices mit Service Discovery -- **Zentrale Versionsverwaltung:** Single Source of Truth -- **Monitoring:** Prometheus & Grafana -- **Security:** Non-Root-Container, SSL/TLS everywhere - ---- - -## 7. Documentation Standards - -Detaillierte Dokumentationsstandards finden Sie in: -**→ [Documentation Standards](./project-standards/documentation-standards.md)** - -Kernpunkte: -- **Sprache:** README-Dateien auf Deutsch, Code-Kommentare je nach Kontext -- **Struktur:** Einheitliche README-Template -- **API-Docs:** OpenAPI-Annotationen mit deutschen Beschreibungen -- **Versionierung:** Dokumentation wird mit Code versioniert diff --git a/.junie/guidelines/process-guides/trace-bullet-guideline.md b/.junie/guidelines/process-guides/trace-bullet-guideline.md deleted file mode 100644 index d7352376..00000000 --- a/.junie/guidelines/process-guides/trace-bullet-guideline.md +++ /dev/null @@ -1,141 +0,0 @@ -# Guideline: Zyklus "Tracer Bullet" - ---- - -guideline_type: "process-guide" -scope: "trace-bullet-development-cycle" -audience: ["developers", "ai-assistants", "project-managers"] -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 -* **Status:** In Arbeit -* **Basis:** Diese Guideline erweitert die [Master-Guideline](../master-guideline.md) -* **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: -> - **Ziel:** Technische Infrastruktur von Client bis Backend testen -> - **Ping-Service:** Minimaler Test-Service für Architektur-Validierung -> - **MVVM:** Client folgt strikt dem MVVM-Pattern mit Compose Multiplatform -> - **Definition of Done:** Vollständiger E2E-Test muss erfolgreich sein - -## 1. Ziel des Zyklus - -Das oberste und einzige Ziel dieses Entwicklungszyklus ist die **Validierung der gesamten technischen Architektur -End-to-End**. Wir wollen beweisen, dass eine Anfrage vom Client den gesamten technischen Stack (Gateway, Service -Discovery, Backend-Service) erfolgreich durchlaufen und eine Antwort zurückliefern kann. - -Am Ende dieses Zyklus werden wir einen stabilen, qualitätsgesicherten und dokumentierten Unterbau haben, auf dem die -Entwicklung der fachlichen Features aufsetzen kann. - -## 2. Umfang (Was gehört zu diesem Zyklus?) - -Die folgenden Module und Aufgaben sind Teil dieses Zyklus: - -### 2.1. Backend-Infrastruktur (`:core` & `:infrastructure`): - -* Vollständige Überarbeitung, Optimierung und Testabdeckung aller Infrastruktur-Module (`cache`, `event-store`, - `auth`, `messaging`, `monitoring`, `gateway`). -* Implementierung einer robusten Logging- und Konfigurations-Infrastruktur. - -### 2.2. Temporärer Test-Service (`:temp:ping-service`): - -* Erstellung eines minimalen Spring-Boot-Service, der nur einen `GET /ping`-Endpunkt bereitstellt. - -* **Frontend-Infrastruktur (`:client`):** - * Aufbau einer sauberen, leeren Grundstruktur für die Kotlin Multiplatform App nach dem MVVM-Muster. - * Implementierung einer minimalen UI mit einem "Ping"-Button und einem Anzeigefeld für die Antwort. - -### 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`](../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. - 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. - -## 3. Spezifische Richtlinien für diesen Zyklus - -* **Fokus auf Technik, nicht Fachlichkeit:** Jede Zeile Code, die in diesem Zyklus geschrieben wird, dient - 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 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. - -## 4. Definition of Done (Wann sind wir fertig?) - -Dieser Zyklus ist abgeschlossen, wenn **alle** der folgenden Kriterien erfüllt sind: - -* [x] Alle `:core` und `:infrastructure`-Module wurden überarbeitet, sind fehlerfrei testbar und ihre `README.md` - -Dateien sind auf dem neuesten Stand. -* [x] Der `:temp:ping-service` ist implementiert, getestet und lauffähig. -* [ ] Die `:client:web-app` ist mit einer sauberen MVVM-Struktur aufgesetzt, startet fehlerfrei und implementiert den Ping-Test mit **Compose for Web**. -* [ ] **Der End-to-End "Tracer Bullet"-Test ist erfolgreich:** - * [ ] Alle Docker-Container (`docker-compose up`) starten fehlerfrei. - * [ ] Der `gateway`-Service startet. - * [ ] Der `ping-service` startet und registriert sich erfolgreich bei Consul. - * [ ] Die `web-app` startet. - * [ ] Ein Klick auf den "Ping"-Button in der Web-App führt zu einer `GET`-Anfrage an das Gateway, wird korrekt an - den `ping-service` weitergeleitet und die Antwort `"pong"` wird erfolgreich in der UI angezeigt. -* [ ] Der gesamte `clean build` des Projekts läuft ohne Fehler und **ohne Warnungen**. *(Status: Build läuft durch, aber mit 5 Testfehlern und mehreren Kotlin-Warnungen)* -* [ ] Die `master-guideline.md` und die `trace-bullet-guideline.md` sind finalisiert. - ---- - -## 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 - - `:temp:ping-service` mit README_TEMP.md - - `: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) - - Multiple Kotlin-Warnungen und Deprecation-Warnings -3. **Funktionale Validierung:** Ohne Docker-Umgebung nicht testbar -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 -4. Docker-Umgebung einrichten und End-to-End-Test durchführen -5. Master-Guideline finalisieren - ---- - -## 5. Lessons Learned (nach Abschluss) - -- [ ] Was hat gut funktioniert? -- [ ] Was würden wir beim nächsten Zyklus anders machen? -- [ ] Welche Standards müssen in die Master-Guideline übernommen werden? - ---- - -**Navigation:** -- [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 -- [Testing-Standards](../project-standards/testing-standards.md) - Test-Qualitätssicherung diff --git a/.junie/guidelines/project-standards/architecture-principles.md b/.junie/guidelines/project-standards/architecture-principles.md deleted file mode 100644 index a435beaa..00000000 --- a/.junie/guidelines/project-standards/architecture-principles.md +++ /dev/null @@ -1,509 +0,0 @@ -# Architecture Principles und Grundsätze - ---- - -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 - -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. - -> **🤖 AI-Assistant Hinweis:** -> Die Architektur basiert auf vier Kernsäulen: -> - **Microservices:** Modularität & Skalierbarkeit -> - **DDD:** Fachlichkeit im Code -> - **EDA:** Ereignisgesteuerte Entkopplung -> - **KMP:** Kotlin Multiplatform für Effizienz - -### Die vier Säulen der Architektur - -1. **Modularität & Skalierbarkeit** durch eine **Microservices-Architektur** -2. **Fachlichkeit im Code** durch **Domain-Driven Design (DDD)** -3. **Entkopplung & Resilienz** durch eine **ereignisgesteuerte Architektur (EDA)** -4. **Effizienz & Konsistenz** durch eine **Multiplattform-Client-Strategie (KMP)** - -> **Grundsatz:** Jede Code-Änderung muss diese vier Grundprinzipien respektieren. - -## 🎯 AI-Assistenten: Architektur-Schnellreferenz - -### 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 | - -## 🔧 Backend-Entwicklungsrichtlinien - -### Microservice-Struktur (Clean Architecture) - -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 -├── service-name-domain/ # Domain Models, Events, Services -└── service-name-infrastructure/ # Repositories, External Services -``` - -#### Layer-Verantwortlichkeiten - -**API Layer (`-api`):** -```kotlin -@RestController -@RequestMapping("/api/v1/members") -class MemberController( - private val memberService: MemberService -) { - @PostMapping - fun createMember(@RequestBody request: CreateMemberRequest): ResponseEntity { - val command = CreateMemberCommand( - name = request.name, - email = request.email, - licenseNumber = request.licenseNumber - ) - - return when (val result = memberService.createMember(command)) { - is Result.Success -> ResponseEntity.ok(result.value.toResponse()) - is Result.Failure -> ResponseEntity.badRequest().body(result.error.toErrorResponse()) - } - } -} -``` - -**Application Layer (`-application`):** -```kotlin -@Service -class MemberService( - private val memberRepository: MemberRepository, - private val eventPublisher: EventPublisher -) { - suspend fun createMember(command: CreateMemberCommand): Result { - // Validation - val validationResult = validateCreateMemberCommand(command) - if (validationResult is Result.Failure) { - return validationResult - } - - // Business Logic - val member = Member.create( - name = command.name, - email = command.email, - licenseNumber = command.licenseNumber - ) - - // Persistence - return memberRepository.save(member).map { - // Event Publishing - eventPublisher.publish(MemberCreatedEvent(member)) - member - } - } -} -``` - -**Domain Layer (`-domain`):** -```kotlin -@JvmInline -value class MemberId(val value: UUID) { - companion object { - fun generate(): MemberId = MemberId(UUID.randomUUID()) - } -} - -data class Member( - val id: MemberId, - val name: String, - val email: Email, - val licenseNumber: LicenseNumber, - val status: MemberStatus = MemberStatus.PENDING -) { - companion object { - fun create( - name: String, - email: String, - licenseNumber: String - ): Result { - return Result.Success( - Member( - id = MemberId.generate(), - name = name, - email = Email.of(email).getOrThrow(), - licenseNumber = LicenseNumber.of(licenseNumber).getOrThrow() - ) - ) - } - } - - fun activate(): Member = copy(status = MemberStatus.ACTIVE) - fun suspend(): Member = copy(status = MemberStatus.SUSPENDED) -} -``` - -**Infrastructure Layer (`-infrastructure`):** -```kotlin -@Repository -class PostgresMemberRepository( - private val jdbcTemplate: JdbcTemplate -) : MemberRepository { - - override suspend fun save(member: Member): Result { - return try { - jdbcTemplate.update( - "INSERT INTO members (id, name, email, license_number, status) VALUES (?, ?, ?, ?, ?)", - member.id.value, - member.name, - member.email.value, - member.licenseNumber.value, - member.status.name - ) - Result.Success(Unit) - } catch (e: DataAccessException) { - Result.Failure(RepositoryError.DATABASE_ERROR) - } - } - - override suspend fun findById(id: MemberId): Result { - return try { - val member = jdbcTemplate.queryForObject( - "SELECT * FROM members WHERE id = ?", - arrayOf(id.value) - ) { rs, _ -> - Member( - id = MemberId(UUID.fromString(rs.getString("id"))), - name = rs.getString("name"), - email = Email.of(rs.getString("email")).getOrThrow(), - licenseNumber = LicenseNumber.of(rs.getString("license_number")).getOrThrow(), - status = MemberStatus.valueOf(rs.getString("status")) - ) - } - Result.Success(member) - } catch (e: EmptyResultDataAccessException) { - Result.Success(null) - } catch (e: DataAccessException) { - Result.Failure(RepositoryError.DATABASE_ERROR) - } - } -} -``` - -### Repository-Pattern - -Jede Repository-Methode muss das `Result`-Pattern verwenden. - -```kotlin -interface MemberRepository { - suspend fun findById(id: MemberId): Result - suspend fun save(member: Member): Result - suspend fun findByEmail(email: Email): Result - suspend fun findByLicenseNumber(licenseNumber: LicenseNumber): Result - suspend fun findAll(pageable: Pageable): Result, RepositoryError> -} -``` - -### Messaging & Event-Naming - -Event-Naming Convention: Domänen-Events folgen dem Muster `{Domain}{Entity}{Action}Event`. - -```kotlin -data class MemberPersonalDataUpdatedEvent( - val memberId: MemberId, - val oldName: String, - val newName: String, - val oldEmail: Email, - val newEmail: Email, - val updatedAt: Instant = Instant.now(), - val correlationId: String = MDC.get("correlationId") ?: UUID.randomUUID().toString() -) : DomainEvent { - override val eventType: String = "member.personal-data.updated" - override val aggregateId: String = memberId.value.toString() - override val version: Int = 1 -} -``` - -## 📱 Frontend-Entwicklungsrichtlinien - -Das Frontend folgt konsequent dem **Model-View-ViewModel (MVVM)**-Muster und der **Kotlin Multiplatform (KMP)**-Strategie. Der UI-Code wird nach **fachlichen Features** (vertikale Schnitte) strukturiert. - -### Multiplatform-Struktur - -```plaintext -client/ -├── src/commonMain/kotlin/ # Shared Business Logic -│ ├── domain/ # Domain Models -│ ├── data/ # Repositories, API-Clients -│ ├── presentation/ # ViewModels, UI-States -│ └── ui/ # Shared UI-Components -├── src/jvmMain/kotlin/ # Desktop-spezifischer Code -│ └── ui/ # Desktop UI-Adaptierungen -└── src/wasmJsMain/kotlin/ # Web-spezifischer Code - └── ui/ # Web UI-Adaptierungen -``` - -### MVVM-Implementation - -**Shared ViewModel (commonMain):** -```kotlin -class MemberListViewModel( - private val memberRepository: MemberRepository -) : ViewModel() { - - private val _uiState = MutableStateFlow(MemberListUiState()) - val uiState: StateFlow = _uiState.asStateFlow() - - fun loadMembers() { - viewModelScope.launch { - _uiState.value = _uiState.value.copy(isLoading = true) - - when (val result = memberRepository.getAllMembers()) { - is Result.Success -> { - _uiState.value = _uiState.value.copy( - isLoading = false, - members = result.value, - error = null - ) - } - is Result.Failure -> { - _uiState.value = _uiState.value.copy( - isLoading = false, - error = result.error.message - ) - } - } - } - } -} - -data class MemberListUiState( - val isLoading: Boolean = false, - val members: List = emptyList(), - val error: String? = null -) -``` - -**Shared UI-Component (commonMain):** -```kotlin -@Composable -fun MemberListScreen( - viewModel: MemberListViewModel = viewModel() -) { - val uiState by viewModel.uiState.collectAsState() - - LaunchedEffect(Unit) { - viewModel.loadMembers() - } - - Column { - if (uiState.isLoading) { - CircularProgressIndicator() - } - - uiState.error?.let { error -> - Text( - text = error, - color = MaterialTheme.colorScheme.error - ) - } - - LazyColumn { - items(uiState.members) { member -> - MemberCard( - member = member, - onMemberClick = { /* Handle click */ } - ) - } - } - } -} -``` - -## 🎯 Domain-Driven Design (DDD) Patterns - -### Bounded Contexts - -```plaintext -Meldestelle-Domain/ -├── member-context/ # Mitgliederverwaltung -├── tournament-context/ # Turnierverwaltung -├── horse-context/ # Pferdeverwaltung -├── registration-context/ # Anmeldungen -└── payment-context/ # Zahlungsabwicklung -``` - -### Aggregate Design - -```kotlin -class Tournament private constructor( - val id: TournamentId, - val name: String, - val startDate: LocalDate, - val endDate: LocalDate, - val maxParticipants: Int, - private val registrations: MutableList = mutableListOf() -) { - companion object { - fun create( - name: String, - startDate: LocalDate, - endDate: LocalDate, - maxParticipants: Int - ): Result { - // Business rules validation - if (startDate.isAfter(endDate)) { - return Result.Failure(ValidationError.INVALID_DATE_RANGE) - } - - return Result.Success( - Tournament( - id = TournamentId.generate(), - name = name, - startDate = startDate, - endDate = endDate, - maxParticipants = maxParticipants - ) - ) - } - } - - fun registerMember(memberId: MemberId): Result { - // Business rules - if (registrations.size >= maxParticipants) { - return Result.Failure(BusinessError.TOURNAMENT_FULL) - } - - if (registrations.any { it.memberId == memberId }) { - return Result.Failure(BusinessError.ALREADY_REGISTERED) - } - - val registration = TournamentRegistration( - id = TournamentRegistrationId.generate(), - tournamentId = id, - memberId = memberId, - registrationDate = LocalDateTime.now() - ) - - registrations.add(registration) - - return Result.Success( - TournamentRegistrationCreatedEvent( - tournamentId = id, - memberId = memberId, - registrationId = registration.id - ) - ) - } -} -``` - -### Infrastructure & Betrieb - -#### Kafka-Konfiguration - -Die Konfiguration muss auf maximale Zuverlässigkeit ausgelegt sein: - -```yaml -# application.yml -kafka: - producer: - acks: all - enable-idempotence: true - max-in-flight-requests-per-connection: 1 - consumer: - group-id-prefix: "meldestelle-${spring.application.name}" - auto-offset-reset: earliest - enable-auto-commit: false -``` - -#### Datenbank-Migrationen (Flyway) - -Migrations-Skripte müssen einer klaren Namenskonvention folgen: - -* **Pattern:** `V{version}__{description}.sql` (z.B., `V001__Create_member_tables.sql`) -* **Repeatable:** `R__{description}.sql` (z.B., `R__Update_member_view.sql`) - -#### API-Dokumentation (OpenAPI) - -Alle öffentlichen REST-Endpunkte müssen mit OpenAPI-Annotationen (`@Operation`, `@ApiResponse`) dokumentiert werden, um eine klare und interaktive API-Dokumentation zu generieren. - -```kotlin -@Operation( - summary = "Neues Mitglied erstellen", - description = "Erstellt ein neues Mitglied mit den angegebenen Daten" -) -@ApiResponses( - value = [ - ApiResponse( - responseCode = "201", - description = "Mitglied erfolgreich erstellt" - ), - ApiResponse( - responseCode = "400", - description = "Ungültige Eingabedaten" - ) - ] -) -@PostMapping -fun createMember(@RequestBody request: CreateMemberRequest): ResponseEntity -``` - -## 🚀 Architektur-Entscheidungen (ADRs) - -### ADR-001: Microservices mit Domain-Driven Design - -**Status:** Akzeptiert - -**Kontext:** Skalierbare und wartbare Architektur für Pferdesport-Plattform - -**Entscheidung:** Microservices-Architektur mit DDD-Bounded-Contexts - -**Konsequenzen:** -- ✅ Unabhängige Entwicklung und Deployment -- ✅ Fachliche Kapselung durch Bounded Contexts -- ❌ Komplexität bei Service-zu-Service-Kommunikation -- ❌ Eventual Consistency zwischen Services - -### ADR-002: Event-Driven Architecture mit Kafka - -**Status:** Akzeptiert - -**Kontext:** Entkopplung und Resilienz zwischen Services - -**Entscheidung:** Kafka als zentraler Event-Broker - -**Konsequenzen:** -- ✅ Lose Kopplung zwischen Services -- ✅ Audit-Log durch Event-Store -- ❌ Komplexität bei Event-Schema-Evolution -- ❌ Eventually Consistent State - -### ADR-003: Kotlin Multiplatform für Client - -**Status:** Akzeptiert - -**Kontext:** Codesharing zwischen Desktop und Web - -**Entscheidung:** KMP mit Compose Multiplatform - -**Konsequenzen:** -- ✅ Geteilte Business-Logic -- ✅ Einheitliche UI-Patterns -- ❌ Plattform-spezifische Optimierungen schwieriger -- ❌ Abhängigkeit von Kotlin/JetBrains-Ökosystem - ---- - -**Navigation:** -- [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 diff --git a/.junie/guidelines/project-standards/coding-standards.md b/.junie/guidelines/project-standards/coding-standards.md deleted file mode 100644 index 457b5560..00000000 --- a/.junie/guidelines/project-standards/coding-standards.md +++ /dev/null @@ -1,220 +0,0 @@ -# Coding Standards und Code-Qualität - ---- -guideline_type: "project-standards" -scope: "coding-standards" -audience: ["developers", "ai-assistants"] -last_updated: "2025-09-15" -dependencies: ["master-guideline.md"] -related_files: ["build.gradle.kts", "detekt.yml", "*.kt"] -ai_context: "Coding conventions, naming standards, type safety, error handling, and logging practices" ---- - -## 📋 Coding Conventions & Code-Qualität - -### Sprach- und Stilstandards - -* **Primärsprache:** Kotlin (JVM/Multiplatform) -* **Java-Kompatibilität:** Ziel ist Java 25+ -* **Code-Stil:** Offizielle Kotlin Coding Conventions, durch `Detekt` geprüft. - -> **🤖 AI-Assistant Hinweis:** -> Alle Kotlin-Code müssen den offiziellen Kotlin Coding Conventions entsprechen: -> - **Detekt-Validierung:** Automatische Code-Style-Prüfung -> - **Java 25+ Kompatibilität:** Nutze moderne Java-Features wo sinnvoll -> - **Multiplatform:** Code sollte plattformübergreifend funktionieren - -### Namenskonventionen - -* **Klassen & Interfaces:** `PascalCase` (z.B. `MemberService`, `EventRepository`) -* **Funktionen & Variablen:** `camelCase` (z.B. `authenticateUser`, `memberRepository`) -* **Testmethoden:** Beschreibend mit Backticks (z.B. `` `should return Success for valid credentials` ``) -* **Konstanten:** `SCREAMING_SNAKE_CASE` (z.B. `MAX_RETRY_ATTEMPTS`) -* **Enums:** `PascalCase` für Werte (z.B. `MemberStatus.ACTIVE`) - -### Value Classes für Typsicherheit - -Primitive Typen (UUID, String, Long) für IDs oder spezifische Werte müssen in typsichere `value class`-Wrapper gekapselt werden. - -```kotlin -@JvmInline -value class MemberId(val value: UUID) { - companion object { - fun of(value: String): Result = - runCatching { UUID.fromString(value) } - .map { MemberId(it) } - .mapError { ValidationError.INVALID_UUID } - } -} -``` - -### Error-Handling & Logging - -* **`Result`-Pattern:** Für erwartbare Geschäftsfehler ist das `Result`-Pattern zu verwenden. Exceptions sind für unerwartete, technische Fehler reserviert. - -* **Fehler-Hierarchie:** Wir verwenden eine `sealed class`-Hierarchie, um Fehlerarten klar zu kategorisieren (`DomainError`, `ValidationError`, `BusinessError`, `TechnicalError`). - -* **Structured Logging:** Logs müssen strukturiert sein und eine Korrelations-ID enthalten, um Anfragen über Service-Grenzen hinweg zu verfolgen. - -```kotlin -logger.info { - "Creating member" with mapOf( - "memberId" to command.memberId.value, - "correlationId" to MDC.get("correlationId") - ) -} -``` - -## 🎯 AI-Assistenten: Coding-Standards-Schnellreferenz - -### 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` | - -### Code-Qualitäts-Checkliste - -- [ ] **Detekt-Prüfung:** Code-Stil entspricht Kotlin Conventions -- [ ] **Value Classes:** Primitive Typen sind in typsichere Wrapper gekapselt -- [ ] **Result-Pattern:** Geschäftsfehler verwenden Result statt Exceptions -- [ ] **Structured Logging:** Logs enthalten Korrelations-IDs -- [ ] **Error-Hierarchie:** Sealed Classes für Fehlerkategorisierung - -### Häufige Code-Patterns - -#### Typsichere IDs - -```kotlin -@JvmInline -value class EntityId(val value: UUID) { - companion object { - fun generate(): EntityId = EntityId(UUID.randomUUID()) - fun of(value: String): Result = - runCatching { UUID.fromString(value) } - .map { EntityId(it) } - .mapError { ValidationError.INVALID_UUID } - } -} -``` - -#### Error-Handling mit Result - -```kotlin -interface EntityRepository { - suspend fun findById(id: EntityId): Result - suspend fun save(entity: Entity): Result -} - -// Verwendung -when (val result = repository.findById(entityId)) { - is Result.Success -> processEntity(result.value) - is Result.Failure -> handleError(result.error) -} -``` - -#### Structured Logging - -```kotlin -class EntityService { - private val logger = LoggerFactory.getLogger(EntityService::class.java) - - suspend fun processEntity(command: ProcessEntityCommand): Result { - val correlationId = MDC.get("correlationId") - - logger.info { - "Processing entity" with mapOf( - "entityId" to command.entityId.value, - "correlationId" to correlationId, - "operation" to "process" - ) - } - - return try { - // Processing logic - Result.Success(Unit) - } catch (e: Exception) { - logger.error { - "Entity processing failed" with mapOf( - "entityId" to command.entityId.value, - "correlationId" to correlationId, - "error" to e.message - ) - } - Result.Failure(ProcessingError.TECHNICAL_ERROR) - } - } -} -``` - -#### Sealed Class Hierarchie für Fehler - -```kotlin -sealed interface DomainError { - val message: String - val code: String -} - -sealed interface ValidationError : DomainError { - data object INVALID_UUID : ValidationError { - override val message = "Invalid UUID format" - override val code = "VALIDATION_INVALID_UUID" - } - - data object REQUIRED_FIELD_MISSING : ValidationError { - override val message = "Required field is missing" - override val code = "VALIDATION_REQUIRED_FIELD_MISSING" - } -} - -sealed interface BusinessError : DomainError { - data object ENTITY_NOT_FOUND : BusinessError { - override val message = "Entity not found" - override val code = "BUSINESS_ENTITY_NOT_FOUND" - } -} - -sealed interface TechnicalError : DomainError { - data object DATABASE_CONNECTION_FAILED : TechnicalError { - override val message = "Database connection failed" - override val code = "TECHNICAL_DATABASE_CONNECTION_FAILED" - } -} -``` - -### Detekt-Konfiguration - -Wichtige Detekt-Regeln für das Projekt: - -```yaml -# detekt.yml -style: - MaxLineLength: - maxLineLength: 120 - FunctionNaming: - functionPattern: '^[a-z][a-zA-Z0-9]*$' - ClassNaming: - classPattern: '^[A-Z][a-zA-Z0-9]*$' - -complexity: - ComplexMethod: - threshold: 15 - LongParameterList: - functionThreshold: 6 - -potential-bugs: - UnsafeCallOnNullableType: - active: true -``` - ---- - -**Navigation:** -- [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 diff --git a/.junie/guidelines/project-standards/documentation-standards.md b/.junie/guidelines/project-standards/documentation-standards.md deleted file mode 100644 index c8fb2ee3..00000000 --- a/.junie/guidelines/project-standards/documentation-standards.md +++ /dev/null @@ -1,349 +0,0 @@ -# Documentation Standards - ---- - -guideline_type: "project-standards" -scope: "documentation-standards" -audience: ["developers", "ai-assistants", "technical-writers"] -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 - -### Sprache für Dokumentation - -* **README-Dateien:** Alle README-Dokumentationen im Projekt müssen in **deutscher Sprache** verfasst werden. Dies gewährleistet Konsistenz und Zugänglichkeit für das deutsche Entwicklungsteam. - -* **Code-Kommentare:** Komplexe Geschäftslogik und fachliche Zusammenhänge sollen in deutscher Sprache kommentiert werden. - -* **API-Dokumentation:** OpenAPI-Beschreibungen und -Beispiele sind bevorzugt in deutscher Sprache zu verfassen, sofern keine internationalen Anforderungen bestehen. - -> **🤖 AI-Assistant Hinweis:** -> Dokumentationssprache-Regeln: -> - **README-Dateien:** Immer Deutsch -> - **Code-Kommentare:** Deutsch für Geschäftslogik, Englisch für technische Details -> - **API-Docs:** Deutsch bevorzugt, Englisch bei internationalen APIs -> - **Technische Begriffe:** Englische Originalform wenn keine deutsche Übersetzung etabliert - -### Dokumentationsstruktur - -* README-Dateien sollen eine einheitliche Struktur befolgen: Überblick, Architektur, Entwicklung, Tests, Deployment. - -* Technische Begriffe dürfen in englischer Originalform verwendet werden, wenn keine etablierte deutsche Übersetzung existiert. - -## 🎯 AI-Assistenten: Documentation-Schnellreferenz - -### README-Template-Struktur - -```markdown -# [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. - * - * Ein Mitglied ist berechtigt, wenn: - * - Der Mitgliedsstatus AKTIV ist - * - Die Lizenz gültig und nicht suspendiert ist - * - Keine offenen Zahlungen vorliegen - */ -fun isEligibleForTournament(member: Member, tournament: Tournament): Result { - // Mitgliedsstatus prüfen - if (member.status != MemberStatus.ACTIVE) { - return Result.Failure(ValidationError.MEMBER_NOT_ACTIVE) - } - - // Lizenzvalidierung durchführen - return validateLicense(member, tournament) -} -``` - -#### Englische technische Kommentare - -```kotlin -/** - * Cache implementation using Redis with TTL support - * Performance: O(1) for get/set operations - */ -class RedisCache( - private val redisClient: RedisClient, - private val ttl: Duration = Duration.ofHours(1) -) : Cache { - - override suspend fun get(key: String): T? { - // Use Redis GET command with automatic deserialization - return redisClient.get(key)?.let { - jsonMapper.readValue(it, typeRef()) - } - } -} -``` - -### OpenAPI-Dokumentation Standards - -#### Deutsche API-Beschreibungen - -```yaml -openapi: 3.0.0 -info: - title: Meldestelle API - description: REST API für die Verwaltung von Pferdesport-Meldungen - version: 1.0.0 - -paths: - /members: - post: - summary: Neues Mitglied anlegen - description: | - Erstellt ein neues Mitglied in der Datenbank. - Validiert alle Pflichtfelder und prüft auf Duplikate. - requestBody: - description: Mitgliedsdaten für die Erstellung - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateMemberRequest' - example: - name: "Max Mustermann" - email: "max.mustermann@example.com" - licenseNumber: "12345" - responses: - '201': - description: Mitglied erfolgreich erstellt - content: - application/json: - schema: - $ref: '#/components/schemas/Member' - '400': - description: Ungültige Eingabedaten - content: - application/json: - schema: - $ref: '#/components/schemas/ValidationError' - -components: - schemas: - Member: - type: object - description: Repräsentiert ein Mitglied im System - properties: - id: - type: string - format: uuid - description: Eindeutige Mitglieds-ID - example: "550e8400-e29b-41d4-a716-446655440000" - name: - type: string - description: Vollständiger Name des Mitglieds - example: "Max Mustermann" - email: - type: string - format: email - description: E-Mail-Adresse des Mitglieds - example: "max.mustermann@example.com" -``` - -### Dokumentations-Checkliste - -#### README-Dateien - -- [ ] **Struktur:** Folgt dem Standard-Template -- [ ] **Sprache:** Auf Deutsch verfasst -- [ ] **Aktualität:** Entspricht dem aktuellen Code-Stand -- [ ] **Vollständigkeit:** Alle erforderlichen Abschnitte vorhanden -- [ ] **Beispiele:** Konkrete Code-Beispiele und Kommandos -- [ ] **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 -- [ ] **Error-Handling:** Dokumentierte Fehlerfälle -- [ ] **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 -- [ ] **TODOs:** Mit Ticket-Referenzen versehen -- [ ] **Javadoc/KDoc:** Für öffentliche APIs vollständig - -### Dokumentations-Patterns - -#### Architektur-Diagramme - -### System-Architektur - -```mermaid -graph TB - subgraph "Client Layer" - WEB[Web App] - MOBILE[Mobile App] - end - - subgraph "API Gateway" - GW[API Gateway] - end - - subgraph "Service Layer" - MS[Member Service] - TS[Tournament Service] - NS[Notification Service] - end - - subgraph "Data Layer" - PG[(PostgreSQL)] - RD[(Redis)] - end - - WEB --> GW - MOBILE --> GW - GW --> MS - GW --> TS - GW --> NS - MS --> PG - TS --> PG - NS --> RD -``` - -#### Feature-Dokumentation - -## 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 - -### Technische Umsetzung - -#### API-Endpunkte -- `POST /tournaments/{id}/registrations` - Anmeldung erstellen -- `GET /tournaments/{id}/registrations` - Anmeldungen abrufen -- `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 - -## Häufige Probleme - -### Problem: Service startet nicht - -**Symptome:** Container bleibt im Status "Restarting" - -**Ursachen:** -- Datenbankverbindung fehlgeschlagen -- Fehlende Environment-Variablen -- Port bereits belegt - -**Lösung:** -1. Logs prüfen: `docker-compose logs service-name` -2. Environment-Variablen validieren -3. Port-Konflikte lösen: `netstat -tulpn | grep :8080` - -### Problem: Langsame API-Antworten - -**Symptome:** Response-Zeiten > 2 Sekunden - -**Debugging:** -```bash -# Database-Performance prüfen -docker-compose exec postgres psql -c "SELECT * FROM pg_stat_activity;" - -# Redis-Performance prüfen -docker-compose exec redis redis-cli info stats -``` - -**Optimierung:** -- 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 -4. **Deployment-Änderungen** → Deployment-Docs aktualisieren - ---- - -**Navigation:** -- [Master-Guideline](../master-guideline.md) - Übergeordnete Projektrichtlinien -- [Coding-Standards](./coding-standards.md) - Code-Qualitätsstandards -- [Testing-Standards](./testing-standards.md) - Test-Qualitätssicherung -- [Architecture-Principles](./architecture-principles.md) - Architektur-Grundsätze diff --git a/.junie/guidelines/project-standards/testing-standards.md b/.junie/guidelines/project-standards/testing-standards.md deleted file mode 100644 index 5789392e..00000000 --- a/.junie/guidelines/project-standards/testing-standards.md +++ /dev/null @@ -1,385 +0,0 @@ -# Testing Standards und Qualitätssicherung - ---- - -guideline_type: "project-standards" -scope: "testing-standards" -audience: ["developers", "ai-assistants"] -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 - -Tests sind ein integraler Bestandteil jedes Features und müssen einen hohen Standard erfüllen. - -> **🤖 AI-Assistant Hinweis:** -> Testing-Prinzipien für das Meldestelle-Projekt: -> - **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 - -### Test-Pyramide & Werkzeuge - -#### Unit-Tests (80 %+ Abdeckung) - -Für Domänen- und Anwendungslogik (JUnit 5, MockK). - -```kotlin -class MemberServiceTest { - private val memberRepository = mockk() - private val eventPublisher = mockk() - private val memberService = MemberService(memberRepository, eventPublisher) - - @Test - fun `should return Success when member is created successfully`() { - // Given - val command = CreateMemberCommand( - memberId = MemberId.generate(), - name = "Max Mustermann", - email = "max@example.com" - ) - - every { memberRepository.save(any()) } returns Result.Success(Unit) - every { eventPublisher.publish(any()) } returns Result.Success(Unit) - - // When - val result = memberService.createMember(command) - - // Then - assertThat(result).isInstanceOf>() - verify { memberRepository.save(any()) } - verify { eventPublisher.publish(ofType()) } - } - - @Test - fun `should return Failure when repository save fails`() { - // Given - val command = CreateMemberCommand( - memberId = MemberId.generate(), - name = "Max Mustermann", - email = "max@example.com" - ) - - every { memberRepository.save(any()) } returns Result.Failure(RepositoryError.DATABASE_ERROR) - - // When - val result = memberService.createMember(command) - - // Then - assertThat(result).isInstanceOf>() - verify { memberRepository.save(any()) } - verify(exactly = 0) { eventPublisher.publish(any()) } - } -} -``` - -#### Integrationstests - -Decken alle Repository-Implementierungen und externen Integrationen ab. - -```kotlin -@Testcontainers -class MemberRepositoryIntegrationTest { - - @Container - private val postgresContainer = PostgreSQLContainer("postgres:16-alpine") - .withDatabaseName("testdb") - .withUsername("test") - .withPassword("test") - - private lateinit var memberRepository: MemberRepository - - @BeforeEach - fun setup() { - val dataSource = HikariDataSource().apply { - jdbcUrl = postgresContainer.jdbcUrl - username = postgresContainer.username - password = postgresContainer.password - } - - // Run migrations - Flyway.configure() - .dataSource(dataSource) - .locations("db/migration") - .load() - .migrate() - - memberRepository = PostgresMemberRepository(dataSource) - } - - @Test - fun `should save and retrieve member successfully`() { - // Given - val member = Member( - id = MemberId.generate(), - name = "Integration Test Member", - email = "integration@test.com" - ) - - // When - val saveResult = runBlocking { memberRepository.save(member) } - val findResult = runBlocking { memberRepository.findById(member.id) } - - // Then - assertThat(saveResult).isInstanceOf>() - assertThat(findResult).isInstanceOf>() - - val retrievedMember = (findResult as Result.Success).value - assertThat(retrievedMember?.id).isEqualTo(member.id) - assertThat(retrievedMember?.name).isEqualTo(member.name) - assertThat(retrievedMember?.email).isEqualTo(member.email) - } -} -``` - -#### Testcontainers als Goldstandard - -Jede Interaktion mit externer Infrastruktur (DB, Cache, Broker) **muss** mit **Testcontainers** getestet werden. - -```kotlin -@Testcontainers -class EventStoreIntegrationTest { - - companion object { - @Container - @JvmStatic - private val redisContainer = GenericContainer("redis:7-alpine") - .withExposedPorts(6379) - - @Container - @JvmStatic - private val kafkaContainer = KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.4.0")) - } - - @Test - fun `should store and retrieve events from Redis`() { - println("[DEBUG_LOG] Testing Redis event storage") - - // Given - val eventStore = RedisEventStore( - redisHost = redisContainer.host, - redisPort = redisContainer.getMappedPort(6379) - ) - - val event = MemberCreatedEvent( - memberId = MemberId.generate(), - name = "Test Member", - timestamp = Instant.now() - ) - - // When - val storeResult = runBlocking { eventStore.store(event) } - val retrieveResult = runBlocking { eventStore.getEvents(event.memberId) } - - // Then - assertThat(storeResult).isInstanceOf>() - assertThat(retrieveResult).isInstanceOf>>() - - val events = (retrieveResult as Result.Success).value - assertThat(events).hasSize(1) - assertThat(events.first()).isInstanceOf() - - println("[DEBUG_LOG] Successfully stored and retrieved ${events.size} events") - } -} -``` - -### Debugging in Tests - -Debug-Ausgaben im Test-Code müssen mit `[DEBUG_LOG]` beginnen, um sie leicht identifizieren und filtern zu können. - -```kotlin -@Test -fun `should handle complex business scenario`() { - println("[DEBUG_LOG] Starting complex business scenario test") - - // Test implementation - - println("[DEBUG_LOG] Member created with ID: ${member.id}") - println("[DEBUG_LOG] Published ${events.size} domain events") - println("[DEBUG_LOG] Test completed successfully") -} -``` - -## 🎯 AI-Assistenten: Testing-Schnellreferenz - -### 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 | - -### Testcontainer-Konfiguration - -#### PostgresQL - -```kotlin -@Container -private val postgresContainer = PostgreSQLContainer("postgres:16-alpine") - .withDatabaseName("testdb") - .withUsername("test") - .withPassword("test") - .withInitScript("test-data.sql") -``` - -#### Redis - -```kotlin -@Container -private val redisContainer = GenericContainer("redis:7-alpine") - .withExposedPorts(6379) - .withCommand("redis-server", "--appendonly", "yes") -``` - -#### Kafka - -```kotlin -@Container -private val kafkaContainer = KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.4.0")) - .withEnv("KAFKA_AUTO_CREATE_TOPICS_ENABLE", "true") -``` - -#### Keycloak - -```kotlin -@Container -private val keycloakContainer = KeycloakContainer("quay.io/keycloak/keycloak:26.0.7") - .withRealmImportFile("test-realm.json") - .withAdminUsername("admin") - .withAdminPassword("admin") -``` - -### Test-Patterns für Result-Handling - -```kotlin -// Success-Case testen -@Test -fun `should return Success when operation succeeds`() { - // Given - every { dependency.operation() } returns Result.Success(expectedValue) - - // When - val result = serviceUnderTest.performOperation() - - // Then - assertThat(result).isInstanceOf>() - assertThat((result as Result.Success).value).isEqualTo(expectedValue) -} - -// Failure-Case testen -@Test -fun `should return Failure when dependency fails`() { - // Given - every { dependency.operation() } returns Result.Failure(ExpectedError.SOME_ERROR) - - // When - val result = serviceUnderTest.performOperation() - - // Then - assertThat(result).isInstanceOf>() - assertThat((result as Result.Failure).error).isEqualTo(ExpectedError.SOME_ERROR) -} -``` - -### Mock-Setup für Services - -```kotlin -class ServiceTest { - private val repository = mockk() - private val eventPublisher = mockk() - private val externalService = mockk() - - private val serviceUnderTest = Service(repository, eventPublisher, externalService) - - @BeforeEach - fun setup() { - clearAllMocks() - - // Default mocks - every { eventPublisher.publish(any()) } returns Result.Success(Unit) - } - - @AfterEach - fun cleanup() { - confirmVerified(repository, eventPublisher, externalService) - } -} -``` - -### Testdaten-Builder - -```kotlin -class MemberTestDataBuilder { - private var id: MemberId = MemberId.generate() - private var name: String = "Test Member" - private var email: String = "test@example.com" - private var status: MemberStatus = MemberStatus.ACTIVE - - fun withId(id: MemberId) = apply { this.id = id } - fun withName(name: String) = apply { this.name = name } - fun withEmail(email: String) = apply { this.email = email } - fun withStatus(status: MemberStatus) = apply { this.status = status } - - fun build() = Member( - id = id, - name = name, - email = email, - status = status - ) -} - -// Verwendung in Tests -@Test -fun `should validate member data`() { - val member = MemberTestDataBuilder() - .withName("Max Mustermann") - .withEmail("max@meldestelle.at") - .withStatus(MemberStatus.PENDING) - .build() - - // Test implementation -} -``` - -### Performance-Tests - -```kotlin -@Test -fun `should handle high load efficiently`() { - println("[DEBUG_LOG] Starting performance test with 1000 concurrent operations") - - val operations = (1..1000).map { - async { - serviceUnderTest.performOperation( - TestCommand(id = MemberId.generate()) - ) - } - } - - val results = runBlocking { - operations.awaitAll() - } - - val successCount = results.count { it is Result.Success } - val failureCount = results.count { it is Result.Failure } - - println("[DEBUG_LOG] Performance test completed: $successCount successes, $failureCount failures") - - assertThat(successCount).isGreaterThan(950) // 95% success rate minimum -} -``` - ---- - -**Navigation:** -- [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 diff --git a/.junie/guidelines/technology-guides/docker/docker-architecture.md b/.junie/guidelines/technology-guides/docker/docker-architecture.md deleted file mode 100644 index 1b86abd3..00000000 --- a/.junie/guidelines/technology-guides/docker/docker-architecture.md +++ /dev/null @@ -1,255 +0,0 @@ -# Docker-Architektur und Services - ---- - -guideline_type: "technology" -scope: "docker-architecture" -audience: ["developers", "ai-assistants", "devops"] -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] - RD[Redis] - KC[Keycloak] - KF[Kafka+Zookeeper] - CS[Consul] - end - - subgraph "Application Services" - GW[API Gateway] - AS[Auth Server] - MS[Monitoring Server] - PS[Ping Service] - end - - subgraph "Client Applications" - WA[Web App] - DA[Desktop App - Native] - end - - subgraph "Monitoring Stack" - PR[Prometheus] - GR[Grafana] - ZK[Zipkin] - NX[Nginx - Prod] - end - - Infrastructure --> Application - Application --> Client - Monitoring --> Infrastructure - Monitoring --> Application -``` - -### 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 | - -## 🎯 Zentrale Docker-Versionsverwaltung - -> **🤖 AI-Assistant Hinweis:** -> Das Versionssystem folgt dem Single Source of Truth Prinzip: -> - **Zentrale Datei:** `docker/versions.toml` definiert alle Versionen -> - **Build-Args:** Automatisch generierte `.env`-Dateien in `docker/build-args/` -> - **Updates:** Via `./scripts/docker-versions-update.sh` - -### Überblick und Motivation - -**Version 3.0.0** führt eine revolutionäre Änderung in der Docker-Versionsverwaltung ein: die **zentrale Verwaltung aller Build-Argumente** analog zum bewährten `gradle/libs.versions.toml` System. - -#### Das Problem vor Version 3.0.0 - -```dockerfile -# BEFORE: Redundante Hardcodierung in 12+ Dockerfiles -ARG GRADLE_VERSION=9.0.0 -ARG GRADLE_VERSION=9.0.0 -ARG GRADLE_VERSION=9.0.0 -# ... 9 weitere Male identisch wiederholt! -``` - -#### Die Lösung: Single Source of Truth - -```toml -# docker/versions.toml - SINGLE SOURCE OF TRUTH -[versions] -gradle = "9.2.1" -java = "25" -node = "22.21.0" -nginx = "1.28.0-alpine" -prometheus = "v2.54.1" -grafana = "11.3.0" -keycloak = "26.4.2" -``` - -### 🏗️ Architektur der zentralen Versionsverwaltung - -```plaintext -docker/ -├── versions.toml # 🎯 Single Source of Truth -├── build-args/ # Auto-generierte Environment Files -│ ├── global.env # Globale Build-Argumente -│ ├── services.env # dockerfiles/services/* -│ ├── clients.env # dockerfiles/clients/* -│ └── infrastructure.env # dockerfiles/infrastructure/* -└── README.md # Dokumentation -``` - -### 📊 Hierarchische Versionsverwaltung - -#### 1. **Globale Versionen** (`docker/build-args/global.env`) - -Verwendet von **allen** Dockerfiles: -```bash -# --- Build Tools --- -GRADLE_VERSION=9.2.1 -JAVA_VERSION=25 - -# --- Build Metadata --- -BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') -VERSION=1.0.0 - -# --- Common Base Images --- -ALPINE_VERSION=3.19 -ECLIPSE_TEMURIN_JDK_VERSION=25-jdk-alpine -ECLIPSE_TEMURIN_JRE_VERSION=25-jre-alpine - -# --- Monitoring & Infrastructure Services --- -DOCKER_PROMETHEUS_VERSION=v2.54.1 -DOCKER_GRAFANA_VERSION=11.3.0 -DOCKER_KEYCLOAK_VERSION=26.4.2 -``` - -#### 2. **Kategorie-spezifische Versionen** - -**Services** (`docker/build-args/services.env`): -```bash -SPRING_PROFILES_ACTIVE=docker -SERVICE_PORT=8080 -PING_SERVICE_PORT=8082 -MEMBERS_SERVICE_PORT=8083 -``` - -**Clients** (`docker/build-args/clients.env`): -```bash -NODE_VERSION=22.21.0 -NGINX_VERSION=1.28.0-alpine -WEB_APP_PORT=4000 -DESKTOP_APP_VNC_PORT=5901 -``` - -**Infrastructure** (`docker/build-args/infrastructure.env`): -```bash -SPRING_PROFILES_ACTIVE=default -GATEWAY_PORT=8081 -AUTH_SERVER_PORT=8087 -``` - -### 🛠️ Verwendung der zentralen Versionsverwaltung - -#### Automatisierte Builds mit `scripts/docker-build.sh` - -```bash -# Alle Services mit zentralen Versionen bauen -./scripts/docker-build.sh services - -# Client-Anwendungen bauen -./scripts/docker-build.sh clients - -# Komplettes System bauen -./scripts/docker-build.sh all - -# Aktuelle Versionen anzeigen -./scripts/docker-build.sh --versions -``` - -#### Versionen aktualisieren mit `scripts/docker-versions-update.sh` - -```bash -# Aktuelle Versionen anzeigen -./scripts/docker-versions-update.sh show - -# Java auf Version 22 upgraden -./scripts/docker-versions-update.sh update java 22 - -# Gradle auf 9.2.1 upgraden -./scripts/docker-versions-update.sh update gradle 9.2.1 - -# Prometheus auf neueste Version upgraden -./scripts/docker-versions-update.sh update prometheus v2.54.1 - -# Grafana auf neueste Version upgraden -./scripts/docker-versions-update.sh update grafana 11.3.0 - -# Keycloak auf neueste Version upgraden -./scripts/docker-versions-update.sh update keycloak 26.4.2 - -# Alle Environment-Dateien synchronisieren -./scripts/docker-versions-update.sh sync -``` - -## 🎯 Für AI-Assistenten: Architektur-Schnellreferenz - -### Service-Kategorien -- **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 - -# Logs eines Services anzeigen -docker-compose logs - -# Versionen aktualisieren -./scripts/docker-versions-update.sh show -./scripts/docker-versions-update.sh update - -# Services neu starten -docker-compose restart -``` - -### Zentrale Konfigurationsdateien - -- `docker/versions.toml` - Alle Versionen -- `docker-compose.yml` - Haupt-Services -- `docker-compose.clients.yml` - Client-Anwendungen -- `docker/build-args/*.env` - Generierte Build-Argumente - ---- - -**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 -- [Docker-Monitoring](./docker-monitoring.md) - Observability -- [Docker-Troubleshooting](./docker-troubleshooting.md) - Problemlösung diff --git a/.junie/guidelines/technology-guides/docker/docker-development.md b/.junie/guidelines/technology-guides/docker/docker-development.md deleted file mode 100644 index 7ae38899..00000000 --- a/.junie/guidelines/technology-guides/docker/docker-development.md +++ /dev/null @@ -1,756 +0,0 @@ -# Docker-Development Workflow - ---- - -guideline_type: "technology" -scope: "docker-development" -audience: ["developers", "ai-assistants"] -last_updated: "2025-11-11" -dependencies: ["docker-overview.md", "docker-architecture.md"] -related_files: ["docker-compose.yml", "docker-compose.services.yml", "docker-compose.clients.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 - -### Komplette Hilfe anzeigen - -```bash -make help # Zeigt alle verfügbaren Befehle mit Beschreibungen -``` - -### Wichtigste Befehle für den Einstieg - -```bash -# Komplettes System starten -make full-up # Infrastruktur + Services + Clients - -# Nur Backend starten -make services-up # Infrastruktur + Microservices - -# Nur Entwicklungsumgebung -make dev-up # Infrastruktur only - -# System-Health prüfen -make health-check # Prüft alle Infrastruktur-Services - -# Logs anzeigen -make full-logs # Alle Logs in Echtzeit -``` - -## 📚 Vollständige Makefile-Referenz - -### Development Workflow Commands - -Befehle für die lokale Entwicklungsumgebung: - -```bash -make dev-up # Startet Entwicklungsumgebung (docker-compose.yaml) -make dev-down # Stoppt Entwicklungsumgebung -make dev-restart # Neustart Entwicklungsumgebung -make dev-logs # Zeigt alle Development-Logs -make dev-info # Zeigt Entwicklungsumgebungs-Informationen -``` - -**Verwendung:** - -```bash -# Infrastruktur starten (Postgres, Redis, Keycloak, Consul) -make dev-up - -# Nach dem Start werden angezeigt: -# - Consul UI: http://localhost:8500 -# - Keycloak: http://localhost:8180 (admin/admin) -# - PostgreSQL: localhost:5432 -# - Redis: localhost:6379 -``` - -### Layer-spezifische Commands - -Das System ist in drei Schichten organisiert: - -#### 1. Infrastructure Layer - -```bash -make infrastructure-up # Startet nur Infrastruktur-Services -make infrastructure-down # Stoppt Infrastruktur-Services -make infrastructure-logs # Zeigt Infrastruktur-Logs -``` - -**Services:** PostgreSQL, Redis, Keycloak, Consul, Kafka, Zookeeper, Prometheus, Grafana - -#### 2. Services Layer (Backend) - -```bash -make services-up # Startet Infrastruktur + Microservices -make services-down # Stoppt Services -make services-restart # Neustart Services -make services-logs # Zeigt Service-Logs -``` - -**Services:** API Gateway + alle Microservices (Ping, Members, Horses, Events, Masterdata, Auth, Monitoring) - -**URLs nach Start:** -- Gateway: http://localhost:8081 -- Ping Service: http://localhost:8082 -- Members Service: http://localhost:8083 -- Horses Service: http://localhost:8084 -- Events Service: http://localhost:8085 -- Master Service: http://localhost:8086 - -#### 3. Clients Layer (Frontend) - -```bash -make clients-up # Startet Infrastruktur + Client-Apps -make clients-down # Stoppt Clients -make clients-restart # Neustart Clients -make clients-logs # Zeigt Client-Logs -``` - -**Clients:** Web-App, Auth-Server, Monitoring-Server - -**URLs nach Start:** -- Web App: http://localhost:4000 -- Auth Server: http://localhost:8087 -- Monitoring: http://localhost:8088 - -### Full System Commands - -Befehle für das komplette System (alle Layer): - -```bash -make full-up # Startet ALLES (Infrastructure + Services + Clients) -make full-down # Stoppt komplettes System -make full-restart # Neustart komplettes System -make full-logs # Zeigt alle System-Logs -``` - -**Nach `make full-up` verfügbare Services:** - -``` -🌐 Frontend & APIs: - Web App: http://localhost:4000 - API Gateway: http://localhost:8081 - -🔧 Infrastructure: - PostgresQL: localhost:5432 - Redis: localhost:6379 - Keycloak: http://localhost:8180 - Consul: http://localhost:8500 - Prometheus: http://localhost:9090 - Grafana: http://localhost:3000 - -⚙️ Microservices: - Ping Service: http://localhost:8082 - Members Service: http://localhost:8083 - Horses Service: http://localhost:8084 - Events Service: http://localhost:8085 - Master Service: http://localhost:8086 - Auth Server: http://localhost:8087 - Monitoring: http://localhost:8088 -``` - -### Build Commands - -Befehle zum Bauen von Docker-Images: - -```bash -make build # Baut alle Custom-Images -make build-service SERVICE=ping-service # Baut einzelnen Service -make build-client CLIENT=web-app # Baut einzelnen Client -``` - -**Beispiele:** - -```bash -# Einzelnen Service neu bauen (ohne Cache) -make build-service SERVICE=api-gateway - -# Web-App neu bauen -make build-client CLIENT=web-app - -# Alle Images neu bauen -make build -``` - -### Test Commands - -Befehle für Testing: - -```bash -make test # Führt Integration-Tests aus -make test-e2e # Führt End-to-End-Tests aus -``` - -**Details:** - -```bash -# Integration-Tests -# - Startet automatisch Infrastruktur -# - Führt Gradle-Tests aus -# - Stoppt Infrastruktur nach Tests -make test - -# E2E-Tests -# - Startet komplette Entwicklungsumgebung -# - Führt Client-Tests aus -# - Stoppt Umgebung nach Tests -make test-e2e -``` - -### Environment Management Commands - -Befehle für Environment-Konfiguration: - -```bash -make env-setup # Zeigt Environment-Setup-Anweisungen -make env-dev # Wechselt zu Development-Environment -make env-prod # Wechselt zu Production-Environment -make env-staging # Wechselt zu Staging-Environment -make env-test # Wechselt zu Test-Environment -make validate # Validiert Docker Compose Konfiguration -make env-template # Erstellt .env Template-Datei -``` - -**Verwendung:** - -```bash -# Entwicklungsumgebung aktivieren -make env-dev - -# Validierung durchführen -make validate - -# Neue .env-Template erstellen -make env-template -``` - -### SSoT (Single Source of Truth) Commands - -Befehle für Docker-Versionsverwaltung: - -```bash -make versions-show # Zeigt zentrale Versionen (docker/versions.toml) -make versions-update key=gradle value=9.2.1 # Aktualisiert eine Version -make docker-sync # Synchronisiert versions.toml -> build-args/*.env -make docker-compose-gen ENV=development # Generiert Docker Compose Files -make docker-validate # Validiert Docker SSoT Konsistenz -make hooks-install # Installiert Pre-Commit SSoT Guard Hook -``` - -**Workflow für Versions-Updates:** - -```bash -# 1. Version in versions.toml aktualisieren -make versions-update key=gradle value=9.2.1 - -# 2. Build-Args synchronisieren -make docker-sync - -# 3. Compose-Files neu generieren -make docker-compose-gen ENV=development - -# 4. Konsistenz validieren -make docker-validate -``` - -**Verfügbare Versions-Keys:** -- `gradle` - Gradle-Version -- `java` - Java-Version -- `node` - Node.js-Version -- `nginx` - Nginx-Version -- `alpine` - Alpine Linux-Version -- `prometheus` - Prometheus-Version -- `grafana` - Grafana-Version -- `keycloak` - Keycloak-Version -- `app-version` - Anwendungsversion -- `spring-profiles-default` - Spring Default-Profile -- `spring-profiles-docker` - Spring Docker-Profile - -### Production Commands - -Befehle für Production-Deployment: - -```bash -make prod-up # Startet Production-Environment -make prod-down # Stoppt Production-Environment -make prod-restart # Neustart Production-Environment -make prod-logs # Zeigt Production-Logs -``` - -**⚠️ Hinweis:** Stelle sicher, dass `.env` korrekt konfiguriert ist mit `make env-prod` - -### Monitoring & Debugging Commands - -Befehle für System-Monitoring und Debugging: - -```bash -make status # Zeigt Container-Status -make health-check # Prüft Health aller Infrastruktur-Services -make logs SERVICE=postgres # Zeigt Logs eines spezifischen Services -make shell SERVICE=postgres # Öffnet Shell in Container -``` - -**Beispiele:** - -```bash -# Status aller Container -make status - -# Health-Check durchführen -make health-check -# Output: -# PostgreSQL: ✅ Ready -# Redis: ✅ PONG -# Consul: ✅ Leader elected -# Keycloak: ✅ Ready - -# Logs von PostgreSQL anzeigen -make logs SERVICE=postgres - -# Shell im Postgres-Container öffnen -make shell SERVICE=postgres -``` - -### Cleanup Commands - -Befehle zum Aufräumen: - -```bash -make clean # Aufräumen Docker-Ressourcen (Prune) -make clean-all # Vollständiges Cleanup (inkl. Images und Volumes) -``` - -**⚠️ Warnung:** `make clean-all` löscht auch Volumes und Images! - -### Development Tools Commands - -```bash -make dev-tools-up # Info: Dev-Tools wurden entfernt (verwende lokale Tools) -make dev-tools-down # Info: Keine Dev-Tool-Container zum Stoppen -``` - -**Empfehlung:** Verwende lokale Tools wie pgAdmin, TablePlus, DBeaver, RedisInsight - -## 🎯 AI-Assistenten: Development-Schnellreferenz - -### Häufigste Workflows - -#### 1. Lokale Entwicklung starten - -```bash -# Variante A: Nur Infrastruktur -make dev-up -./gradlew :members:members-service:bootRun - -# Variante B: Komplettes Backend -make services-up - -# Variante C: Alles inkl. Frontend -make full-up -``` - -#### 2. Service neu bauen nach Code-Änderungen - -```bash -# Service stoppen -docker compose down api-gateway - -# Service neu bauen -make build-service SERVICE=api-gateway - -# Service starten -make services-up -``` - -#### 3. Debugging eines Services - -```bash -# Logs in Echtzeit -make logs SERVICE=ping-service - -# Shell im Container öffnen -make shell SERVICE=ping-service - -# Health-Status prüfen -curl -s http://localhost:8082/actuator/health | jq -``` - -#### 4. Docker-Versionen aktualisieren - -```bash -# Gradle-Version ändern -make versions-update key=gradle value=9.2.1 - -# Änderungen synchronisieren -make docker-sync -make docker-compose-gen -make docker-validate - -# Git-Status prüfen (sollte generierte Files zeigen) -git status -``` - -#### 5. Tests ausführen - -```bash -# Integration-Tests (automatische Infrastruktur) -make test - -# E2E-Tests (automatische Full-Environment) -make test-e2e - -# Einzelner Test via Gradle -./gradlew :members:members-service:test -``` - -### Development-URLs Übersicht - -| Service | URL | Credentials | -|-----------------|-------------------------------|-------------------| -| Web App | http://localhost:4000 | - | -| API Gateway | http://localhost:8081 | - | -| Ping Service | http://localhost:8082 | - | -| Members Service | http://localhost:8083 | - | -| Horses Service | http://localhost:8084 | - | -| Events Service | http://localhost:8085 | - | -| Master Service | http://localhost:8086 | - | -| Auth Server | http://localhost:8087 | - | -| Monitoring | http://localhost:8088 | - | -| Keycloak Admin | http://localhost:8180 | admin/admin | -| Consul UI | http://localhost:8500 | - | -| Prometheus | http://localhost:9090 | - | -| Grafana | http://localhost:3000 | admin/admin | -| PostgreSQL | localhost:5432 | meldestelle/*** | -| Redis | localhost:6379 | - | - -### Health-Check Endpoints - -```bash -# API Gateway -curl -s http://localhost:8081/actuator/health | jq - -# Ping Service -curl -s http://localhost:8082/actuator/health | jq - -# Members Service -curl -s http://localhost:8083/actuator/health | jq - -# Keycloak -curl -s http://localhost:8180/health/ready | jq - -# Consul -curl -s http://localhost:8500/v1/status/leader -``` - -### Debug-Ports - -**Spring Boot Services:** -- Debug-Port: 5005 (Standard Java Debug Protocol) -- Konfiguration in docker-compose.services.yml - -**Client-Apps:** -- Web-App: Hot-Reload über Volume-Mapping -- Desktop-App: VNC Port 5901, VNC Web Port 6080 - -### Troubleshooting Development - -#### Container startet nicht - -```bash -# 1. Status prüfen -make status - -# 2. Logs anzeigen -make logs SERVICE= - -# 3. Container neu starten -docker compose restart - -# 4. Image neu bauen (ohne Cache) -make build-service SERVICE= -docker compose up -d -``` - -#### Port-Konflikte - -```bash -# Ports prüfen -lsof -i : -# oder -netstat -tulpn | grep : - -# Konfigurierten Port in .env ändern -# z.B. API_GATEWAY_PORT=8081 -> API_GATEWAY_PORT=8091 - -# Services neu starten -make services-restart -``` - -#### Health-Check schlägt fehl - -```bash -# 1. Service-Status prüfen -make status - -# 2. Service-Logs prüfen -make logs SERVICE= - -# 3. Manueller Health-Check -curl -v http://localhost:/actuator/health - -# 4. Container-Netzwerk prüfen -docker network inspect meldestelle-network - -# 5. Service neu starten -docker compose restart -``` - -#### Volume-Probleme - -```bash -# Volumes anzeigen -docker volume ls | grep meldestelle - -# Volume-Inhalt prüfen -make shell SERVICE=postgres -ls -la /var/lib/postgresql/data - -# Volume entfernen (⚠️ Daten gehen verloren!) -docker volume rm meldestelle_postgres-data - -# Volumes neu erstellen -make full-down -make full-up -``` - -#### Datenbankverbindung fehlgeschlagen - -```bash -# 1. PostgreSQL-Status prüfen -make health-check - -# 2. PostgreSQL-Logs prüfen -make logs SERVICE=postgres - -# 3. Verbindung testen (aus anderem Container) -docker compose exec api-gateway sh -apk add postgresql-client -psql -h postgres -U meldestelle -d meldestelle - -# 4. Secrets prüfen (falls verwendet) -ls -la ./docker/secrets/ -``` - -#### Gradle-Build schlägt fehl im Container - -```bash -# 1. Gradle-Version in versions.toml prüfen -cat docker/versions.toml | grep gradle - -# 2. Verfügbare Gradle-Images prüfen -docker search gradle | grep alpine - -# 3. Build-Logs detailliert anzeigen -make logs SERVICE= - -# 4. Manuell im Container debuggen -make shell SERVICE= -./gradlew --version -./gradlew dependencies -``` - -#### Service ist erreichbar, antwortet aber nicht - -```bash -# 1. Service-Logs in Echtzeit -make logs SERVICE= - -# 2. JVM-Status prüfen (bei Java-Services) -make shell SERVICE= -ps aux | grep java - -# 3. Speicher/CPU prüfen -docker stats - -# 4. Netzwerk-Verbindung testen -docker compose exec sh -apk add curl -curl -v http://api-gateway:8081/actuator/health -``` - -## 🤖 AI-Assistant Best Practices - -### Für Code-Assistenten - -1. **Verwende immer `make help`** um verfügbare Befehle zu sehen -2. **Befehlsnamen korrekt verwenden:** - - ✅ `make build-service SERVICE=ping-service` - - ❌ `make service-build SERVICE=ping-service` (veraltet) -3. **Port-Angaben beachten:** - - API Gateway: Port 8081 (nicht 8080!) - - Alle Ports in `.env` oder `docker-compose*.yml` definiert -4. **SSoT-Workflow einhalten:** - - Versionen nur in `docker/versions.toml` ändern - - `make docker-sync` nach Änderungen - - `make docker-validate` vor Commits - -### Für Entwickler-Support - -1. **Troubleshooting-Reihenfolge:** - - `make status` → Container-Status - - `make health-check` → Service-Health - - `make logs SERVICE=` → Logs prüfen - - `make shell SERVICE=` → Interactive Debugging - -2. **Häufige Fehlerquellen:** - - Fehlende `.env` Datei → `make env-dev` - - Port-Konflikte → `lsof -i :` - - Veraltete Images → `make build` - - Volume-Berechtigungen → `make clean-all` (⚠️ Daten-Verlust!) - -3. **Performance-Optimierung:** - - Nur benötigte Layer starten (infrastructure/services/clients) - - Docker BuildKit aktivieren: `export DOCKER_BUILDKIT=1` - - Gradle-Cache nutzen (bereits in Dockerfiles konfiguriert) - -## 📦 Docker Compose Dateien - -Das Projekt verwendet mehrere Compose-Files: - -- **docker-compose.yml** - Infrastruktur-Layer (Postgres, Redis, Keycloak, Consul, etc.) -- **docker-compose.services.yml** - Services-Layer (API Gateway, Microservices) -- **docker-compose.clients.yml** - Clients-Layer (Web-App, Desktop-App) - -**Kombinationen:** - -```bash -# Nur Infrastruktur -docker compose -f docker-compose.yaml up -d - -# Infrastruktur + Services -docker compose -f docker-compose.yaml -f docker-compose.services.yaml up -d - -# Infrastruktur + Clients -docker compose -f docker-compose.yaml -f docker-compose.frontend.yaml up -d - -# Alles -docker compose -f docker-compose.yaml -f docker-compose.services.yaml -f docker-compose.frontend.yaml up -d - -# ⚠️ Tipp: Verwende stattdessen die Makefile-Befehle! -``` - -## 🔄 Typische Entwicklungs-Workflows - -### Workflow 1: Neues Feature entwickeln - -```bash -# 1. Frische Umgebung starten -make full-down -make dev-up - -# 2. Feature in IDE entwickeln -# (Service läuft lokal via Gradle, nicht in Docker) - -# 3. Tests lokal ausführen -./gradlew :members:members-service:test - -# 4. Service als Container testen -make build-service SERVICE=members-service -make services-up - -# 5. Integration-Tests -make test - -# 6. Aufräumen -make dev-down -``` - -### Workflow 2: Bug-Fixing - -```bash -# 1. System starten -make full-up - -# 2. Logs beobachten -make logs SERVICE= - -# 3. Shell im Container öffnen (falls nötig) -make shell SERVICE= - -# 4. Fix implementieren und Service neu bauen -make build-service SERVICE= -docker compose restart - -# 5. Fix verifizieren -curl http://localhost:/actuator/health -make test -``` - -### Workflow 3: Docker-Version aktualisieren - -```bash -# 1. Aktuelle Versionen anzeigen -make versions-show - -# 2. Version aktualisieren (z.B. Java) -make versions-update key=java value=22 - -# 3. Build-Args synchronisieren -make docker-sync - -# 4. Compose-Files neu generieren -make docker-compose-gen ENV=development - -# 5. Konsistenz validieren -make docker-validate - -# 6. Testen -make clean-all # ⚠️ Entfernt Volumes! -make full-up -make health-check -``` - -### Workflow 4: Kompletter System-Reset - -```bash -# 1. Alles stoppen -make full-down - -# 2. Alle Docker-Ressourcen entfernen -make clean-all # ⚠️ Entfernt auch Volumes und Images! - -# 3. Images neu bauen -make build - -# 4. System neu starten -make full-up - -# 5. Health-Check -make health-check - -# 6. Logs prüfen -make full-logs -``` - ---- - -**Navigation:** -- [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 - ---- - -**Letzte Aktualisierung:** 2025-11-11 -**Version:** 2.0.0 - Vollständige Makefile-Referenz mit allen 50+ Befehlen diff --git a/.junie/guidelines/technology-guides/docker/docker-monitoring.md b/.junie/guidelines/technology-guides/docker/docker-monitoring.md deleted file mode 100644 index 21112af4..00000000 --- a/.junie/guidelines/technology-guides/docker/docker-monitoring.md +++ /dev/null @@ -1,257 +0,0 @@ -# Docker-Monitoring und Observability - ---- - -guideline_type: "technology" -scope: "docker-monitoring" -audience: ["developers", "devops", "ai-assistants"] -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 - -### Prometheus Metrics - -Alle Services exposieren standardisierte Metrics: - -```yaml -# Service-Labels für Prometheus Autodiscovery -labels: - - "prometheus.scrape=true" - - "prometheus.port=8080" - - "prometheus.path=/actuator/prometheus" - - "prometheus.service=${SERVICE_NAME}" -``` - -> **🤖 AI-Assistant Hinweis:** -> Monitoring-Stack Zugriff: -> - **Grafana:** http://localhost:3000 (admin/admin) -> - **Prometheus:** http://localhost:9090 -> - **Metrics-Endpoints:** `/actuator/prometheus` für Spring-Services -> - **Health-Checks:** `/actuator/health` für Readiness-Probes - -### Grafana Dashboards - -**Vorgefertigte Dashboards:** - -- **Infrastructure Overview**: CPU, Memory, Disk, Network -- **Spring Boot Services**: JVM Metrics, HTTP Requests, Circuit Breaker -- **Database Performance**: PostgreSQL Connections, Query Performance -- **Message Queue**: Kafka Consumer Lag, Throughput -- **Business Metrics**: Application-spezifische KPIs - -### 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 | - -### Log Aggregation - -```bash -# Centralized logging mit ELK Stack (optional) -docker-compose -f docker-compose.yaml -f docker-compose.logging.yml up -d - -# Log-Parsing für strukturierte Logs -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 -- **Service Health:** http://localhost:/actuator/health - -### 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 | - -### Health-Check Befehle - -```bash -# Alle Services prüfen -docker-compose ps - -# Service-spezifische Health-Checks -curl -s http://localhost:8082/actuator/health | jq '.status' -curl -s http://localhost:8081/actuator/health | jq '.status' - -# Infrastructure Health-Checks -docker-compose exec postgres pg_isready -U meldestelle -d meldestelle -docker-compose exec redis redis-cli ping -curl -s http://localhost:8180/health/ready -``` - -### Log-Analyse - -```bash -# Service-Logs in Echtzeit -docker-compose logs -f - -# Error-Logs filtern -docker-compose logs | grep ERROR - -# JSON-Logs strukturiert anzeigen -docker-compose logs api-gateway | jq -r '. | select(.level=="ERROR") | .message' - -# Performance-Logs analysieren -docker-compose logs api-gateway | grep -i "took\|duration\|time" -``` - -### Dashboard-Setup - -#### Infrastructure-Dashboard - -```json -{ - "dashboard": { - "title": "Meldestelle Infrastructure", - "panels": [ - { - "title": "CPU Usage", - "targets": [ - { - "expr": "rate(container_cpu_usage_seconds_total[5m]) * 100" - } - ] - }, - { - "title": "Memory Usage", - "targets": [ - { - "expr": "container_memory_usage_bytes / container_spec_memory_limit_bytes * 100" - } - ] - } - ] - } -} -``` - -#### Application-Dashboard - -```json -{ - "dashboard": { - "title": "Meldestelle Services", - "panels": [ - { - "title": "HTTP Requests/sec", - "targets": [ - { - "expr": "rate(http_requests_total[1m])" - } - ] - }, - { - "title": "Response Time", - "targets": [ - { - "expr": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))" - } - ] - } - ] - } -} -``` - -### Alerting-Regeln - -```yaml -# prometheus/alerts.yaml -groups: - - name: meldestelle.rules - rules: - - alert: ServiceDown - expr: up == 0 - for: 1m - labels: - severity: critical - annotations: - summary: "Service {{ $labels.instance }} is down" - - - alert: HighMemoryUsage - expr: (container_memory_usage_bytes / container_spec_memory_limit_bytes) > 0.8 - for: 5m - labels: - severity: warning - annotations: - summary: "High memory usage on {{ $labels.instance }}" - - - alert: DatabaseConnectionsFull - expr: hikaricp_connections_active >= hikaricp_connections_max * 0.8 - for: 2m - labels: - severity: warning - annotations: - summary: "Database connection pool nearly exhausted" -``` - -### Monitoring-Wartung - -```bash -# Prometheus-Konfiguration neu laden -curl -X POST http://localhost:9090/-/reload - -# Grafana-Dashboards exportieren -curl -s -H "Authorization: Bearer " \ - http://localhost:3000/api/dashboards/uid/ > dashboard_backup.json - -# Monitoring-Data bereinigen -docker-compose exec prometheus rm -rf /prometheus/data -docker-compose restart prometheus - -# Log-Rotation für Monitoring-Services -docker-compose exec grafana find /var/log -name "*.log" -exec truncate -s 0 {} \; -``` - -### Performance-Tuning - -```yaml -# prometheus.yaml - Optimierte Konfiguration -global: - scrape_interval: 15s - evaluation_interval: 15s - -rule_files: - - "/etc/prometheus/alerts.yaml" - -scrape_configs: - - job_name: 'spring-boot' - metrics_path: '/actuator/prometheus' - static_configs: - - targets: ['api-gateway:8081', 'ping-service:8082'] - scrape_interval: 10s - - - job_name: 'infrastructure' - static_configs: - - targets: ['postgres:5432', 'redis:6379'] - scrape_interval: 30s -``` - ---- - -**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 diff --git a/.junie/guidelines/technology-guides/docker/docker-overview.md b/.junie/guidelines/technology-guides/docker/docker-overview.md deleted file mode 100644 index cf9c971c..00000000 --- a/.junie/guidelines/technology-guides/docker/docker-overview.md +++ /dev/null @@ -1,74 +0,0 @@ -# Docker-Overview und Philosophie - ---- - -guideline_type: "technology" -scope: "docker-overview" -audience: ["developers", "ai-assistants", "devops"] -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 - -Das Meldestelle-Projekt implementiert eine **moderne, sicherheitsorientierte Containerisierungsstrategie** basierend auf bewährten DevOps-Praktiken und Production-Ready-Standards. Unsere Docker-Architektur ist darauf ausgelegt: - -- **Sicherheit first**: Alle Container laufen als Non-Root-User -- **Optimale Performance**: Multi-stage Builds mit Layer-Caching -- **Observability**: Umfassendes Monitoring und Health-Checks -- **Skalierbarkeit**: Microservices-ready mit Service Discovery -- **Wartbarkeit**: Standardisierte Templates und klare Konventionen - -## 🎯 Für AI-Assistenten: Wichtige Konzepte - -> **🤖 AI-Assistant Hinweis:** -> Diese Sektion enthält die Grundphilosophie des Docker-Setups. -> - Alle Versionsinformationen sind in `docker/versions.toml` zentralisiert -> - Services sind in `docker-compose.yml` definiert -> - 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 -- `scripts/validate-docker-consistency.sh` - Konsistenz-Validierung - -## 📋 Docker-Guidelines Navigation - -Für spezifische Docker-Themen siehe: -- [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 -- **Versionierung**: Semantische Versionierung aller Images - ---- - -> **Basis-Prinzipien:** Diese Guidelines erweitern die [Master-Guideline](../../master-guideline.md) um Docker-spezifische Aspekte und folgen den allgemeinen Projektstandards. diff --git a/.junie/guidelines/technology-guides/docker/docker-production.md b/.junie/guidelines/technology-guides/docker/docker-production.md deleted file mode 100644 index 1ddc2bf0..00000000 --- a/.junie/guidelines/technology-guides/docker/docker-production.md +++ /dev/null @@ -1,230 +0,0 @@ -# Docker-Production Deployment - ---- - -guideline_type: "technology" -scope: "docker-production" -audience: ["developers", "devops", "ai-assistants"] -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 - -### Security Hardening - -Unsere Production-Konfiguration implementiert umfassende Sicherheitsmaßnahmen: - -#### 🔒 SSL/TLS Everywhere - -```bash -# TLS-Zertifikate vorbereiten -mkdir -p config/ssl/{postgres,redis,keycloak,grafana,prometheus,nginx} - -# Let's Encrypt Zertifikate generieren -certbot certonly --dns-route53 -d api.meldestelle.at -certbot certonly --dns-route53 -d auth.meldestelle.at -certbot certonly --dns-route53 -d monitor.meldestelle.at -``` - -#### 🛡️ Environment Variables - -> **🤖 AI-Assistant Hinweis:** -> Alle Passwörter werden in der Produktion mit starker Verschlüsselung generiert: -> - **PostgreSQL/Redis:** `openssl rand -base64 32` -> - **Keycloak:** Separate Admin-Credentials -> - **Monitoring:** Grafana/Prometheus Admin-Access - -**Erforderliche Production-Variablen:** - -```bash -# Datenschutz und Sicherheit -export POSTGRES_USER=meldestelle_prod -export POSTGRES_PASSWORD=$(openssl rand -base64 32) -export POSTGRES_DB=meldestelle_prod -export REDIS_PASSWORD=$(openssl rand -base64 32) - -# Keycloak Admin -export KEYCLOAK_ADMIN=admin -export KEYCLOAK_ADMIN_PASSWORD=$(openssl rand -base64 32) -export KC_DB_PASSWORD=${POSTGRES_PASSWORD} -export KC_HOSTNAME=auth.meldestelle.at - -# Monitoring -export GF_SECURITY_ADMIN_USER=admin -export GF_SECURITY_ADMIN_PASSWORD=$(openssl rand -base64 32) -export GRAFANA_HOSTNAME=monitor.meldestelle.at -export PROMETHEUS_HOSTNAME=metrics.meldestelle.at - -# Kafka Security -export KAFKA_BROKER_ID=1 -export KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181 -``` - -#### 🌐 Reverse Proxy Configuration - -**nginx.prod.conf** Beispiel: - -```nginx -upstream api_backend { - server api-gateway:8081; - keepalive 32; -} - -upstream auth_backend { - server keycloak:8443; - keepalive 32; -} - -upstream monitoring_backend { - server grafana:3443; - keepalive 32; -} - -server { - listen 443 ssl http2; - server_name api.meldestelle.at; - - ssl_certificate /etc/ssl/nginx/api.meldestelle.at.crt; - ssl_certificate_key /etc/ssl/nginx/api.meldestelle.at.key; - - # Security headers - add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; - add_header X-Frame-Options DENY always; - add_header X-Content-Type-Options nosniff always; - add_header Referrer-Policy strict-origin-when-cross-origin always; - - location / { - proxy_pass http://api_backend; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } -} -``` - -### Resource Limits - -Alle Production-Services haben definierte Resource-Limits: - -```yaml -# Beispiel für Resource-Management -services: - postgres: - deploy: - resources: - limits: - memory: 1G - cpus: '0.5' - reservations: - memory: 512M - cpus: '0.25' - - api-gateway: - deploy: - resources: - limits: - memory: 512M - cpus: '0.5' - reservations: - memory: 256M - cpus: '0.25' -``` - -## 🎯 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 -- [ ] Resource Limits für alle Services definiert -- [ ] Firewall-Regeln nur für notwendige Ports -- [ ] Container laufen als non-root User - -### 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 ` | Vulnerability Check | -| Log-Rotation | `docker system prune -f` | Alte Logs bereinigen | - -### Environment-Variablen Validierung - -```bash -# Production-Variablen prüfen -echo "Postgres User: $POSTGRES_USER" -echo "Keycloak Hostname: $KC_HOSTNAME" -echo "Grafana Hostname: $GRAFANA_HOSTNAME" - -# Passwort-Stärke prüfen (sollte 32+ Zeichen haben) -echo ${#POSTGRES_PASSWORD} # Sollte 44+ ausgeben -echo ${#KEYCLOAK_ADMIN_PASSWORD} # Sollte 44+ ausgeben -``` - -### Deployment-Workflow - -```bash -# 1. Environment-Variablen setzen -source .env.production - -# 2. SSL-Zertifikate prüfen -certbot certificates - -# 3. Services mit Production-Konfiguration starten -docker-compose -f docker-compose.yaml -f docker-compose.prod.yml up -d - -# 4. Health-Checks durchführen -curl -f https://api.meldestelle.at/actuator/health -curl -f https://auth.meldestelle.at/health/ready -curl -f https://monitor.meldestelle.at/api/health - -# 5. SSL-Konfiguration validieren -curl -I https://api.meldestelle.at | grep -i security -``` - -### Backup-Strategie - -```bash -# Datenbank-Backup -docker-compose exec postgres pg_dump -U $POSTGRES_USER $POSTGRES_DB > backup_$(date +%Y%m%d).sql - -# Konfigurationsdateien sichern -tar -czf config_backup_$(date +%Y%m%d).tar.gz config/ - -# Docker-Volumes sichern -docker run --rm -v postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup_$(date +%Y%m%d).tar.gz /data -``` - -### Monitoring-Integration - -```bash -# Prometheus-Targets prüfen -curl -s https://metrics.meldestelle.at/api/v1/targets | jq '.data.activeTargets[].health' - -# Grafana-Dashboard Status -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 diff --git a/.junie/guidelines/technology-guides/docker/docker-troubleshooting.md b/.junie/guidelines/technology-guides/docker/docker-troubleshooting.md deleted file mode 100644 index 9b037525..00000000 --- a/.junie/guidelines/technology-guides/docker/docker-troubleshooting.md +++ /dev/null @@ -1,304 +0,0 @@ -# Docker-Troubleshooting und Best Practices - ---- - -guideline_type: "technology" -scope: "docker-troubleshooting" -audience: ["developers", "devops", "ai-assistants"] -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 - -### Häufige Probleme und Lösungen - -#### 🚫 Port-Konflikte - -```bash -# Überprüfe, welche Ports verwendet werden -netstat -tulpn | grep :8080 -lsof -i :8080 - -# Stoppe konfligierende Services -docker-compose down -sudo systemctl stop apache2 # Falls Apache läuft -``` - -#### 🐌 Langsame Startup-Zeiten - -```bash -# Überprüfe Container-Ressourcen -docker stats - -# Health-Check Logs analysieren -docker-compose logs ping-service | grep health - -# Java Startup optimieren -export JAVA_OPTS="$JAVA_OPTS -XX:TieredStopAtLevel=1 -noverify" -``` - -#### 💾 Disk-Space Probleme - -```bash -# Docker-Cleanup -docker system prune -a --volumes -docker volume prune - -# Log-Rotation für Container -docker-compose logs --tail=1000 > /dev/null # Truncate logs -``` - -#### 🌐 Service Discovery Issues - -```bash -# Consul Status prüfen -curl -s http://localhost:8500/v1/health/state/any | jq - -# Service Registration überprüfen -curl -s http://localhost:8500/v1/catalog/services | jq - -# DNS-Resolution testen -docker-compose exec api-gateway nslookup ping-service -``` - -### Debug-Kommandos - -```bash -# Container introspection -docker-compose exec SERVICE_NAME sh -docker-compose exec postgres psql -U meldestelle -d meldestelle - -# Live-Monitoring -docker-compose top -watch -n 1 'docker-compose ps' - -# Memory und CPU-Usage -docker stats $(docker-compose ps -q) - -# Detailed service logs -docker-compose logs -f --tail=50 SERVICE_NAME -``` - -## 🎯 AI-Assistenten: Troubleshooting-Schnellreferenz - -### Häufige Befehle - -| Problem | Befehl | Beschreibung | -|-----------------------|---------------------------------------------------|-----------------------| -| Port belegt | `netstat -tulpn \| grep :` | Port-Nutzung prüfen | -| Service startet nicht | `docker-compose logs ` | Service-Logs anzeigen | -| Container hängt | `docker stats` | Ressourcenverbrauch | -| DNS-Probleme | `docker-compose exec nslookup ` | 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 ` - Logs analysieren -3. `docker-compose exec 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 ping ` - Connectivity testen -3. Consul Service-Discovery prüfen -4. DNS-Resolution validieren - -## ✅ Best Practices - -### 🔐 Security Best Practices - -1. **Non-Root Users**: Alle Container laufen mit dedizierten Non-Root-Usern -2. **Minimal Base Images**: Alpine Linux für kleinste Angriffsfläche -3. **Secrets Management**: Externe Secret-Stores für Production -4. **Network Isolation**: Dedizierte Docker-Networks -5. **Regular Updates**: Automatische Security-Updates für Base Images - -### ⚡ Performance Best Practices - -1. **Multi-Stage Builds**: Minimale Runtime-Images -2. **Layer Caching**: Optimale COPY-Reihenfolge in Dockerfiles -3. **Resource Limits**: Definierte Memory und CPU-Limits -4. **Health Checks**: Proaktive Container-Health-Überwachung -5. **JVM Tuning**: Container-aware JVM-Settings - -### 🧹 Wartung Best Practices - -1. **Version Pinning**: Explizite Image-Versionen in Production -2. **Backup Strategies**: Automatische Volume-Backups -3. **Log Rotation**: Begrenzte Log-Datei-Größen -4. **Documentation**: Aktuelle README-Dateien pro Service -5. **Testing**: Automatisierte Container-Tests - -### 🎯 Zentrale Verwaltung Best Practices - -#### Single Source of Truth Prinzipien - -```bash -# ✅ RICHTIG - Zentrale Version-Updates -./scripts/docker-versions-update.sh update java 22 -./scripts/docker-versions-update.sh sync - -# ❌ FALSCH - Manuelle Bearbeitung von Dockerfiles -vim dockerfiles/services/ping-service/Dockerfile # Version hardcoden -``` - -> **🤖 AI-Assistant Hinweis:** -> Verwende immer das zentrale Versionssystem: -> - **Updates:** `./scripts/docker-versions-update.sh update ` -> - **Validierung:** `./scripts/validate-docker-consistency.sh` -> - **Template-Updates:** `./scripts/generate-compose-files.sh` - -#### Port-Verwaltung Richtlinien - -1. **Immer zentrale Port-Registry verwenden**: - ```toml - # docker/versions.toml - Port-Definitionen - [service-ports] - new-service = 8089 # Nächster verfügbarer Port - ``` - -2. **Port-Konflikte vor Deployment prüfen**: - ```bash - ./scripts/validate-docker-consistency.sh - ``` - -3. **Port-Ranges einhalten**: - - Infrastructure: 8081-8088 - - Services: 8082-8099 - - Monitoring: 9090-9099 - - Clients: 4000-4099 - -#### Environment-Overrides Standards - -1. **Environment-spezifische Konfigurationen nutzen**: - ```bash - # Development - export DOCKER_ENVIRONMENT=development - - # Production - export DOCKER_ENVIRONMENT=production - ``` - -2. **Konsistente Health-Check-Konfigurationen**: - ```toml - [environments.production] - health-check-interval = "15s" - health-check-timeout = "3s" - health-check-retries = 3 - ``` - -#### Template-System Richtlinien - -1. **Compose-Files aus Templates generieren**: - ```bash - # Automatische Generierung bevorzugen - ./scripts/generate-compose-files.sh - - # Manuelle Bearbeitung nur bei spezifischen Anpassungen - ``` - -2. **Service-Kategorien korrekt zuordnen**: - - `services/`: Domain-Services (ping, members, horses) - - `infrastructure/`: Platform-Services (gateway, auth, monitoring) - - `clients/`: Frontend-Anwendungen (web-app, desktop-app) - -#### Validierung und Konsistenz - -1. **Regelmäßige Konsistenz-Prüfungen**: - ```bash - # Bei jedem Build - ./scripts/validate-docker-consistency.sh - - # In CI/CD Pipeline integrieren - ``` - -2. **Build-Args Konsistenz**: - ```dockerfile - # ✅ RICHTIG - Zentrale Referenz - ARG GRADLE_VERSION - ARG JAVA_VERSION - - # ❌ FALSCH - Hardcodierte Versionen - ARG GRADLE_VERSION=9.0.0 - ``` - -#### IDE-Integration Best Practices - -1. **JSON Schema für Validierung aktivieren**: - ```json - { - "yaml.schemas": { - "./docker/schemas/versions-schema.json": "docker/versions.toml" - } - } - ``` - -2. **Automatisierte Tasks nutzen**: - - Docker: Show Versions - - Docker: Validate Consistency - - Docker: Build All Services - -### 🚀 Entwickler-Workflow Best Practices - -#### Neuen Service hinzufügen - -```bash -# 1. Port in versions.toml reservieren -echo "new-service = 8089" >> docker/versions.toml - -# 2. Template-basierten Service erstellen -./scripts/generate-compose-files.sh - -# 3. Dockerfile aus Template erstellen -cp dockerfiles/templates/spring-boot-service.Dockerfile \ - dockerfiles/services/new-service/Dockerfile - -# 4. Build-Args und Environment synchronisieren -./scripts/docker-versions-update.sh sync - -# 5. Konsistenz validieren -./scripts/validate-docker-consistency.sh -``` - -#### Version-Updates durchführen - -```bash -# 1. Aktuelle Versionen prüfen -./scripts/docker-versions-update.sh show - -# 2. Spezifische Version aktualisieren -./scripts/docker-versions-update.sh update java 22 - -# 3. Alle Build-Args synchronisieren -./scripts/docker-versions-update.sh sync - -# 4. Services neu bauen -docker-compose build --no-cache - -# 5. System-Tests durchführen -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 diff --git a/.junie/guidelines/technology-guides/web-app-guideline.md b/.junie/guidelines/technology-guides/web-app-guideline.md deleted file mode 100644 index 5fa5e5aa..00000000 --- a/.junie/guidelines/technology-guides/web-app-guideline.md +++ /dev/null @@ -1,216 +0,0 @@ -# Client-App-Richtlinie (Compose Multiplatform) - ---- - -guideline_type: "technology" -scope: "web-app-multiplatform" -audience: ["developers", "ai-assistants", "frontend-developers"] -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 - -Diese Richtlinie beschreibt die Architektur und die Best Practices für die Entwicklung der Client-Anwendungen für das "Meldestelle"-Projekt. Die Client-Anwendungen werden mit **Compose Multiplatform** für Desktop und Web entwickelt. - -Das Hauptziel ist die maximale Wiederverwendung von Code zwischen den Desktop- und Web-Plattformen durch die konsequente Nutzung des `commonMain`-Source-Sets von Kotlin Multiplatform (KMP). Die Anwendung läuft sowohl als native Desktop-Anwendung (JVM) als auch als Web-Anwendung (WebAssembly). - -> **🤖 AI-Assistant Hinweis:** -> Compose Multiplatform Entwicklung folgt diesen Kernprinzipien: -> - **commonMain:** Geteilte UI-Logik und Business-Logic -> - **MVVM-Pattern:** ViewModels in commonMain, UI-Components plattformübergreifend -> - **@Composable-Funktionen:** Deklarative UI mit State Hoisting -> - **expect/actual:** Plattformspezifische Implementierungen nur wo nötig - -## 2. Grundprinzipien - -### 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:** 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. - -### State Management - -Der UI-Zustand (State) wird explizit verwaltet. - -- **`mutableStateOf` und `remember`**: Für einfachen, temporären UI-Zustand innerhalb einer Composable-Funktion. -- **State Hoisting**: Der Zustand sollte so weit wie möglich nach oben in der Komponentenhierarchie verschoben werden ("State Hoisting"), idealerweise in eine ViewModel- oder Presenter-Klasse in `commonMain`. -- **ViewModels/Presenters**: Komplexe Logik zur Zustandsverwaltung gehört in Klassen (z. B. `ExampleViewModel`) im `commonMain`-Modul. Diese Klassen sind plattformunabhängig und können von der UI (im `jsMain`-Modul) genutzt werden. - -### Styling - -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. -- **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.). - -```kotlin -// Beispiel für gemeinsames Theming in commonMain -@Composable -fun AppTheme(content: @Composable () -> Unit) { - MaterialTheme( - colorScheme = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme(), - typography = AppTypography, - content = content - ) -} -``` - -### 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 - -- **`client/src/commonMain`**: - - **UI-Code**: Alle `@Composable`-Funktionen, die zwischen Desktop und Web geteilt werden. - - **Business-Logik**: ViewModels/Presenters, die den UI-Zustand verwalten. - - **Data-Klassen**: Modelle, die Daten repräsentieren. - - **Common Dependencies**: Shared Compose-Dependencies (runtime, foundation, material3, ui). - -- **`client/src/jvmMain`** (Desktop-Plattform): - - **`main.kt`**: Der Einstiegspunkt der Desktop-Anwendung. - - **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-spezifischer Code**: Browser-spezifische Implementierungen. - - **Platform-spezifische Implementierungen**: Web-APIs und Browser-Integrationen. - -- **`client/src/wasmJsMain/resources`**: - - **`index.html`**: Das Host-HTML-Dokument für die Compose-Anwendung. - - **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. - -## 4. Entwicklung und Ausführung - -### Desktop-Entwicklung - -Für die Desktop-Anwendung stehen folgende Gradle-Tasks zur Verfügung: - -```shell script -# Desktop-Anwendung direkt ausführen -./gradlew :client:run - -# Desktop-Distribution erstellen (DMG, MSI, DEB) -./gradlew :client:createDistributable -./gradlew :client:packageDmg # macOS -./gradlew :client:packageMsi # Windows -./gradlew :client:packageDeb # Linux -``` - -### Web-Entwicklung mit Hot-Reload - -Für die Web-Anwendung mit automatischer Neuladung bei Änderungen: - -```shell script -# Web-App mit Hot-Reload starten -./gradlew :client:wasmJsBrowserDevelopmentRun -``` - -#### 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 -# Startet die Web-App mit Hot-Reload -docker-compose -f docker-compose.yaml \ --f docker-compose.frontend.yaml up -d web-app -``` - -Der Dienst ist dann unter dem in der `docker-compose.clients.yml` konfigurierten Port (z.B. Port `3000`) erreichbar. - -### 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. - -## 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 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. -- **DON'T**: Annahmen über die Zielplattform in `commonMain` machen. - ---- - -**Navigation:** -- [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 diff --git a/.junie/scripts/check-docs-drift.sh b/.junie/scripts/check-docs-drift.sh old mode 100644 new mode 100755 index 4440138d..c4db519d --- a/.junie/scripts/check-docs-drift.sh +++ b/.junie/scripts/check-docs-drift.sh @@ -1,43 +1,43 @@ #!/usr/bin/env bash set -euo pipefail +# check-docs-drift.sh +# Zweck: sehr schlanke Drift-Checks gegen die neue Doku-Struktur. +# - Kein Guidelines-System mehr. +# - Single Source of Truth: `docs/` + err=0 has() { grep -q "$2" "$1" || { echo "[DRIFT] '$2' fehlt in $1"; err=1; }; } miss() { grep -q "$2" "$1" && { echo "[DRIFT] Veralteter Begriff '$2' in $1"; err=1; }; } -# Quelle der Wahrheit: Spring Cloud Gateway -has docs/overview/system-overview.md "Spring Cloud Gateway" -has docs/architecture/adr/0007-api-gateway-pattern-de.md "Spring Cloud Gateway" -miss docs/architecture/adr/0007-api-gateway-pattern-de.md "Ktor" - -# C4: Container muss Technology korrekt führen -has docs/architecture/c4/02-container-de.puml "Spring Cloud Gateway" -miss docs/architecture/c4/02-container-de.puml "Ktor" - -# Verbiete versehentlich verbliebene englische ADR/C4 ohne -de -if ls docs/architecture/adr/*.md 2>/dev/null | grep -E -v '-de\.md$' >/dev/null; then - echo "[DRIFT] Englische ADR-Dateien ohne -de gefunden in docs/architecture/adr/" - ls docs/architecture/adr/*.md | grep -E -v '-de\.md$' || true +# Harte Altlast-Pfade dürfen nicht mehr vorkommen +if git grep -n "docs/00_Domain/" -- docs >/dev/null 2>&1; then + echo "[DRIFT] Veralteter Pfad 'docs/00_Domain/' in docs/* gefunden" err=1 fi -if ls docs/architecture/c4/*.puml 2>/dev/null | grep -E -v '-de\.puml$' >/dev/null; then - echo "[DRIFT] Englische C4-Dateien ohne -de gefunden in docs/architecture/c4/" - ls docs/architecture/c4/*.puml | grep -E -v '-de\.puml$' || true +if git grep -n "docs/adr/" -- docs >/dev/null 2>&1; then + echo "[DRIFT] Veralteter Pfad 'docs/adr/' in docs/* gefunden" + err=1 +fi +if git grep -n "docs/c4/" -- docs >/dev/null 2>&1; then + echo "[DRIFT] Veralteter Pfad 'docs/c4/' in docs/* gefunden" + err=1 +fi +if git grep -n "docs/how-to/" -- docs >/dev/null 2>&1; then + echo "[DRIFT] Veralteter Pfad 'docs/how-to/' in docs/* gefunden" + err=1 +fi +if git grep -n "docs/reference/" -- docs >/dev/null 2>&1; then + echo "[DRIFT] Veralteter Pfad 'docs/reference/' in docs/* gefunden" err=1 fi -# ADR-Stubs: max. 40 Zeilen und YouTrack-Link Pflicht, wenn als Stub gekennzeichnet -for f in $(grep -RIl "^doc_type: adr-link" docs/architecture/adr 2>/dev/null || true); do - lines=$(wc -l < "$f" | tr -d ' ') - if [ "${lines}" -gt 40 ]; then - echo "[DRIFT] ADR-Stub überschreitet 40 Zeilen: $f (${lines})" - err=1 - fi - if ! grep -Eiq "https?://[^ ]*youtrack" "$f"; then - echo "[DRIFT] ADR-Stub ohne YouTrack-Link: $f" - err=1 - fi -done +# Quelle der Wahrheit: Gateway-Technologie (sollte in Architektur/ADRs/C4 konsistent sein) +has docs/01_Architecture/ARCHITECTURE.md "Spring Cloud Gateway" +has docs/01_Architecture/adr/0007-api-gateway-pattern-de.md "Spring Cloud Gateway" +miss docs/01_Architecture/adr/0007-api-gateway-pattern-de.md "Ktor" +has docs/01_Architecture/c4/02-container-de.puml "Spring Cloud Gateway" +miss docs/01_Architecture/c4/02-container-de.puml "Ktor" exit $err diff --git a/.junie/scripts/create-guideline.sh b/.junie/scripts/create-guideline.sh deleted file mode 100755 index 481eb1f2..00000000 --- a/.junie/scripts/create-guideline.sh +++ /dev/null @@ -1,308 +0,0 @@ -#!/bin/bash - -# create-guideline.sh - Automatisierte Guideline-Erstellung für Meldestelle Guidelines -# Version: 1.0.0 -# Autor: Junie AI-Assistant -# Datum: 2025-09-15 - -set -euo pipefail - -# Bestimme das Projekt-Root-Verzeichnis -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" - -# Wechsle ins Projekt-Root für korrekte relative Pfade -cd "$PROJECT_ROOT" - -GUIDELINES_DIR=".junie/guidelines" -TEMPLATES_DIR="$GUIDELINES_DIR/_templates" -META_DIR="$GUIDELINES_DIR/_meta" - -# Farben für Output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -NC='\033[0m' # No Color - -# Logging-Funktionen -log_info() { - echo -e "${BLUE}ℹ️ $1${NC}" -} - -log_success() { - echo -e "${GREEN}✅ $1${NC}" -} - -log_warning() { - echo -e "${YELLOW}⚠️ $1${NC}" -} - -log_error() { - echo -e "${RED}❌ $1${NC}" -} - -# Hilfe-Funktion -show_help() { - cat << 'EOF' -Meldestelle Guidelines Creator - -USAGE: - ./create-guideline.sh [TYPE] [NAME] [SCOPE] [OPTIONS] - -ARGUMENTE: - TYPE Typ der Guideline (project-standard|process-guide|technology) - NAME Name der neuen Guideline (ohne .md Extension) - SCOPE Bereich/Scope der Guideline - -OPTIONEN: - --output-dir DIR Alternatives Zielverzeichnis (Standard: entsprechend TYPE) - --no-meta-update Metadaten (versions.json) nicht automatisch aktualisieren - --dry-run Zeige nur was erstellt würde, ohne Dateien zu schreiben - --help Diese Hilfe anzeigen - -BEISPIELE: - ./create-guideline.sh project-standard security-standards security-practices - ./create-guideline.sh process-guide deployment-process deployment-workflow - ./create-guideline.sh technology kubernetes-guide kubernetes-orchestration - -VERFÜGBARE TEMPLATES: - project-standard-template.md -> project-standards/ - process-guide-template.md -> process-guides/ - technology-guideline-template.md -> technology-guides/ - -EOF -} - -# Globale Variablen -TYPE="" -NAME="" -SCOPE="" -OUTPUT_DIR="" -NO_META_UPDATE=false -DRY_RUN=false - -# Command-line Parameter parsen -parse_arguments() { - if [[ $# -eq 0 ]] || [[ "$1" == "--help" ]] || [[ "$1" == "-h" ]]; then - show_help - exit 0 - fi - - # Erforderliche Argumente - if [[ $# -lt 3 ]]; then - log_error "Nicht genug Argumente. Benötigt: TYPE NAME SCOPE" - echo "Nutze --help für Details" - exit 1 - fi - - TYPE="$1" - NAME="$2" - SCOPE="$3" - shift 3 - - # Optionale Parameter - while [[ $# -gt 0 ]]; do - case $1 in - --output-dir) - OUTPUT_DIR="$2" - shift 2 - ;; - --no-meta-update) - NO_META_UPDATE=true - shift - ;; - --dry-run) - DRY_RUN=true - shift - ;; - *) - log_error "Unbekannter Parameter: $1" - echo "Nutze --help für verfügbare Optionen" - exit 1 - ;; - esac - done -} - -# Template-Pfad und Zielverzeichnis bestimmen -determine_paths() { - local template_file="" - local default_target_dir="" - - case "$TYPE" in - "project-standard") - template_file="$TEMPLATES_DIR/project-standard-template.md" - default_target_dir="$GUIDELINES_DIR/project-standards" - ;; - "process-guide") - template_file="$TEMPLATES_DIR/process-guide-template.md" - default_target_dir="$GUIDELINES_DIR/process-guides" - ;; - "technology") - template_file="$TEMPLATES_DIR/technology-guideline-template.md" - default_target_dir="$GUIDELINES_DIR/technology-guides" - ;; - *) - log_error "Unbekannter Guideline-Typ: $TYPE" - echo "Verfügbare Typen: project-standard, process-guide, technology" - exit 1 - ;; - esac - - if [[ ! -f "$template_file" ]]; then - log_error "Template nicht gefunden: $template_file" - exit 1 - fi - - # Zielverzeichnis bestimmen - if [[ -n "$OUTPUT_DIR" ]]; then - TARGET_DIR="$OUTPUT_DIR" - else - TARGET_DIR="$default_target_dir" - fi - - TARGET_FILE="$TARGET_DIR/$NAME.md" - TEMPLATE_PATH="$template_file" -} - -# Prüfe ob Ziel bereits existiert -check_target_exists() { - if [[ -f "$TARGET_FILE" ]]; then - log_error "Guideline existiert bereits: $TARGET_FILE" - log_info "Lösche die existierende Datei oder wähle einen anderen Namen" - exit 1 - fi - - # Stelle sicher, dass Zielverzeichnis existiert - if [[ "$DRY_RUN" = false ]] && [[ ! -d "$TARGET_DIR" ]]; then - mkdir -p "$TARGET_DIR" - log_info "Zielverzeichnis erstellt: $TARGET_DIR" - fi -} - -# Template-Platzhalter ersetzen -process_template() { - local current_date=$(date +%Y-%m-%d) - local processed_content - - if [[ "$DRY_RUN" = true ]]; then - log_info "DRY-RUN: Würde Template verarbeiten..." - log_info " Template: $TEMPLATE_PATH" - log_info " NAME: $NAME" - log_info " SCOPE: $SCOPE" - log_info " DATE: $current_date" - log_info " Ziel: $TARGET_FILE" - return - fi - - # Template lesen und Platzhalter ersetzen - processed_content=$(cat "$TEMPLATE_PATH") - processed_content="${processed_content//\{\{NAME\}\}/$NAME}" - processed_content="${processed_content//\{\{SCOPE\}\}/$SCOPE}" - processed_content="${processed_content//\{\{DATE\}\}/$current_date}" - - # Zieldatei erstellen - echo "$processed_content" > "$TARGET_FILE" - log_success "Neue Guideline erstellt: $TARGET_FILE" -} - -# Metadaten aktualisieren -update_metadata() { - if [[ "$NO_META_UPDATE" = true ]]; then - log_info "Überspringe Metadaten-Update (--no-meta-update)" - return - fi - - if [[ "$DRY_RUN" = true ]]; then - log_info "DRY-RUN: Würde Metadaten aktualisieren..." - return - fi - - local versions_file="$META_DIR/versions.json" - if [[ ! -f "$versions_file" ]]; then - log_warning "versions.json nicht gefunden: $versions_file" - return - fi - - # Relative Pfad für versions.json - local relative_path="${TARGET_FILE#$GUIDELINES_DIR/}" - local current_date=$(date +%Y-%m-%d) - - # Temporäre JSON-Update (einfache Implementierung) - # In einer vollständigen Implementation würde man jq verwenden - log_info "Metadaten-Update für $relative_path implementierung ausstehend" - log_warning "Bitte aktualisieren Sie $versions_file manuell" -} - -# Cross-Referenzen aktualisieren -update_cross_references() { - if [[ "$DRY_RUN" = true ]]; then - log_info "DRY-RUN: Würde Cross-Referenzen aktualisieren..." - return - fi - - local cross_refs_file="$META_DIR/cross-refs.json" - if [[ ! -f "$cross_refs_file" ]]; then - log_warning "cross-refs.json nicht gefunden: $cross_refs_file" - return - fi - - log_info "Cross-Referenz-Update implementierung ausstehend" - log_warning "Bitte aktualisieren Sie $cross_refs_file manuell" -} - -# Validierung der neuen Guideline -validate_new_guideline() { - if [[ "$DRY_RUN" = true ]]; then - log_info "DRY-RUN: Würde neue Guideline validieren..." - return - fi - - log_info "Validiere neue Guideline..." - - # Nutze das validate-links.sh Script falls verfügbar - local validate_script=".junie/scripts/validate-links.sh" - if [[ -x "$validate_script" ]]; then - log_info "Führe Link-Validierung aus..." - if "$validate_script" --quick; then - log_success "Validierung erfolgreich!" - else - log_warning "Validierung ergab Warnungen - bitte prüfen Sie die Ausgabe" - fi - else - log_warning "validate-links.sh nicht verfügbar - manuelle Validierung empfohlen" - fi -} - -# Hauptfunktion -main() { - echo "🚀 Meldestelle Guidelines Creator" - echo "==================================" - - parse_arguments "$@" - determine_paths - check_target_exists - process_template - update_metadata - update_cross_references - validate_new_guideline - - echo "" - if [[ "$DRY_RUN" = true ]]; then - log_info "DRY-RUN abgeschlossen - keine Dateien wurden geändert" - else - log_success "Guideline-Erstellung erfolgreich abgeschlossen!" - echo "" - echo "📋 Nächste Schritte:" - echo "1. Bearbeiten Sie die neue Guideline: $TARGET_FILE" - echo "2. Aktualisieren Sie die Metadaten manuell:" - echo " - $META_DIR/versions.json" - echo " - $META_DIR/cross-refs.json" - echo "3. Führen Sie eine vollständige Validierung aus:" - echo " - .junie/scripts/validate-links.sh" - fi -} - -# Script ausführen -main "$@" diff --git a/.junie/scripts/pre-commit-guidelines.sh b/.junie/scripts/pre-commit-guidelines.sh deleted file mode 100755 index 224f762f..00000000 --- a/.junie/scripts/pre-commit-guidelines.sh +++ /dev/null @@ -1,174 +0,0 @@ -#!/bin/bash -# -# Pre-commit Hook für Meldestelle Guidelines Validierung -# Installation: ln -s ../../.junie/scripts/pre-commit-guidelines.sh .git/hooks/pre-commit -# - -set -e - -echo "🔍 Pre-commit Guidelines Validation..." -echo "======================================" - -# Prüfe ob Guidelines-Änderungen vorliegen -GUIDELINES_CHANGED=$(git diff --cached --name-only | grep -E '\.junie/(guidelines|scripts)/' || true) - -if [[ -z "$GUIDELINES_CHANGED" ]]; then - echo "ℹ️ Keine Guidelines-Änderungen erkannt - überspringe Validierung" - exit 0 -fi - -echo "📝 Geänderte Guidelines-Dateien:" -echo "$GUIDELINES_CHANGED" | sed 's/^/ - /' -echo "" - -# Arbeitsverzeichnis sicherstellen -cd "$(git rev-parse --show-toplevel)" - -# Temporäres Verzeichnis für Staging-Area-Dateien -TEMP_DIR=$(mktemp -d) -trap "rm -rf $TEMP_DIR" EXIT - -# Staging-Area-Dateien extrahieren für Validierung -echo "🔄 Extrahiere Staging-Area-Dateien..." -echo "$GUIDELINES_CHANGED" | while read file; do - if [[ -n "$file" ]]; then - mkdir -p "$TEMP_DIR/$(dirname "$file")" - git show ":$file" > "$TEMP_DIR/$file" 2>/dev/null || { - # Neue Dateien (noch nicht im Repository) - if [[ -f "$file" ]]; then - cp "$file" "$TEMP_DIR/$file" - fi - } - fi -done - -# 1. YAML-Syntax Schnellprüfung -echo "📋 Prüfe YAML-Syntax..." -yaml_errors=0 -find "$TEMP_DIR/.junie/guidelines" -name "*.md" -not -path "*/_archived/*" 2>/dev/null | while read file; do - if [[ -f "$file" ]]; then - # YAML-Header extrahieren - yaml_content=$(sed -n '/^---$/,/^---$/p' "$file" | head -n -1 | tail -n +2) - if [[ -n "$yaml_content" ]]; then - echo "$yaml_content" | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)" 2>/dev/null || { - echo " ❌ YAML-Fehler in $(basename "$file")" - yaml_errors=$((yaml_errors + 1)) - } - fi - fi -done - -if [[ $yaml_errors -gt 0 ]]; then - echo "❌ $yaml_errors YAML-Syntax-Fehler gefunden" - exit 1 -fi - -# 2. Erforderliche Metadaten prüfen -echo "🏷️ Prüfe erforderliche Metadaten..." -metadata_errors=0 -find "$TEMP_DIR/.junie/guidelines" -name "*.md" -not -path "*/_archived/*" -not -name "README.md" 2>/dev/null | while read file; do - if [[ -f "$file" ]]; then - filename=$(basename "$file") - missing_fields=() - - if ! grep -q "guideline_type:" "$file"; then - missing_fields+=("guideline_type") - fi - if ! grep -q "ai_context:" "$file"; then - missing_fields+=("ai_context") - fi - if ! grep -q "last_updated:" "$file"; then - missing_fields+=("last_updated") - fi - - if [[ ${#missing_fields[@]} -gt 0 ]]; then - echo " ❌ $filename fehlt: ${missing_fields[*]}" - metadata_errors=$((metadata_errors + 1)) - fi - fi -done - -if [[ $metadata_errors -gt 0 ]]; then - echo "❌ $metadata_errors Metadaten-Fehler gefunden" - exit 1 -fi - -# 3. JSON-Konfigurationsdateien validieren -echo "🔧 Prüfe JSON-Konfiguration..." -json_errors=0 -find "$TEMP_DIR/.junie/guidelines/_meta" -name "*.json" 2>/dev/null | while read file; do - if [[ -f "$file" ]]; then - jq empty "$file" 2>/dev/null || { - echo " ❌ JSON-Syntax-Fehler in $(basename "$file")" - json_errors=$((json_errors + 1)) - } - fi -done - -if [[ $json_errors -gt 0 ]]; then - echo "❌ $json_errors JSON-Syntax-Fehler gefunden" - exit 1 -fi - -# 4. Aktuelles Datum in last_updated prüfen -echo "📅 Prüfe Datum-Aktualität..." -current_date=$(date +%Y-%m-%d) -date_warnings=0 -find "$TEMP_DIR/.junie/guidelines" -name "*.md" -not -path "*/_archived/*" 2>/dev/null | while read file; do - if [[ -f "$file" ]]; then - filename=$(basename "$file") - if grep -q "last_updated:" "$file"; then - file_date=$(grep "last_updated:" "$file" | cut -d'"' -f2 2>/dev/null || echo "") - if [[ "$file_date" != "$current_date" && -n "$file_date" ]]; then - echo " ⚠️ $filename hat Datum $file_date (heute: $current_date)" - date_warnings=$((date_warnings + 1)) - fi - fi - fi -done - -if [[ $date_warnings -gt 0 ]]; then - echo "⚠️ $date_warnings Guidelines haben veraltete Daten (wird toleriert)" -fi - -# 5. Script-Berechtigungen prüfen (nur bei geänderten Scripts) -SCRIPT_CHANGES=$(echo "$GUIDELINES_CHANGED" | grep -E '\.junie/scripts/.*\.sh$' || true) -if [[ -n "$SCRIPT_CHANGES" ]]; then - echo "⚙️ Prüfe Script-Berechtigungen..." - script_errors=0 - echo "$SCRIPT_CHANGES" | while read script; do - if [[ -f "$script" && ! -x "$script" ]]; then - echo " ❌ $script ist nicht ausführbar" - script_errors=$((script_errors + 1)) - fi - done - - if [[ $script_errors -gt 0 ]]; then - echo "❌ $script_errors Script-Berechtigungsfehler" - echo "💡 Lösung: chmod +x " - exit 1 - fi -fi - -# 6. Schnelle Link-Validierung (nur bei verfügbarem validate-links.sh) -if [[ -x ".junie/scripts/validate-links.sh" ]]; then - echo "🔗 Schnelle Link-Validierung..." - if ! ./.junie/scripts/validate-links.sh --quick --staged 2>/dev/null; then - echo "⚠️ Link-Validierung fehlgeschlagen (wird toleriert im Pre-commit)" - fi -fi - -# Erfolgreiche Validierung -echo "" -echo "✅ Pre-commit Guidelines Validation erfolgreich!" -echo " - YAML-Syntax: OK" -echo " - Metadaten: OK" -echo " - JSON-Konfiguration: OK" -echo " - Script-Berechtigungen: OK" -if [[ $date_warnings -gt 0 ]]; then - echo " - Datum-Warnings: $date_warnings (toleriert)" -fi -echo "" -echo "🚀 Commit kann fortgesetzt werden..." - -exit 0 diff --git a/.junie/scripts/validate-links.sh b/.junie/scripts/validate-links.sh index 92a85cdf..65fac53b 100755 --- a/.junie/scripts/validate-links.sh +++ b/.junie/scripts/validate-links.sh @@ -1,343 +1,142 @@ -#!/bin/bash - -# validate-links.sh - Automatisierte Link-Validierung für Meldestelle Guidelines -# Version: 1.0.0 -# Autor: Junie AI-Assistant -# Datum: 2025-09-15 - +#!/usr/bin/env bash set -euo pipefail -# Bestimme das Projekt-Root-Verzeichnis +# validate-links.sh - Link-Validierung für Projektdokumentation (`docs/**`). +# Zweck: Guardrail für die neue Doku-Strategie (Single Source of Truth = `docs/`). +# Hinweis: Das frühere Guidelines-System (`.junie/guidelines/**`) ist entfernt. + SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" - -# Wechsle ins Projekt-Root für korrekte relative Pfade cd "$PROJECT_ROOT" -GUIDELINES_DIR=".junie/guidelines" -META_DIR="$GUIDELINES_DIR/_meta" -CROSS_REFS_FILE="$META_DIR/cross-refs.json" -SCRIPTS_DIR=".junie/scripts" - -# Farben für Output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -NC='\033[0m' # No Color - -# Logging-Funktionen -log_info() { - echo -e "${BLUE}ℹ️ $1${NC}" -} - -log_success() { - echo -e "${GREEN}✅ $1${NC}" -} - -log_warning() { - echo -e "${YELLOW}⚠️ $1${NC}" -} - -log_error() { - echo -e "${RED}❌ $1${NC}" -} - -# Hauptvariablen -ERRORS=0 -WARNINGS=0 QUICK_MODE=false -# Command-line Parameter while [[ $# -gt 0 ]]; do - case $1 in - --quick) - QUICK_MODE=true - shift - ;; - --help|-h) - cat << 'EOF' -Meldestelle Guidelines Link-Validierung + case $1 in + --quick) + QUICK_MODE=true + shift + ;; + --help|-h) + cat << 'EOF' +Docs Link-Validierung USAGE: - ./validate-links.sh [OPTIONS] - -OPTIONS: - --quick Schnelle Validierung (nur kritische Checks) - --help Diese Hilfe anzeigen + ./.junie/scripts/validate-links.sh [--quick] BESCHREIBUNG: - Validiert alle Links und Cross-Referenzen in den Guidelines basierend auf - der cross-refs.json Matrix. Prüft: - - - Cross-Referenzen zwischen Guidelines - - Markdown-Links in Guidelines - - YAML-Metadaten-Konsistenz - - Template-Struktur-Konsistenz - -EXIT-CODES: - 0 = Alle Validierungen erfolgreich - 1 = Fehler gefunden - 2 = Warnings gefunden (nur bei --strict) + Prüft Markdown-Links in `docs/**/*.md` auf gebrochene relative Pfade. + Ignoriert externe Links (http/https/mailto) sowie reine Anchors (#...). +OPTIONEN: + --quick Nur schnelle Checks (zusätzlich werden harte Altlast-Pfade geprüft) EOF - exit 0 - ;; - *) - log_error "Unbekannter Parameter: $1" - echo "Nutze --help für Hilfe" - exit 1 - ;; - esac + exit 0 + ;; + *) + echo "[ERROR] Unbekannter Parameter: $1" >&2 + exit 2 + ;; + esac done -echo "🔍 Meldestelle Guidelines Link-Validierung" -echo "==================================================" -echo "Datum: $(date '+%Y-%m-%d %H:%M:%S')" -echo "Modus: $([ "$QUICK_MODE" = true ] && echo "Quick" || echo "Vollständig")" -echo "" +python3 - <<'PY' +import os +import re +import sys +from pathlib import Path +from urllib.parse import unquote -# Prüfe ob erforderliche Dateien existieren -if [[ ! -f "$CROSS_REFS_FILE" ]]; then - log_error "Cross-Referenz-Datei nicht gefunden: $CROSS_REFS_FILE" - exit 1 -fi +root = Path.cwd() +docs_dir = root / "docs" -if [[ ! -d "$GUIDELINES_DIR" ]]; then - log_error "Guidelines-Verzeichnis nicht gefunden: $GUIDELINES_DIR" - exit 1 -fi +if not docs_dir.is_dir(): + print(f"[ERROR] docs-Verzeichnis nicht gefunden: {docs_dir}", file=sys.stderr) + sys.exit(2) -# 1. Cross-Referenz-Validierung -validate_cross_references() { - log_info "Validiere Cross-Referenzen aus cross-refs.json..." +# Harte Altlast-Pfade, die nicht mehr im Repo vorkommen sollen +FORBIDDEN_SUBSTRINGS = [ + "docs/00_Domain/", + "docs/adr/", + "docs/c4/", + "docs/how-to/", + "docs/reference/", +] - local temp_guidelines=$(mktemp) - local temp_refs=$(mktemp) +md_files = sorted(docs_dir.rglob("*.md")) - # Alle Guidelines aus cross-refs.json extrahieren - jq -r '.cross_references | keys[]' "$CROSS_REFS_FILE" > "$temp_guidelines" 2>/dev/null || { - log_error "Fehler beim Lesen der cross-refs.json" - ((ERRORS++)) - return - } +link_pattern = re.compile(r"\]\(([^)]+)\)") - while IFS= read -r guideline; do - # Special handling for README.md which is at project root - if [[ "$guideline" == "README.md" ]]; then - guideline_file="$PROJECT_ROOT/README.md" - else - guideline_file="$GUIDELINES_DIR/$guideline" - fi +errors = 0 - # Prüfe ob Guideline-Datei existiert - if [[ ! -f "$guideline_file" ]]; then - log_error "Guideline '$guideline' in cross-refs.json aber Datei fehlt: $guideline_file" - ((ERRORS++)) +def is_external(target: str) -> bool: + t = target.lower() + return t.startswith("http://") or t.startswith("https://") or t.startswith("mailto:") + +def strip_fragment_and_query(target: str) -> str: + # remove fragment and query parts + target = target.split("#", 1)[0] + target = target.split("?", 1)[0] + return target + +for f in md_files: + text = f.read_text(encoding="utf-8", errors="replace") + + for forbidden in FORBIDDEN_SUBSTRINGS: + if forbidden in text: + print(f"[ERROR] Veralteter Pfad '{forbidden}' in {f}") + errors += 1 + + for match in link_pattern.finditer(text): + target = match.group(1).strip() + + if not target: continue - fi - - # Hole referenzierte Guidelines aus JSON - jq -r ".cross_references[\"$guideline\"].references_to[]? // empty" "$CROSS_REFS_FILE" > "$temp_refs" 2>/dev/null - - while IFS= read -r ref; do - # Skip leere Zeilen - [[ -z "$ref" ]] && continue - - # Relativer Pfad zu absolut konvertieren - if [[ "$ref" == /* ]]; then - ref_file="$GUIDELINES_DIR$ref" - elif [[ "$ref" == *"/" ]]; then - # Directory-Referenz (z.B. technology-guides/docker/) - ref_dir="$GUIDELINES_DIR/$ref" - if [[ ! -d "$ref_dir" ]]; then - log_error "Referenziertes Verzeichnis '$ref' existiert nicht: $ref_dir" - ((ERRORS++)) - fi - continue - else - # Alle Referenzen sind relativ zum Guidelines-Root-Verzeichnis - ref_file="$GUIDELINES_DIR/$ref" - fi - - # Normalisiere Pfad - ref_file=$(realpath -m "$ref_file" 2>/dev/null || echo "$ref_file") - - # Prüfe ob referenzierte Datei existiert - if [[ ! -f "$ref_file" ]]; then - log_error "'$guideline' referenziert '$ref', aber Datei existiert nicht: $ref_file" - ((ERRORS++)) - continue - fi - - # Prüfe ob der Link tatsächlich im Markdown existiert (nur im vollständigen Modus) - if [[ "$QUICK_MODE" = false ]]; then - ref_basename=$(basename "$ref" .md) - # Check for link with basename in brackets OR reference path (with or without directory) in parentheses - if ! grep -q "\[$ref_basename\]" "$guideline_file" && ! grep -qE "\([^)]*$ref\)" "$guideline_file"; then - log_warning "'$guideline' sollte '$ref' referenzieren, aber Link fehlt im Markdown" - ((WARNINGS++)) - fi - fi - - done < "$temp_refs" - - log_success "'$guideline' - Cross-Referenzen validiert" - - done < "$temp_guidelines" - - rm -f "$temp_guidelines" "$temp_refs" -} - -# 2. Markdown-Links Validierung -validate_markdown_links() { - if [[ "$QUICK_MODE" = true ]]; then - log_info "Überspringe Markdown-Link-Validierung (Quick-Modus)" - return - fi - - log_info "Validiere Markdown-Links in Guidelines..." - - find "$GUIDELINES_DIR" -name "*.md" -not -path "*/_archived/*" | while read file; do - # Relative Links extrahieren ([Text](./path/file.md)) - grep -o "\[.*\](\./[^)]*\.md)" "$file" 2>/dev/null | sed 's/.*(\.\///' | sed 's/).*//' | while read link; do - [[ -z "$link" ]] && continue - - # Absoluten Pfad konstruieren - dir=$(dirname "$file") - target_file="$dir/$link" - target_file=$(realpath -m "$target_file" 2>/dev/null || echo "$target_file") - - if [[ ! -f "$target_file" ]]; then - log_error "$(basename "$file") verlinkt auf '$link', aber Ziel existiert nicht: $target_file" - ((ERRORS++)) - fi - done - - # Relative Links mit ../ extrahieren - grep -o "\[.*\](\.\./[^)]*\.md)" "$file" 2>/dev/null | sed 's/.*(\.\.\///' | sed 's/).*//' | while read link; do - [[ -z "$link" ]] && continue - - dir=$(dirname "$file") - target_file="$dir/../$link" - target_file=$(realpath -m "$target_file" 2>/dev/null || echo "$target_file") - - if [[ ! -f "$target_file" ]]; then - log_error "$(basename "$file") verlinkt auf '../$link', aber Ziel existiert nicht: $target_file" - ((ERRORS++)) - fi - done - - log_success "$(basename "$file") - Markdown-Links validiert" - done -} - -# 3. YAML-Metadaten Validierung -validate_yaml_metadata() { - log_info "Validiere YAML-Metadaten-Konsistenz..." - - find "$GUIDELINES_DIR" -name "*.md" -not -path "*/_archived/*" -not -name "README.md" -not -name "master-guideline.md" | while read file; do - # YAML-Header extrahieren (nur zwischen den ersten beiden --- Zeilen) - yaml_content=$(awk '/^---$/{if(++count==2) exit} count==1 && !/^---$/{print}' "$file" 2>/dev/null || echo "") - - if [[ -z "$yaml_content" ]]; then - log_warning "'$(basename "$file")' hat keinen YAML-Header" - ((WARNINGS++)) + if is_external(target): + continue + if target.startswith("#"): continue - fi - # YAML-Syntax prüfen (falls python verfügbar) - if command -v python3 &> /dev/null; then - echo "$yaml_content" | python3 -c "import yaml,sys; yaml.safe_load(sys.stdin)" 2>/dev/null || { - log_error "'$(basename "$file")' hat ungültige YAML-Syntax im Header" - ((ERRORS++)) - continue - } - fi + # drop angle brackets <...> used in markdown for urls with spaces + if target.startswith("<") and target.endswith(">"): + target = target[1:-1] - # Erforderliche Felder prüfen - required_fields=("guideline_type" "scope" "audience" "last_updated" "ai_context") - for field in "${required_fields[@]}"; do - if ! echo "$yaml_content" | grep -q "^$field:" 2>/dev/null; then - log_error "'$(basename "$file")' fehlt erforderliches YAML-Feld: $field" - ((ERRORS++)) - fi - done + target = unquote(strip_fragment_and_query(target)) - # Dependencies validieren (nur im vollständigen Modus) - if [[ "$QUICK_MODE" = false ]]; then - deps=$(echo "$yaml_content" | grep "dependencies:" 2>/dev/null | sed 's/.*\[//' | sed 's/\].*//' | tr ',' '\n' | sed 's/[" ]//g' || echo "") - for dep in $deps; do - [[ -z "$dep" ]] && continue - dep_file="$GUIDELINES_DIR/$dep" - if [[ ! -f "$dep_file" ]]; then - log_error "'$(basename "$file")' dependency '$dep' existiert nicht" - ((ERRORS++)) - fi - done - fi + # ignore absolute paths in the repo (we treat them as doc-style links; validate only if relative) + if target.startswith("/"): + continue - log_success "$(basename "$file") - Metadaten validiert" - done -} + # ignore non-file targets (e.g. empty or protocol-less anchors) + if ":" in target.split("/", 1)[0]: + # things like "vscode:..." etc. + continue -# 4. Template-Struktur Validierung -validate_template_structure() { - if [[ "$QUICK_MODE" = true ]]; then - log_info "Überspringe Template-Validierung (Quick-Modus)" - return - fi + # treat as file path relative to markdown file + resolved = (f.parent / target).resolve() - log_info "Validiere Template-Struktur-Konsistenz..." + # keep validation within repo + try: + resolved.relative_to(root.resolve()) + except ValueError: + print(f"[ERROR] Link zeigt außerhalb des Repos: {f} -> {target}") + errors += 1 + continue - local template_dir="$GUIDELINES_DIR/_templates" - if [[ ! -d "$template_dir" ]]; then - log_warning "Template-Verzeichnis nicht gefunden: $template_dir" - ((WARNINGS++)) - return - fi + # allow directories if they contain README.md + if resolved.is_dir(): + if not (resolved / "README.md").is_file(): + print(f"[ERROR] Verlinktes Verzeichnis ohne README.md: {f} -> {target}") + errors += 1 + continue - # Prüfe ob neue Guidelines Template-Struktur folgen - find "$GUIDELINES_DIR" -name "*.md" -not -path "*/_archived/*" -not -path "*/_templates/*" -not -name "README.md" | while read file; do - # Prüfe grundlegende Template-Struktur - if ! grep -q "^guideline_type:" "$file" 2>/dev/null; then - log_warning "'$(basename "$file")' folgt möglicherweise nicht der Template-Struktur (fehlt guideline_type)" - ((WARNINGS++)) - fi + if not resolved.exists(): + print(f"[ERROR] Broken link: {f} -> {target}") + errors += 1 - if ! grep -q "^ai_context:" "$file" 2>/dev/null; then - log_warning "'$(basename "$file")' folgt möglicherweise nicht der Template-Struktur (fehlt ai_context)" - ((WARNINGS++)) - fi - done +if errors: + print(f"[ERROR] Link-Validierung fehlgeschlagen: {errors} Fehler") + sys.exit(1) - log_success "Template-Struktur validiert" -} - -# Hauptvalidierung ausführen -main() { - validate_cross_references - validate_markdown_links - validate_yaml_metadata - validate_template_structure - - echo "" - echo "==================================================" - echo "📊 Validierungs-Ergebnisse:" - echo " Fehler: $ERRORS" - echo " Warnungen: $WARNINGS" - - if [[ $ERRORS -eq 0 && $WARNINGS -eq 0 ]]; then - log_success "Alle Validierungen erfolgreich! 🎉" - exit 0 - elif [[ $ERRORS -eq 0 ]]; then - log_warning "Validierung abgeschlossen mit $WARNINGS Warnungen" - exit 0 - else - log_error "Validierung fehlgeschlagen mit $ERRORS Fehlern und $WARNINGS Warnungen" - exit 1 - fi -} - -# Script ausführen -main "$@" +print(f"[OK] Link-Validierung erfolgreich: {len(md_files)} Markdown-Dateien geprüft") +PY diff --git a/README.md b/README.md index 6c10b639..caf5ed05 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ docker compose -f docker-compose.yaml up -d # ./gradlew bootRun ``` -**Vollständige Anleitung**: [docs/how-to/start-local.md](docs/how-to/start-local.md) +**Vollständige Anleitung**: [docs/02_Onboarding/Development/start-local.md](docs/02_Onboarding/Development/start-local.md) --- @@ -57,26 +57,11 @@ Die Hauptdokumentation befindet sich in der **YouTrack Wissensdatenbank**: #### Im Repository - [📖 docs/README.md](docs/README.md) - Übersicht aller Repository-Dokumentation -- [🏛️ Architecture Decision Records](docs/adr) -- [📐 C4-Diagramme](docs/c4) -- [🛠️ Developer Guides](docs/how-to) -- [📑 Projekt-Guidelines (Master)](.junie/guidelines/master-guideline.md) - -Zusätzliche zentrale Guidelines: - -- [Coding Standards](.junie/guidelines/project-standards/coding-standards.md) -- [Testing Standards](.junie/guidelines/project-standards/testing-standards.md) -- [Documentation Standards](.junie/guidelines/project-standards/documentation-standards.md) -- [Architecture Principles](.junie/guidelines/project-standards/architecture-principles.md) -- [Web App Guideline](.junie/guidelines/technology-guides/web-app-guideline.md) -- Docker Guides: - - [Docker Overview](.junie/guidelines/technology-guides/docker/docker-overview.md) - - [Docker Architecture](.junie/guidelines/technology-guides/docker/docker-architecture.md) - - [Docker Development](.junie/guidelines/technology-guides/docker/docker-development.md) - - [Docker Production](.junie/guidelines/technology-guides/docker/docker-production.md) - - [Docker Monitoring](.junie/guidelines/technology-guides/docker/docker-monitoring.md) - - [Docker Troubleshooting](.junie/guidelines/technology-guides/docker/docker-troubleshooting.md) -- Process Guide: [Trace Bullet](.junie/guidelines/process-guides/trace-bullet-guideline.md) +- [🏛️ Architecture Decision Records](docs/01_Architecture/adr/) +- [📐 C4-Diagramme](docs/01_Architecture/c4/) +- [🛠️ Developer Guides](docs/02_Onboarding/Development/) +- [🤖 KI Operating Model](docs/03_Agents/) +- [🧰 Tooling/Guardrails](.junie/README.md) --- @@ -98,7 +83,7 @@ Das System ist in unabhängige Domänen aufgeteilt: - **Polyglot Persistence**: PostgreSQL + Redis - **Container-First**: Docker & Docker Compose -**Details**: [ADR-0002 Domain-Driven Design](docs/adr/0002-domain-driven-design-de.md) +**Details**: [ADR-0002 Domain-Driven Design](docs/01_Architecture/adr/0002-domain-driven-design-de.md) --- @@ -372,7 +357,7 @@ make docker-compose-gen # Generiert Docker Compose Files make docker-validate # Validiert Docker SSoT Konsistenz ``` -**Vollständige Referenz:** [Docker Development Guide](.junie/guidelines/technology-guides/docker/docker-development.md#-vollständige-makefile-referenz) +**Vollständige Referenz:** Siehe `Makefile` (`make help`) und `docs/02_Onboarding/Development/start-local.md`. ### Was ist die Single Source of Truth? @@ -436,7 +421,7 @@ DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development ## 🤝 Contributing -Bitte lies [docs/how-to/branchschutz-und-pr-workflow.md](docs/how-to/branchschutz-und-pr-workflow.md) für den +Bitte lies [docs/02_Onboarding/Development/branchschutz-und-pr-workflow.md](docs/02_Onboarding/Development/branchschutz-und-pr-workflow.md) für den PR-Workflow. --- diff --git a/docs/ARCHITECTURE.md b/docs/01_Architecture/ARCHITECTURE.md similarity index 100% rename from docs/ARCHITECTURE.md rename to docs/01_Architecture/ARCHITECTURE.md diff --git a/docs/adr/0000-adr-template-de.md b/docs/01_Architecture/adr/0000-adr-template-de.md similarity index 100% rename from docs/adr/0000-adr-template-de.md rename to docs/01_Architecture/adr/0000-adr-template-de.md diff --git a/docs/adr/0001-modular-architecture-de.md b/docs/01_Architecture/adr/0001-modular-architecture-de.md similarity index 100% rename from docs/adr/0001-modular-architecture-de.md rename to docs/01_Architecture/adr/0001-modular-architecture-de.md diff --git a/docs/adr/0002-domain-driven-design-de.md b/docs/01_Architecture/adr/0002-domain-driven-design-de.md similarity index 100% rename from docs/adr/0002-domain-driven-design-de.md rename to docs/01_Architecture/adr/0002-domain-driven-design-de.md diff --git a/docs/adr/0003-microservices-architecture-de.md b/docs/01_Architecture/adr/0003-microservices-architecture-de.md similarity index 100% rename from docs/adr/0003-microservices-architecture-de.md rename to docs/01_Architecture/adr/0003-microservices-architecture-de.md diff --git a/docs/adr/0004-event-driven-communication-de.md b/docs/01_Architecture/adr/0004-event-driven-communication-de.md similarity index 100% rename from docs/adr/0004-event-driven-communication-de.md rename to docs/01_Architecture/adr/0004-event-driven-communication-de.md diff --git a/docs/adr/0005-polyglot-persistence-de.md b/docs/01_Architecture/adr/0005-polyglot-persistence-de.md similarity index 100% rename from docs/adr/0005-polyglot-persistence-de.md rename to docs/01_Architecture/adr/0005-polyglot-persistence-de.md diff --git a/docs/adr/0006-authentication-authorization-keycloak-de.md b/docs/01_Architecture/adr/0006-authentication-authorization-keycloak-de.md similarity index 100% rename from docs/adr/0006-authentication-authorization-keycloak-de.md rename to docs/01_Architecture/adr/0006-authentication-authorization-keycloak-de.md diff --git a/docs/adr/0007-api-gateway-pattern-de.md b/docs/01_Architecture/adr/0007-api-gateway-pattern-de.md similarity index 100% rename from docs/adr/0007-api-gateway-pattern-de.md rename to docs/01_Architecture/adr/0007-api-gateway-pattern-de.md diff --git a/docs/adr/0008-multiplatform-client-applications-de.md b/docs/01_Architecture/adr/0008-multiplatform-client-applications-de.md similarity index 100% rename from docs/adr/0008-multiplatform-client-applications-de.md rename to docs/01_Architecture/adr/0008-multiplatform-client-applications-de.md diff --git a/docs/adr/0009-final-kmp-architecture.md b/docs/01_Architecture/adr/0009-final-kmp-architecture.md similarity index 100% rename from docs/adr/0009-final-kmp-architecture.md rename to docs/01_Architecture/adr/0009-final-kmp-architecture.md diff --git a/docs/adr/README.md b/docs/01_Architecture/adr/README.md similarity index 100% rename from docs/adr/README.md rename to docs/01_Architecture/adr/README.md diff --git a/docs/c4/01-context-de.puml b/docs/01_Architecture/c4/01-context-de.puml similarity index 100% rename from docs/c4/01-context-de.puml rename to docs/01_Architecture/c4/01-context-de.puml diff --git a/docs/c4/02-container-de.puml b/docs/01_Architecture/c4/02-container-de.puml similarity index 100% rename from docs/c4/02-container-de.puml rename to docs/01_Architecture/c4/02-container-de.puml diff --git a/docs/c4/03-component-events-service-de.puml b/docs/01_Architecture/c4/03-component-events-service-de.puml similarity index 100% rename from docs/c4/03-component-events-service-de.puml rename to docs/01_Architecture/c4/03-component-events-service-de.puml diff --git a/docs/c4/Kernentitäten.puml b/docs/01_Architecture/c4/Kernentitäten.puml similarity index 100% rename from docs/c4/Kernentitäten.puml rename to docs/01_Architecture/c4/Kernentitäten.puml diff --git a/docs/how-to/branchschutz-und-pr-workflow.md b/docs/02_Onboarding/Development/branchschutz-und-pr-workflow.md similarity index 100% rename from docs/how-to/branchschutz-und-pr-workflow.md rename to docs/02_Onboarding/Development/branchschutz-und-pr-workflow.md diff --git a/docs/how-to/kdoc-style.md b/docs/02_Onboarding/Development/kdoc-style.md similarity index 100% rename from docs/how-to/kdoc-style.md rename to docs/02_Onboarding/Development/kdoc-style.md diff --git a/docs/how-to/start-local.md b/docs/02_Onboarding/Development/start-local.md similarity index 100% rename from docs/how-to/start-local.md rename to docs/02_Onboarding/Development/start-local.md diff --git a/docs/03_Agents/Playbooks/Curator.md b/docs/03_Agents/Playbooks/Curator.md new file mode 100644 index 00000000..982325b8 --- /dev/null +++ b/docs/03_Agents/Playbooks/Curator.md @@ -0,0 +1,19 @@ +# Playbook: Documentation & Knowledge Curator + +## Zweck +Der Curator sorgt dafür, dass Wissen **auffindbar, konsistent und versioniert** bleibt. Er ist die „letzte Rolle“ jeder Session. + +## Kernregeln +* `docs/` ist die **Wahrheit**. +* Jede Session endet mit **genau einem** Artefakt (ADR/Reference/How-to/Journal). +* Links/Verweise setzen (auf relevante Code-Stellen, Dateien, ADRs). + +## Ablauf (leichtgewichtig) +1. Thema der Session in 1 Satz festhalten. +2. Ergebnis-Typ wählen (welches Artefakt passt?). +3. Artefakt erstellen/aktualisieren. +4. Offene Fragen in den passenden „Parking Lot“ übernehmen. +5. Optional: kurzes Journal-Update, wenn das Artefakt nicht selbsterklärend ist. + +## Parking Lots +* Technisch/Architektur: `docs/01_Architecture/questions.md` (falls benötigt) diff --git a/docs/03_Agents/Playbooks/Gemini.md b/docs/03_Agents/Playbooks/Gemini.md new file mode 100644 index 00000000..8b587af3 --- /dev/null +++ b/docs/03_Agents/Playbooks/Gemini.md @@ -0,0 +1,21 @@ +# Playbook: Gemini (parallel/extern) + +## Zweck +Gemini wird genutzt für **Konzeptarbeit**: Varianten vergleichen, Argumente/Trade-offs schärfen, Formulierungen für ADRs/Doku liefern, Review von Entwürfen. + +## Startpunkt +1. `docs/README.md` +2. `docs/03_Agents/README.md` (Artefakt-Vertrag) +3. Je nach Thema: Architektur (`docs/01_Architecture/`), Backend (`docs/04_Backend/`), Frontend (`docs/05_Frontend/`), Infrastruktur (`docs/06_Infrastructure/`) + +## Do +* Immer 2–4 Optionen mit Vor-/Nachteilen liefern. +* Offene Fragen explizit als Liste zurückgeben. +* Formuliere Outputs so, dass sie **direkt** in ein `docs/*` Artefakt übernommen werden können. + +## Don’t +* Keine Annahmen als Fakten verkaufen. +* Keine Repo-spezifischen Behauptungen ohne Quelle (Dateipfad/Link). + +## Abschluss (Pflicht) +Der Output wird durch den `Curator` als genau **ein** Artefakt in `docs/` verankert (ADR/Reference/How-to/Journal). diff --git a/docs/03_Agents/Playbooks/Junie.md b/docs/03_Agents/Playbooks/Junie.md new file mode 100644 index 00000000..f1a32af9 --- /dev/null +++ b/docs/03_Agents/Playbooks/Junie.md @@ -0,0 +1,21 @@ +# Playbook: Junie (IDE) + +## Zweck +Junie wird genutzt für **Repo-nahe Arbeit**: Code lesen, reale Pfade/Module finden, konkrete Änderungen vorschlagen und umsetzen. + +## Startpunkt +1. `docs/README.md` +2. Relevanter Bereich (z.B. `docs/01_Architecture/`, `docs/04_Backend/`, `docs/05_Frontend/`) +3. Bei Rollen/Prozessfragen: `docs/03_Agents/README.md` + +## Do +* Immer mit **konkreten Dateipfaden** arbeiten. +* Bei Unklarheit: gezielte Rückfragen stellen und Annahmen explizit machen. +* Änderungen so klein wie möglich halten und den passenden Doku-Output erzeugen. + +## Don’t +* Keine „zweite Wahrheit“ in `.junie/guidelines/*` etablieren. +* Keine Entscheidungen „im Chat verlieren“ – am Ende muss ein Artefakt in `docs/` stehen. + +## Abschluss (Pflicht) +Am Ende der Session genau **ein** Artefakt gemäß `docs/03_Agents/README.md` erzeugen (oder aktualisieren). diff --git a/docs/03_Agents/README.md b/docs/03_Agents/README.md new file mode 100644 index 00000000..126f03d0 --- /dev/null +++ b/docs/03_Agents/README.md @@ -0,0 +1,34 @@ +# Agent Operating Model (AOM) + +Dieses Verzeichnis definiert, **wie** KI-Unterstützung im Projekt eingesetzt wird: +Rollen/Playbooks, Ablageorte und der minimale Prozess, damit Wissen nicht verloren geht. + +## Governance (Konfliktregel) + +* **Single Source of Truth:** `docs/` +* **Tooling/Automatisierung:** `.junie/` (Scripts, Checks, optional Archiv – keine zweite „Wahrheit“) +* **Personas-Übersicht:** `AGENTS.md` (Repo-Root) + +Wenn Aussagen in `.junie/*` und `docs/*` widersprechen, gilt **`docs/*`**. + +## Artefakt-Vertrag (Anti-Wissensverlust) + +Jede KI-Session endet mit **genau einem** Artefakt in `docs/`: + +1. **ADR** (`docs/01_Architecture/adr/`) – Entscheidung/Optionen/Trade-offs (Status `proposed` ist erlaubt) +2. **Reference** (passender Bereich) – Fakten/Ist-Zustand/Inventar +3. **How-to / Runbook** (passender Bereich) – konkrete Schritte (Setup/Betrieb/Recovery) +4. **Journal Entry** (`docs/99_Journal/`) – Kurzprotokoll, wenn nichts „fertig“ wird + +## Tool-Rollen (keine Doppelarbeit) + +* **Junie (IDE-nah):** Code/Repo-Wahrheit (Dateien, konkrete Implementierung, Refactors) +* **Gemini (parallel/extern):** Variantenraum (Optionen, Argumentation, Formulierungen, Gegenentwurf) + +„Wahr“ wird es erst, wenn es im passenden `docs/*` Artefakt verankert ist. + +## Playbooks + +* `Playbooks/Junie.md` +* `Playbooks/Gemini.md` +* `Playbooks/Curator.md` diff --git a/docs/04_Backend/Services/ping-service.md b/docs/04_Backend/Services/ping-service.md new file mode 100644 index 00000000..6dfe9027 --- /dev/null +++ b/docs/04_Backend/Services/ping-service.md @@ -0,0 +1,13 @@ +# Ping-Service + +Diese Seite beschreibt den **aktuellen technischen Stand** des `Ping-Service`. +Sie ist der **stabile Einstiegspunkt** ("technische Wahrheit") für diesen Service. + +## Einstieg + +* Implementierungs-Report (Historie/Detailanalyse): `docs/90_Reports/Ping-Service_Impl_01-2026.md` + +## Ablage-Regel (pro System) + +* Pro Service gibt es eine stabile Datei unter `docs/04_Backend/Services/`. +* Zeitlich datierte Analysen/Status-Reports liegen unter `docs/90_Reports/`. diff --git a/docs/reference/ports-and-urls.md b/docs/06_Infrastructure/Reference/ports-and-urls.md similarity index 100% rename from docs/reference/ports-and-urls.md rename to docs/06_Infrastructure/Reference/ports-and-urls.md diff --git a/docs/Analyse_Build-Tooling-Integrität_01-2026.md b/docs/90_Reports/Analyse_Build-Tooling-Integrität_01-2026.md similarity index 100% rename from docs/Analyse_Build-Tooling-Integrität_01-2026.md rename to docs/90_Reports/Analyse_Build-Tooling-Integrität_01-2026.md diff --git a/docs/ArchitektonischeEvaluierungImplementierungsstrategieOffline-FähigkeitKMP_Web-Desktop_SQLDelight_2-2-1_01-2026.md b/docs/90_Reports/ArchitektonischeEvaluierungImplementierungsstrategieOffline-FähigkeitKMP_Web-Desktop_SQLDelight_2-2-1_01-2026.md similarity index 100% rename from docs/ArchitektonischeEvaluierungImplementierungsstrategieOffline-FähigkeitKMP_Web-Desktop_SQLDelight_2-2-1_01-2026.md rename to docs/90_Reports/ArchitektonischeEvaluierungImplementierungsstrategieOffline-FähigkeitKMP_Web-Desktop_SQLDelight_2-2-1_01-2026.md diff --git a/docs/Backend_Status_Report_01-2026.md b/docs/90_Reports/Backend_Status_Report_01-2026.md similarity index 100% rename from docs/Backend_Status_Report_01-2026.md rename to docs/90_Reports/Backend_Status_Report_01-2026.md diff --git a/docs/Frontend_Status_Report_01-2026.md b/docs/90_Reports/Frontend_Status_Report_01-2026.md similarity index 100% rename from docs/Frontend_Status_Report_01-2026.md rename to docs/90_Reports/Frontend_Status_Report_01-2026.md diff --git a/docs/Kompatibilitätsanalyse_01-2026.md b/docs/90_Reports/Kompatibilitätsanalyse_01-2026.md similarity index 100% rename from docs/Kompatibilitätsanalyse_01-2026.md rename to docs/90_Reports/Kompatibilitätsanalyse_01-2026.md diff --git a/docs/Ping-Service_Impl_01-2026.md b/docs/90_Reports/Ping-Service_Impl_01-2026.md similarity index 100% rename from docs/Ping-Service_Impl_01-2026.md rename to docs/90_Reports/Ping-Service_Impl_01-2026.md diff --git a/docs/RoomJetpackAndroidDevelopers.md b/docs/90_Reports/Research/RoomJetpackAndroidDevelopers.md similarity index 100% rename from docs/RoomJetpackAndroidDevelopers.md rename to docs/90_Reports/Research/RoomJetpackAndroidDevelopers.md diff --git a/docs/Technischer_Kompatibilitäs-Architektur_KMP-2-3-0_Ökosystem.md b/docs/90_Reports/Technischer_Kompatibilitäs-Architektur_KMP-2-3-0_Ökosystem.md similarity index 100% rename from docs/Technischer_Kompatibilitäs-Architektur_KMP-2-3-0_Ökosystem.md rename to docs/90_Reports/Technischer_Kompatibilitäs-Architektur_KMP-2-3-0_Ökosystem.md diff --git a/docs/99_Journal/2026-01.md b/docs/99_Journal/2026-01.md new file mode 100644 index 00000000..299fdafd --- /dev/null +++ b/docs/99_Journal/2026-01.md @@ -0,0 +1,10 @@ +# Journal 2026-01 + +## Vorlage + +### YYYY-MM-DD – Thema +* **Kontext:** … +* **Rollen genutzt:** … +* **Ergebnis:** … (Link auf ADR/Note/How-to/Reference) +* **Offen:** … (Link auf `docs/00_Domain/questions.md` oder andere Parking Lots) +* **Next:** … diff --git a/docs/99_Journal/README.md b/docs/99_Journal/README.md new file mode 100644 index 00000000..df7df0a6 --- /dev/null +++ b/docs/99_Journal/README.md @@ -0,0 +1,13 @@ +# Journal + +Kurze Session-Protokolle, damit Entscheidungen/Erkenntnisse nicht „im Chat“ verloren gehen. + +## Regeln + +* Pro Session 5–15 Zeilen. +* Linke auf relevante Artefakte (ADR/Domain Note/How-to/Reference) und – wenn sinnvoll – auf Code-Pfade. +* Wenn eine Session keine klare Entscheidung erzeugt: trotzdem ein Journal-Eintrag. + +## Dateien + +* `2026-01.md` (Monatsjournal) diff --git a/docs/README.md b/docs/README.md index b0b8f55a..b99c4095 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,14 +6,14 @@ Die Dokumentation wird nach dem **"Docs-as-Code"**-Prinzip gepflegt: Sie liegt n ## Struktur der Dokumentation -* **/01_Architecture**: Enthält **Architecture Decision Records (ADRs)**. Jede wichtige Architekturentscheidung (z.B. "Warum nutzen wir ein API-Gateway?") wird hier in einer eigenen Datei festgehalten. -* **/02_Onboarding**: Anleitungen für den schnellen Einstieg in das Projekt. Enthält `Getting_Started.md` für das lokale Setup. -* **/03_Agents**: Definitionen und spezifische Anleitungen für die im Projekt eingesetzten KI-Agenten. - * `AGENTS.md`: Definiert die Rollen, Verantwortlichkeiten und Regeln für jeden Agenten. - * `Gemini/`, `Junie/`: Ablageorte für finalisierte Berichte und Analysen der jeweiligen KI-Assistenten. -* **/04_Backend**: Dokumentation, die sich speziell auf die Backend-Services bezieht. -* **/05_Frontend**: Dokumentation für das KMP-Frontend ("Meldestelle Portal"). -* **/06_Infrastructure**: Anleitungen und Konfigurationsdetails zur Infrastruktur (Docker, Keycloak, Consul, etc.). +* **/01_Architecture**: Architektur (ADRs, C4/Diagramme, Architektur-Referenzen). +* **/02_Onboarding**: Einstieg & Entwickler-Workflow (lokales Setup, PR-Workflow, Style-Guides). +* **/03_Agents**: Agent Operating Model (AOM) + Playbooks für Junie/Gemini und weitere KI-Unterstützungen. +* **/04_Backend**: Backend-spezifische Dokumentation (Services, Datenmodelle, Integrationen). +* **/05_Frontend**: Frontend-spezifische Dokumentation (KMP/Compose, Offline/Synchronisierung). +* **/06_Infrastructure**: Betrieb & Infrastruktur (Docker, Keycloak, Observability, Ports/URLs, Runbooks). +* **/90_Reports**: Berichte/Analysen/Status-Reports (zeitlich geordnet, nicht zwingend „verbindliche Regeln“). +* **/99_Journal**: Kurzprotokolle pro Session (Anti-Wissensverlust, Nachvollziehbarkeit). ## Wie man diese Dokumentation pflegt @@ -24,3 +24,12 @@ Jeder Entwickler und jeder KI-Agent ist dafür verantwortlich, die Dokumentation * **Bei Änderungen am Setup:** Passe die Anleitungen im `Onboarding`- oder `Infrastructure`-Verzeichnis an. Änderungen an der Dokumentation sollten Teil derselben Pull Request/Commit sein wie die zugehörigen Code-Änderungen. + +### Wichtigste Einstiege + +* Agenten/Arbeitsmodus: `docs/03_Agents/` +* Lokales Setup/Workflow: `docs/02_Onboarding/` +* Architekturentscheidungen: `docs/01_Architecture/adr/` +* Backend (pro Service): `docs/04_Backend/Services/` +* Ping-Service (Startpunkt): `docs/04_Backend/Services/ping-service.md` +* Ping-Service Implementierungs-Report (Historie): `docs/90_Reports/Ping-Service_Impl_01-2026.md`