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

tooling: make .junie/.gemini docs-first (remove legacy guidelines)

Browse Source
This commit is contained in:
Stefan Mogeritsch
2026-01-13 14:32:49 +01:00
parent 696c2e0bd8
commit ff0e1a36cc
66 changed files with 347 additions and 8923 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gemini/README.md
+35
View File
@@ -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`
.junie/AUTOMATION-FEATURES.md
-410
View File
@@ -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.
.junie/IMPLEMENTATION-REPORT.md
-348
View File
@@ -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**
.junie/OPTIMIZATION-SUMMARY.md
-171
View File
@@ -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.
.junie/README.md
+21
View File
@@ -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).
.junie/guidelines/README.md
-172
View File
@@ -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.
.junie/guidelines/_archived/docker-guideline-v3.0.1-archived-2025-09-15.md
-2445
View File
File diff suppressed because it is too large Load Diff
.junie/guidelines/_meta/cross-refs.json
-217
View File
@@ -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"
]
}
}
}
.junie/guidelines/_meta/versions.json
-143
View File
@@ -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"
}
}
}
.junie/guidelines/_templates/process-guide-template.md
-165
View File
@@ -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]
.junie/guidelines/_templates/project-standard-template.md
-92
View File
@@ -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]
.junie/guidelines/_templates/technology-guideline-template.md
-117
View File
@@ -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.
.junie/guidelines/master-guideline.md
-98
View File
@@ -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
.junie/guidelines/process-guides/trace-bullet-guideline.md
-141
View File
@@ -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
.junie/guidelines/project-standards/architecture-principles.md
-509
View File
@@ -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<MemberResponse> {
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<Member, BusinessError> {
// 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<Member, ValidationError> {
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<Unit, RepositoryError> {
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<Member?, RepositoryError> {
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<Member?, RepositoryError>
suspend fun save(member: Member): Result<Unit, RepositoryError>
suspend fun findByEmail(email: Email): Result<Member?, RepositoryError>
suspend fun findByLicenseNumber(licenseNumber: LicenseNumber): Result<Member?, RepositoryError>
suspend fun findAll(pageable: Pageable): Result<Page<Member>, 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<MemberListUiState> = _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<Member> = 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<TournamentRegistration> = mutableListOf()
) {
companion object {
fun create(
name: String,
startDate: LocalDate,
endDate: LocalDate,
maxParticipants: Int
): Result<Tournament, ValidationError> {
// 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<TournamentRegistrationCreatedEvent, BusinessError> {
// 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<MemberResponse>
```
## 🚀 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
.junie/guidelines/project-standards/coding-standards.md
-220
View File
@@ -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<MemberId, ValidationError> =
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<EntityId, ValidationError> =
runCatching { UUID.fromString(value) }
.map { EntityId(it) }
.mapError { ValidationError.INVALID_UUID }
}
}
```
#### Error-Handling mit Result
```kotlin
interface EntityRepository {
suspend fun findById(id: EntityId): Result<Entity?, RepositoryError>
suspend fun save(entity: Entity): Result<Unit, RepositoryError>
}
// 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<Unit, ProcessingError> {
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
.junie/guidelines/project-standards/documentation-standards.md
-349
View File
@@ -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<Boolean, ValidationError> {
// 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<T>(
private val redisClient: RedisClient,
private val ttl: Duration = Duration.ofHours(1)
) : Cache<T> {
override suspend fun get(key: String): T? {
// Use Redis GET command with automatic deserialization
return redisClient.get(key)?.let {
jsonMapper.readValue(it, typeRef<T>())
}
}
}
```
### 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
.junie/guidelines/project-standards/testing-standards.md
-385
View File
@@ -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<MemberRepository>()
private val eventPublisher = mockk<EventPublisher>()
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<Result.Success<Unit>>()
verify { memberRepository.save(any()) }
verify { eventPublisher.publish(ofType<MemberCreatedEvent>()) }
}
@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<Result.Failure<RepositoryError>>()
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<Result.Success<Unit>>()
assertThat(findResult).isInstanceOf<Result.Success<Member?>>()
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<Nothing>("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<Result.Success<Unit>>()
assertThat(retrieveResult).isInstanceOf<Result.Success<List<DomainEvent>>>()
val events = (retrieveResult as Result.Success).value
assertThat(events).hasSize(1)
assertThat(events.first()).isInstanceOf<MemberCreatedEvent>()
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<Nothing>("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<Result.Success<ExpectedType>>()
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<Result.Failure<ExpectedError>>()
assertThat((result as Result.Failure).error).isEqualTo(ExpectedError.SOME_ERROR)
}
```
### Mock-Setup für Services
```kotlin
class ServiceTest {
private val repository = mockk<Repository>()
private val eventPublisher = mockk<EventPublisher>()
private val externalService = mockk<ExternalService>()
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
.junie/guidelines/technology-guides/docker/docker-architecture.md
-255
View File
@@ -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 <service-name>
# Versionen aktualisieren
./scripts/docker-versions-update.sh show
./scripts/docker-versions-update.sh update <component> <version>
# Services neu starten
docker-compose restart <service-name>
```
### 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
.junie/guidelines/technology-guides/docker/docker-development.md
-756
View File
@@ -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=<service-name>
# 3. Container neu starten
docker compose restart <service-name>
# 4. Image neu bauen (ohne Cache)
make build-service SERVICE=<service-name>
docker compose up -d <service-name>
```
#### Port-Konflikte
```bash
# Ports prüfen
lsof -i :<port>
# oder
netstat -tulpn | grep :<port>
# 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=<service-name>
# 3. Manueller Health-Check
curl -v http://localhost:<port>/actuator/health
# 4. Container-Netzwerk prüfen
docker network inspect meldestelle-network
# 5. Service neu starten
docker compose restart <service-name>
```
#### 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=<service-name>
# 4. Manuell im Container debuggen
make shell SERVICE=<service-name>
./gradlew --version
./gradlew dependencies
```
#### Service ist erreichbar, antwortet aber nicht
```bash
# 1. Service-Logs in Echtzeit
make logs SERVICE=<service-name>
# 2. JVM-Status prüfen (bei Java-Services)
make shell SERVICE=<service-name>
ps aux | grep java
# 3. Speicher/CPU prüfen
docker stats <container-name>
# 4. Netzwerk-Verbindung testen
docker compose exec <service> 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=<name>` → Logs prüfen
- `make shell SERVICE=<name>` → Interactive Debugging
2. **Häufige Fehlerquellen:**
- Fehlende `.env` Datei → `make env-dev`
- Port-Konflikte → `lsof -i :<port>`
- 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=<betroffener-service>
# 3. Shell im Container öffnen (falls nötig)
make shell SERVICE=<betroffener-service>
# 4. Fix implementieren und Service neu bauen
make build-service SERVICE=<betroffener-service>
docker compose restart <betroffener-service>
# 5. Fix verifizieren
curl http://localhost:<port>/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
.junie/guidelines/technology-guides/docker/docker-monitoring.md
-257
View File
@@ -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:<port>/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 <service-name>
# Error-Logs filtern
docker-compose logs <service-name> | 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 <token>" \
http://localhost:3000/api/dashboards/uid/<dashboard-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
.junie/guidelines/technology-guides/docker/docker-overview.md
-74
View File
@@ -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.
.junie/guidelines/technology-guides/docker/docker-production.md
-230
View File
@@ -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 <image>` | 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
.junie/guidelines/technology-guides/docker/docker-troubleshooting.md
-304
View File
@@ -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>` | Port-Nutzung prüfen |
| Service startet nicht | `docker-compose logs <service>` | Service-Logs anzeigen |
| Container hängt | `docker stats` | Ressourcenverbrauch |
| DNS-Probleme | `docker-compose exec <service> nslookup <target>` | DNS-Resolution testen |
| Disk voll | `docker system prune -a --volumes` | Cleanup durchführen |
### Debug-Workflows
#### Service startet nicht
1. `docker-compose ps` - Status prüfen
2. `docker-compose logs <service>` - Logs analysieren
3. `docker-compose exec <service> sh` - Container inspizieren
4. Health-Check-Endpoint testen
#### Performance-Probleme
1. `docker stats` - Ressourcenverbrauch
2. `docker-compose top` - Prozess-Übersicht
3. JVM-Parameter optimieren
4. Resource-Limits anpassen
#### Netzwerk-Probleme
1. `docker network ls` - Netzwerke auflisten
2. `docker-compose exec <service> ping <target>` - Connectivity testen
3. Consul Service-Discovery prüfen
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 <component> <version>`
> - **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
.junie/guidelines/technology-guides/web-app-guideline.md
-216
View File
@@ -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
.junie/scripts/check-docs-drift.sh
Regular → Executable
+28 -28
View File
@@ -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
.junie/scripts/create-guideline.sh
-308
View File
@@ -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 "$@"
.junie/scripts/pre-commit-guidelines.sh
-174
View File
@@ -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 <script-name>"
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
.junie/scripts/validate-links.sh
+91 -292
View File
@@ -1,54 +1,16 @@
#!/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)
@@ -57,287 +19,124 @@ while [[ $# -gt 0 ]]; do
;;
--help|-h)
cat << 'EOF'
Meldestelle Guidelines Link-Validierung
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
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
if is_external(target):
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++))
if target.startswith("#"):
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
# drop angle brackets <...> used in markdown for urls with spaces
if target.startswith("<") and target.endswith(">"):
target = target[1:-1]
done < "$temp_refs"
target = unquote(strip_fragment_and_query(target))
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++))
# ignore absolute paths in the repo (we treat them as doc-style links; validate only if relative)
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++))
# ignore non-file targets (e.g. empty or protocol-less anchors)
if ":" in target.split("/", 1)[0]:
# things like "vscode:..." etc.
continue
}
fi
# 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
# treat as file path relative to markdown file
resolved = (f.parent / target).resolve()
# 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
# 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
log_success "$(basename "$file") - Metadaten validiert"
done
}
# 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
# 4. Template-Struktur Validierung
validate_template_structure() {
if [[ "$QUICK_MODE" = true ]]; then
log_info "Überspringe Template-Validierung (Quick-Modus)"
return
fi
if not resolved.exists():
print(f"[ERROR] Broken link: {f} -> {target}")
errors += 1
log_info "Validiere Template-Struktur-Konsistenz..."
if errors:
print(f"[ERROR] Link-Validierung fehlgeschlagen: {errors} Fehler")
sys.exit(1)
local template_dir="$GUIDELINES_DIR/_templates"
if [[ ! -d "$template_dir" ]]; then
log_warning "Template-Verzeichnis nicht gefunden: $template_dir"
((WARNINGS++))
return
fi
# 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 ! 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
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
README.md
+9 -24
View File
@@ -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.
---
docs/ARCHITECTURE.md → docs/01_Architecture/ARCHITECTURE.md
View File
docs/adr/0000-adr-template-de.md → docs/01_Architecture/adr/0000-adr-template-de.md
View File
docs/adr/0001-modular-architecture-de.md → docs/01_Architecture/adr/0001-modular-architecture-de.md
View File
docs/adr/0002-domain-driven-design-de.md → docs/01_Architecture/adr/0002-domain-driven-design-de.md
View File
docs/adr/0003-microservices-architecture-de.md → docs/01_Architecture/adr/0003-microservices-architecture-de.md
View File
docs/adr/0004-event-driven-communication-de.md → docs/01_Architecture/adr/0004-event-driven-communication-de.md
View File
docs/adr/0005-polyglot-persistence-de.md → docs/01_Architecture/adr/0005-polyglot-persistence-de.md
View File
docs/adr/0006-authentication-authorization-keycloak-de.md → docs/01_Architecture/adr/0006-authentication-authorization-keycloak-de.md
View File
docs/adr/0007-api-gateway-pattern-de.md → docs/01_Architecture/adr/0007-api-gateway-pattern-de.md
View File
docs/adr/0008-multiplatform-client-applications-de.md → docs/01_Architecture/adr/0008-multiplatform-client-applications-de.md
View File
docs/adr/0009-final-kmp-architecture.md → docs/01_Architecture/adr/0009-final-kmp-architecture.md
View File
docs/adr/README.md → docs/01_Architecture/adr/README.md
View File
docs/c4/01-context-de.puml → docs/01_Architecture/c4/01-context-de.puml
View File
docs/c4/02-container-de.puml → docs/01_Architecture/c4/02-container-de.puml
View File
docs/c4/03-component-events-service-de.puml → docs/01_Architecture/c4/03-component-events-service-de.puml
View File
docs/c4/Kernentitäten.puml → docs/01_Architecture/c4/Kernentitäten.puml
View File
docs/how-to/branchschutz-und-pr-workflow.md → docs/02_Onboarding/Development/branchschutz-und-pr-workflow.md
View File
docs/how-to/kdoc-style.md → docs/02_Onboarding/Development/kdoc-style.md
View File
docs/how-to/start-local.md → docs/02_Onboarding/Development/start-local.md
View File
docs/03_Agents/Playbooks/Curator.md
+19
View File
@@ -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)
docs/03_Agents/Playbooks/Gemini.md
+21
View File
@@ -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).
docs/03_Agents/Playbooks/Junie.md
+21
View File
@@ -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).
docs/03_Agents/README.md
+34
View File
@@ -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`
docs/04_Backend/Services/ping-service.md
+13
View File
@@ -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/`.
docs/reference/ports-and-urls.md → docs/06_Infrastructure/Reference/ports-and-urls.md
View File
docs/Analyse_Build-Tooling-Integrität_01-2026.md → docs/90_Reports/Analyse_Build-Tooling-Integrität_01-2026.md
View File
docs/ArchitektonischeEvaluierungImplementierungsstrategieOffline-FähigkeitKMP_Web-Desktop_SQLDelight_2-2-1_01-2026.md → docs/90_Reports/ArchitektonischeEvaluierungImplementierungsstrategieOffline-FähigkeitKMP_Web-Desktop_SQLDelight_2-2-1_01-2026.md
View File
docs/Backend_Status_Report_01-2026.md → docs/90_Reports/Backend_Status_Report_01-2026.md
View File
docs/Frontend_Status_Report_01-2026.md → docs/90_Reports/Frontend_Status_Report_01-2026.md
View File
docs/Kompatibilitätsanalyse_01-2026.md → docs/90_Reports/Kompatibilitätsanalyse_01-2026.md
View File
docs/Ping-Service_Impl_01-2026.md → docs/90_Reports/Ping-Service_Impl_01-2026.md
View File
docs/RoomJetpackAndroidDevelopers.md → docs/90_Reports/Research/RoomJetpackAndroidDevelopers.md
View File
docs/Technischer_Kompatibilitäs-Architektur_KMP-2-3-0_Ökosystem.md → docs/90_Reports/Technischer_Kompatibilitäs-Architektur_KMP-2-3-0_Ökosystem.md
View File
docs/99_Journal/2026-01.md
+10
View File
@@ -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:** …
docs/99_Journal/README.md
+13
View File
@@ -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)
docs/README.md
+17 -8
View File
@@ -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`