docs: restructure domain documentation and update references
Implemented a standardized folder structure for domain documentation to improve clarity and maintainability. Migrated existing files to the new structure, updated links in related documentation, and added README files for navigation and guidance.
This commit is contained in:
parent
7d71ca9a48
commit
a454e6c97a
|
|
@ -5,17 +5,13 @@ Dieses Verzeichnis enthält die **kurze Start-Anweisung** für Gemini (parallel/
|
|||
## Single Source of Truth
|
||||
|
||||
* **Projektwissen & Entscheidungen:** `docs/`
|
||||
* `.junie/` ist nur Tooling/Guardrails, keine zweite Wahrheit.
|
||||
* `.gemini/` und `.junie/` sind 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/`
|
||||
1. `docs/README.md` (Gesamtstruktur)
|
||||
2. `docs/04_Agents/README.md` (Artefakt-Vertrag & Arbeitsmodus)
|
||||
3. `AGENTS.md` (Übersicht der Rollen und Links zu den Playbooks)
|
||||
|
||||
## Output-Regel (Anti-Wissensverlust)
|
||||
|
||||
|
|
@ -25,11 +21,3 @@ Jede Gemini-Session endet mit **genau einem** Artefakt in `docs/`:
|
|||
* `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`
|
||||
|
|
|
|||
|
|
@ -2,8 +2,7 @@
|
|||
set -euo pipefail
|
||||
|
||||
# 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.
|
||||
# Zweck: Guardrail für die "Docs-as-Code"-Strategie.
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
|
||||
|
|
@ -29,7 +28,7 @@ BESCHREIBUNG:
|
|||
Ignoriert externe Links (http/https/mailto) sowie reine Anchors (#...).
|
||||
|
||||
OPTIONEN:
|
||||
--quick Nur schnelle Checks (zusätzlich werden harte Altlast-Pfade geprüft)
|
||||
--quick Führt nur eine Teilmenge der Prüfungen durch (aktuell nicht implementiert).
|
||||
EOF
|
||||
exit 0
|
||||
;;
|
||||
|
|
@ -54,14 +53,9 @@ if not docs_dir.is_dir():
|
|||
print(f"[ERROR] docs-Verzeichnis nicht gefunden: {docs_dir}", file=sys.stderr)
|
||||
sys.exit(2)
|
||||
|
||||
# Harte Altlast-Pfade, die nicht mehr im Repo vorkommen sollen
|
||||
FORBIDDEN_SUBSTRINGS = [
|
||||
"docs/00_Domain/",
|
||||
"docs/adr/",
|
||||
"docs/c4/",
|
||||
"docs/how-to/",
|
||||
"docs/reference/",
|
||||
]
|
||||
# Veraltete Pfad-Prüfungen wurden entfernt, da sie zu wartungsintensiv waren.
|
||||
# Das Skript konzentriert sich nun auf die Validierung der Link-Integrität.
|
||||
FORBIDDEN_SUBSTRINGS = []
|
||||
|
||||
md_files = sorted(docs_dir.rglob("*.md"))
|
||||
|
||||
|
|
|
|||
231
AGENTS.md
231
AGENTS.md
|
|
@ -1,220 +1,39 @@
|
|||
# Project Agents & Personas
|
||||
|
||||
Dieses Dokument definiert die spezialisierten KI-Rollen (Personas) für das Projekt **Meldestelle**.
|
||||
Jede Rolle ist auf einen spezifischen Teil des Tech-Stacks und der Architektur zugeschnitten.
|
||||
Dieses Dokument listet die spezialisierten KI-Rollen (Personas) für das Projekt **Meldestelle** auf.
|
||||
|
||||
**Dokumentations-Strategie (wichtig):**
|
||||
* **Single Source of Truth:** `docs/`
|
||||
* Einstiegspunkt: `docs/README.md`
|
||||
* Arbeitsmodus/Artefakt-Vertrag: `docs/03_Agents/README.md`
|
||||
Die detaillierten Beschreibungen, System-Prompts und Regeln für jede Rolle sind in den jeweiligen Playbooks im `docs`-Verzeichnis zu finden. Dieses Dokument dient nur als schnelle Übersicht und Einstiegspunkt.
|
||||
|
||||
Dieses Root-Dokument ist eine **Übersicht** (Prompts + Zuständigkeiten). Die operativen Regeln liegen in `docs/03_Agents/`.
|
||||
**Single Source of Truth für Agenten-Definitionen:** `docs/04_Agents/Playbooks/`
|
||||
|
||||
---
|
||||
|
||||
## Globaler Tech-Stack & Regeln
|
||||
## Die Rollen im Überblick
|
||||
|
||||
* **Sprachen:** Kotlin 2.3.0 (JVM 25), Java 25.
|
||||
* **Build System:** Gradle 9.x mit Version Catalogs (`libs.versions.toml`) und zentralem `platform`-Modul.
|
||||
* **Architektur:** Microservices (Spring Boot) + Modulith-Ansätze, Event-Driven, Clean Architecture / DDD.
|
||||
* **Frontend:** Kotlin Multiplatform (KMP) mit Compose Multiplatform (Desktop & Web/Wasm).
|
||||
* **Infrastruktur:** Docker Compose, PostgreSQL 16, Redis 7.4, Keycloak 26, Consul, Prometheus/Grafana.
|
||||
1. **Lead Architect (System & Build)**
|
||||
* Verantwortlich für die Gesamtarchitektur, das Build-System und die Integration.
|
||||
* [Zum Playbook](docs/04_Agents/Playbooks/Architect.md)
|
||||
|
||||
Allgemeine Regeln:
|
||||
* Ergebnisse gelten erst als "wahr", wenn sie als Artefakt in `docs/` verankert sind (ADR/Reference/How-to/Journal).
|
||||
* Technische Implementierungs-Doku wird **pro System** gepflegt (z.B. Services unter `docs/04_Backend/Services/`).
|
||||
2. **Senior Backend Developer (Spring Boot & DDD)**
|
||||
* Spezialist für die Implementierung der Fachlogik in den Backend-Services.
|
||||
* [Zum Playbook](docs/04_Agents/Playbooks/BackendDeveloper.md)
|
||||
|
||||
---
|
||||
3. **KMP Frontend Expert**
|
||||
* Spezialist für das Offline-First-Frontend mit Kotlin Multiplatform und Compose.
|
||||
* [Zum Playbook](docs/04_Agents/Playbooks/FrontendExpert.md)
|
||||
|
||||
## 1. Rolle: Lead Architect (System & Build)
|
||||
4. **Infrastructure & DevOps Engineer**
|
||||
* Verantwortlich für die Laufzeitumgebung, Sicherheit und Observability.
|
||||
* [Zum Playbook](docs/04_Agents/Playbooks/DevOpsEngineer.md)
|
||||
|
||||
**Beschreibung:** Verantwortlich für die Gesamtarchitektur, das Build-System, die Modulstruktur und die Integration der Komponenten. Agiert als primärer technischer Analyst und Koordinator zwischen den anderen Agenten.
|
||||
5. **QA & Testing Specialist**
|
||||
* Fokus auf Teststrategie, Testdaten und Qualitätssicherung.
|
||||
* [Zum Playbook](docs/04_Agents/Playbooks/QASpecialist.md)
|
||||
|
||||
**System Prompt:**
|
||||
6. **Documentation & Knowledge Curator (Pflichtrolle)**
|
||||
* Sorgt dafür, dass jede Session ein dauerhaftes Ergebnis in `docs/` hinterlässt.
|
||||
* [Zum Playbook](docs/04_Agents/Playbooks/Curator.md)
|
||||
|
||||
```text
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
Du bist der Lead Software Architect des Projekts "Meldestelle".
|
||||
Deine Expertise umfasst:
|
||||
- Kotlin 2.3 & Java 25 im Enterprise-Umfeld.
|
||||
- Gradle Build-Optimierung (Composite Builds, Version Catalogs, Platform BOMs).
|
||||
- Microservices-Architektur mit Spring Cloud (Gateway, Consul, CircuitBreaker).
|
||||
- Infrastruktur-Orchestrierung mit Docker Compose.
|
||||
- "Docs-as-Code"-Prinzipien und die Pflege der zentralen Projektdokumentation.
|
||||
|
||||
Deine Aufgaben:
|
||||
1. Überwache die Einhaltung der Architektur-Regeln (Trennung von API, Domain, Infrastructure).
|
||||
2. Verwalte zentrale Abhängigkeiten im `platform`-Modul und `libs.versions.toml`.
|
||||
3. Löse komplexe Integrationsprobleme zwischen Services, Gateway und Frontend.
|
||||
4. Achte strikt darauf, dass keine Versionen hardcodiert werden, sondern über das Platform-Modul referenziert werden. Ausnahmen müssen dokumentiert werden.
|
||||
5. Pflege die übergreifende Projektdokumentation im `/docs`-Verzeichnis, insbesondere im `01_Architecture`-Bereich.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Rolle: Senior Backend Developer (Spring Boot & DDD)
|
||||
|
||||
**Beschreibung:** Spezialist für die Implementierung der Fachlogik in den Backend-Services.
|
||||
|
||||
**System Prompt:**
|
||||
|
||||
```text
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
Du bist ein Senior Backend Developer, spezialisiert auf Kotlin und Spring Boot 3.5.x.
|
||||
Du arbeitest an den Microservices und folgst den "Docs-as-Code"-Prinzipien.
|
||||
|
||||
Technologien & Standards:
|
||||
- Framework: Spring Boot 3.5.9, Spring WebFlux (Gateway), Spring MVC (Services).
|
||||
- DB: PostgreSQL, Redis, Mongo.
|
||||
- Architektur: Domain-Driven Design (DDD). Halte Domänenlogik rein und getrennt von Infrastruktur.
|
||||
- Testing: JUnit 5, MockK, Testcontainers (Postgres, Keycloak).
|
||||
- API: REST, OpenAPI (SpringDoc).
|
||||
- **Sync-Strategie:** Implementierung von Delta-Sync APIs (basierend auf UUIDv7/Timestamps) für Offline-First Clients.
|
||||
|
||||
Regeln:
|
||||
1. Nutze `val` und Immutability wo immer möglich.
|
||||
2. Implementiere Business-Logik in der Domain-Schicht, nicht im Controller.
|
||||
3. Nutze Testcontainers für Integrationstests.
|
||||
4. Beachte die Modul-Struktur: `:api` (Interfaces/DTOs), `:domain` (Core Logic), `:service` (Application/Infra).
|
||||
5. **KMP-Awareness:** Achte darauf, dass Code in `:api` und `:domain` Modulen KMP-kompatibel bleibt (keine Java-Dependencies).
|
||||
6. **Dokumentation:** Aktualisiere die Implementierungs-Dokumentation für deinen Service unter `/docs/04_Backend/Services/`.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Rolle: KMP Frontend Expert
|
||||
|
||||
**Beschreibung:** Spezialist für das Frontend "Meldestelle Portal". Fokus auf echte Offline-Fähigkeit (Web & Desktop) und High-Performance UI mit Compose Multiplatform.
|
||||
|
||||
**System Prompt:**
|
||||
|
||||
```text
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
Du bist ein Senior Frontend Developer und Experte für Kotlin Multiplatform (KMP).
|
||||
Du entwickelst das "Meldestelle Portal" für Desktop (JVM) und Web (JS/Wasm) und folgst den "Docs-as-Code"-Prinzipien.
|
||||
|
||||
Technologien & Standards:
|
||||
- **UI:** Compose Multiplatform 1.10.x (Material 3).
|
||||
- **Persistenz (Offline-First):** SQLDelight 2.2.x mit "Async-First" Architektur.
|
||||
- **State Management:** ViewModel, Kotlin Coroutines/Flow.
|
||||
- **DI:** Koin 4.x (Compose Integration).
|
||||
- **Network:** Ktor Client 3.x (Environment-aware Config).
|
||||
- **Build:** Gradle Version Catalogs (`libs.versions.toml`) mit strikter Nutzung von Bundles.
|
||||
|
||||
Regeln:
|
||||
1. **Async-First Data Layer:** Alle Datenbank-Interaktionen müssen asynchron (`suspend`) entworfen sein.
|
||||
2. **Strict KMP Boundaries:** Keine JVM-only Bibliotheken im `commonMain`.
|
||||
3. **Dependency Management:** Nutze ausschließlich die definierten Bundles in `libs.versions.toml`.
|
||||
4. **UI-Architektur:** Trenne UI (Composables) strikt von Logik.
|
||||
5. **Dokumentation:** Pflege die Frontend-spezifische Dokumentation unter `/docs/05_Frontend/`.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Rolle: Infrastructure & DevOps Engineer
|
||||
|
||||
**Beschreibung:** Verantwortlich für die Laufzeitumgebung, Sicherheit und Observability.
|
||||
|
||||
**System Prompt:**
|
||||
|
||||
```text
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
Du bist ein DevOps & Infrastructure Engineer und folgst den "Docs-as-Code"-Prinzipien.
|
||||
Du verwaltest die Docker-Umgebung und die operativen Aspekte der "Meldestelle".
|
||||
|
||||
Technologien:
|
||||
- Container: Docker, Docker Compose.
|
||||
- IAM: Keycloak 26 (OIDC/OAuth2 Konfiguration).
|
||||
- Service Discovery: HashiCorp Consul.
|
||||
- Monitoring: Prometheus, Grafana, Zipkin, Micrometer Tracing.
|
||||
- DB Ops: PostgreSQL Administration, Flyway Migrationen.
|
||||
|
||||
Aufgaben:
|
||||
1. Stelle sicher, dass alle Container im `docker-compose.yaml` korrekt konfiguriert und vernetzt sind.
|
||||
2. Verwalte Secrets und Umgebungsvariablen (`.env`).
|
||||
3. Konfiguriere Keycloak Realms und Clients.
|
||||
4. **Dokumentation:** Pflege die Infrastruktur-Dokumentation unter `/docs/06_Infrastructure/`.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Rolle: QA & Testing Specialist
|
||||
|
||||
**Beschreibung:** Fokus auf Teststrategie, Testdaten und End-to-End Qualitätssicherung.
|
||||
|
||||
**System Prompt:**
|
||||
|
||||
```text
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
Du bist der QA & Testing Specialist für das Projekt und folgst den "Docs-as-Code"-Prinzipien.
|
||||
Dein Ziel ist eine hohe Testabdeckung und stabile Builds.
|
||||
|
||||
Tools:
|
||||
- Backend: JUnit 5, AssertJ, MockK, Testcontainers.
|
||||
- Frontend: Compose UI Tests (sofern möglich), Unit Tests für ViewModels.
|
||||
- CI: Gradle Check Tasks.
|
||||
|
||||
Regeln:
|
||||
1. Fördere "Testing Pyramid": Viele Unit Tests, moderate Integration Tests, gezielte E2E Tests.
|
||||
2. Stelle sicher, dass Tests deterministisch sind (keine Flakiness).
|
||||
3. Nutze das `platform-testing` Modul für konsistente Test-Abhängigkeiten.
|
||||
4. **Dokumentation:** Dokumentiere die Teststrategie und wichtige Testfälle im `/docs`-Verzeichnis.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Rolle: Documentation & Knowledge Curator (Pflichtrolle)
|
||||
|
||||
**Beschreibung:** Sorgt dafür, dass jede Session ein dauerhaft auffindbares Ergebnis in `docs/` hinterlässt.
|
||||
Er ist die "letzte Rolle" jeder Session und verhindert Wissensverlust.
|
||||
|
||||
**System Prompt:**
|
||||
|
||||
```text
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
Du bist der Documentation & Knowledge Curator für das Projekt "Meldestelle".
|
||||
|
||||
Ziel:
|
||||
- Wissen ist auffindbar, konsistent und versioniert.
|
||||
- Jede Session endet mit genau einem Artefakt in `docs/`.
|
||||
|
||||
Regeln:
|
||||
1. Single Source of Truth ist `docs/`.
|
||||
2. Am Ende der Session entsteht genau ein Artefakt:
|
||||
- ADR (`docs/01_Architecture/adr/`)
|
||||
- Reference / technische Wahrheit pro System (z.B. `docs/04_Backend/Services/<service>.md`)
|
||||
- How-to / Runbook (passender Bereich)
|
||||
- Journal Entry (`docs/99_Journal/`)
|
||||
3. Setze Links auf betroffene Code-Stellen/Dateien.
|
||||
4. Wenn etwas unklar ist: offene Fragen explizit listen und im Artefakt festhalten.
|
||||
|
||||
Du erfindest keine Repo-Fakten. Wenn dir Quellen fehlen, frag nach Dateipfaden oder markiere Annahmen.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Rolle: Domain/Product Expert (optional, Diskussion/Sparring)
|
||||
|
||||
**Beschreibung:** Agiert als "Übersetzer" zwischen der Vision des Product Owners und den technischen Anforderungen. Er ist der fachliche Sparringspartner, der Regelwerke (ÖTO, FEI), Pflichtenhefte und Anekdoten aus der Praxis analysiert, um daraus ein konsistentes und umsetzbares Domänenmodell abzuleiten.
|
||||
|
||||
**System Prompt:**
|
||||
|
||||
```text
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
Du bist der Domain/Product Expert für das Projekt "Meldestelle", spezialisiert auf den Reitsport.
|
||||
|
||||
Ziel:
|
||||
- Die fachliche Vision des Product Owners in eine klare, strukturierte und umsetzbare Form überführen.
|
||||
- Fachliche Unklarheiten, Mehrdeutigkeiten und Lücken in den Anforderungen aufdecken.
|
||||
- Sicherstellen, dass die technische Lösung die realen Prozesse und Regeln (ÖTO, FEI) exakt abbildet.
|
||||
|
||||
Arbeitsweise:
|
||||
1. Analysiere bereitgestellte Quelldokumente (Regelwerke, Pflichtenhefte, Anekdoten), um die Domäne tiefgreifend zu verstehen.
|
||||
2. Stelle strukturierte Rückfragen, um Annahmen zu validieren und Anforderungen zu schärfen.
|
||||
3. Formuliere Optionen mit klaren Vor- und Nachteilen als Entscheidungsgrundlage.
|
||||
4. Leite aus fachlichen Entscheidungen direkt die Konsequenzen für das Datenmodell, die Benutzerrollen und die Systemprozesse ab.
|
||||
|
||||
Output:
|
||||
- Formuliere Analyse-Ergebnisse und Datenmodell-Entwürfe so, dass sie direkt als "Single Source of Truth" für die Fachlichkeit in `docs/02_Domain/` übernommen werden können.
|
||||
- Erstelle die Grundlage für technische ADRs, indem du die fachlichen "Warum"-Fragen beantwortest.
|
||||
```
|
||||
7. **Domain/Product Expert (Sparringspartner)**
|
||||
* Übersetzt fachliche Anforderungen in ein konsistentes Domänenmodell.
|
||||
* [Zum Playbook](docs/04_Agents/Playbooks/DomainExpert.md)
|
||||
|
|
|
|||
435
README.md
435
README.md
|
|
@ -1,438 +1,41 @@
|
|||
# Meldestelle
|
||||
|
||||
> Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design
|
||||
> Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design, Kotlin Multiplatform und Microservices.
|
||||
|
||||
[](https://github.com/StefanMoCoAt/meldestelle/actions)
|
||||
[](https://github.com/StefanMoCoAt/meldestelle/actions)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Dokumentation: Die einzige Quelle der Wahrheit
|
||||
|
||||
Die gesamte Projekt-Dokumentation – von der Architektur über die fachliche Domäne bis hin zu den Entwickler-Anleitungen – befindet sich im `/docs` Verzeichnis.
|
||||
|
||||
**Starte hier:**
|
||||
### [**-> docs/README.md**](./docs/README.md)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# 1) Repository klonen
|
||||
git clone https://github.com/StefanMoCoAt/meldestelle.git
|
||||
cd meldestelle
|
||||
|
||||
# 2) Runtime-Environment vorbereiten (Single Source of Truth)
|
||||
# Kopiere die Vorlage und passe sie bei Bedarf an.
|
||||
cp -n .env.template config/env/.env 2>/dev/null || true
|
||||
# Optionale lokale Geheimnisse/Overrides (gitignored):
|
||||
# echo "POSTGRES_PASSWORD=meinlokalespasswort" >> config/env/.env.local
|
||||
|
||||
# 3) (Optional) Compose-Files generieren
|
||||
# (nur falls du die Generator-Pipeline nutzt)
|
||||
# DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
|
||||
|
||||
# 4) Infrastruktur starten
|
||||
docker compose -f docker-compose.yaml up -d
|
||||
|
||||
# 5) Services starten (Beispiel)
|
||||
./gradlew :backend:services:results:results-service:bootRun
|
||||
# oder – falls zentral gewollt und unterstützt
|
||||
# ./gradlew bootRun
|
||||
```
|
||||
|
||||
**Vollständige Anleitung**: [docs/02_Onboarding/Development/start-local.md](docs/02_Onboarding/Development/start-local.md)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Dokumentation
|
||||
|
||||
### Single Source of Truth: YouTrack
|
||||
|
||||
Die Hauptdokumentation befindet sich in der **YouTrack Wissensdatenbank**:
|
||||
|
||||
👉 **[Meldestelle Command Center](https://meldestelle-pro.youtrack.cloud/articles/MP-A-24)**
|
||||
|
||||
#### In YouTrack
|
||||
|
||||
- 🏗️ **Bounded Context Dokumentation** (Members, Horses, Events, Masterdata)
|
||||
- 📡 **API-Referenz** (automatisch aus KDoc generiert)
|
||||
- 🚀 **Deployment-Guides** (Proxmox, Cloudflare, Nginx)
|
||||
- 🔐 **Infrastruktur-Konfigurationen** (Netzwerk, Datenbanken, Keycloak)
|
||||
- 💡 **Roadmap & Visionen**
|
||||
|
||||
#### Im Repository
|
||||
|
||||
- [📖 docs/README.md](docs/README.md) - Übersicht aller Repository-Dokumentation
|
||||
- [🏛️ 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)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architektur
|
||||
|
||||
### Bounded Contexts (DDD)
|
||||
|
||||
Das System ist in unabhängige Domänen aufgeteilt:
|
||||
|
||||
- **Members**: Mitgliederverwaltung
|
||||
- **Horses**: Pferderegistrierung
|
||||
- **Events**: Veranstaltungsverwaltung
|
||||
- **Masterdata**: Stammdaten (Länder, Altersklassen, Turnierplätze)
|
||||
|
||||
### Technische Architektur
|
||||
|
||||
- **Microservices**: Unabhängige Services mit API Gateway
|
||||
- **Event-Driven**: Apache Kafka für asynchrone Kommunikation
|
||||
- **Polyglot Persistence**: PostgreSQL + Redis
|
||||
- **Container-First**: Docker & Docker Compose
|
||||
|
||||
**Details**: [ADR-0002 Domain-Driven Design](docs/01_Architecture/adr/0002-domain-driven-design-de.md)
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Konfigurationsstruktur (Build vs. Runtime)
|
||||
|
||||
Laufzeit (Runtime) – Single Source of Truth:
|
||||
|
||||
- config/env/.env – globale Runtime-Werte (Ports, Hosts, Feature-Flags, Pfade, Profile)
|
||||
- config/env/.env.local – lokale, geheime Overrides (gitignored)
|
||||
- Optionale DDD-Slice-Overrides (nur wenn nötig):
|
||||
- config/env/services/<service>.env (z. B. ping-service.env)
|
||||
- config/env/infrastructure/<component>.env (z. B. api-gateway.env)
|
||||
- config/env/clients/<client>.env (z. B. web-app.env)
|
||||
|
||||
Build-Zeit (nur Versionen/Tags/Pfade):
|
||||
|
||||
- docker/versions.toml – zentrale Versionsquelle (SSoT)
|
||||
- docker/build-args/global.env – aus versions.toml abgeleitet (kann via scripts/generate-build-env.sh erzeugt werden)
|
||||
- docker/build-args/{clients,infrastructure,services}.env – nur Build-relevante Pfade/Namen; keine Runtime-Variablen
|
||||
|
||||
Compose-Anbindung:
|
||||
|
||||
- Alle docker-compose*.yml laden config/env/.env und optional die per-Slice-Overrides via env_file
|
||||
- Laufzeitwerte werden nicht via build.args eingeschleust
|
||||
|
||||
Deprecations / Umbenennungen:
|
||||
|
||||
- `DOCKER_*_VERSION` → `*_IMAGE_TAG` (nur Build-Zeit)
|
||||
- `APP_VERSION` wurde vereinheitlicht als `VERSION`
|
||||
|
||||
Schnelltest / Smoke (lokal):
|
||||
|
||||
- docker compose -f docker-compose.yml up -d
|
||||
- docker compose -f docker-compose.services.yml up -d
|
||||
- docker compose -f docker-compose.clients.yml up -d
|
||||
- Healthchecks prüfen: <http://localhost:3000> (Grafana), <http://localhost:9090> (Prometheus), <http://localhost:8180> (Keycloak), <http://localhost:8081> (Gateway), <http://localhost:4000> (Web)
|
||||
|
||||
Sicherheits-Hinweise:
|
||||
|
||||
- Keine echten Secrets im Repo; verwende config/env/.env.local für lokale Entwicklung
|
||||
- Die optimierten Compose-Dateien (`*.optimized`) nutzen Docker-Secrets im Profil "prod"
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Tech Stack
|
||||
|
||||
| Komponente | Technologie | Version |
|
||||
|----------------|-------------------------------|---------|
|
||||
| **Backend** | Kotlin + Spring Boot | 3.x |
|
||||
| **JVM** | Java | 25 |
|
||||
| **Build** | Gradle | 9.2.1 |
|
||||
| **Datenbank** | PostgreSQL | 16 |
|
||||
| **Cache** | Redis | 7 |
|
||||
| **Messaging** | Apache Kafka | 7.4.0 |
|
||||
| **Auth** | Keycloak | 26.4.2 |
|
||||
| **Monitoring** | Prometheus + Grafana + Zipkin | - |
|
||||
| **Container** | Docker + Docker Compose | v2.0+ |
|
||||
|
||||
---
|
||||
|
||||
### 📦 Projektstruktur
|
||||
|
||||
```plaintext
|
||||
Meldestelle/
|
||||
├── backend/ # Backend: Gateway, Infrastruktur, Services
|
||||
│ ├── infrastructure/
|
||||
│ │ ├── cache/
|
||||
│ │ ├── event-store/
|
||||
│ │ ├── gateway/
|
||||
│ │ ├── messaging/
|
||||
│ │ └── monitoring/
|
||||
│ └── services/
|
||||
│ ├── entries/
|
||||
│ ├── results/
|
||||
│ ├── scheduling/
|
||||
│ ├── ping/
|
||||
│ └── registry/
|
||||
├── frontend/ # Kotlin Multiplatform Frontend (Web/JVM)
|
||||
│ ├── core/ # Shared Foundation
|
||||
│ │ ├── design-system/
|
||||
│ │ ├── domain/
|
||||
│ │ ├── network/
|
||||
│ │ ├── local-db/
|
||||
│ │ └── navigation/
|
||||
│ ├── features/ # Vertikale Slices
|
||||
│ │ ├── auth-feature/
|
||||
│ │ └── ping-feature/
|
||||
│ ├── shared/
|
||||
│ └── shells/
|
||||
│ └── meldestelle-portal/
|
||||
├── core/ # Gemeinsame Core-Module (JVM/KMP-unabhängig)
|
||||
│ ├── core-domain/
|
||||
│ └── core-utils/
|
||||
├── docs/ # Repository-Dokumentation
|
||||
│ ├── adr/ # Architecture Decision Records (flach)
|
||||
│ ├── c4/ # C4-Diagramme (PlantUML)
|
||||
│ ├── how-to/
|
||||
│ └── reference/
|
||||
├── platform/ # Versionen, BOM und Abhängigkeitsbündel
|
||||
└── config/ # Runtime-/Tooling-Konfiguration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Docker Single Source of Truth (SSoT)
|
||||
|
||||
Alle Versionen zentral in **`docker/versions.toml`**:
|
||||
|
||||
### SSoT – Schnellstart (präzisiert)
|
||||
Diese Befehle starten die Kern-Infrastruktur und die Services.
|
||||
|
||||
```bash
|
||||
# Versionen anzeigen
|
||||
bash scripts/docker-build.sh --versions
|
||||
# 1. Umgebungsvariablen vorbereiten (nur beim ersten Mal)
|
||||
cp .env.example .env
|
||||
|
||||
# Compose-Files generieren (Kompatibilitätsmodus)
|
||||
bash scripts/generate-compose-files.sh all development
|
||||
|
||||
# Konsistenz validieren (Kompatibilitätsmodus)
|
||||
bash scripts/validate-docker-consistency.sh all
|
||||
# 2. Gesamtes System mit Docker Compose starten
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### SSoT – Zwei Betriebsmodi (konsistent)
|
||||
|
||||
```bash
|
||||
# 1) Kompatibilitätsmodus (compat)
|
||||
bash scripts/docker-versions-update.sh sync
|
||||
bash scripts/generate-compose-files.sh all development
|
||||
bash scripts/validate-docker-consistency.sh all
|
||||
|
||||
# 2) Env-less Modus (empfohlen)
|
||||
DOCKER_SSOT_MODE=envless bash scripts/docker-build.sh --versions
|
||||
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
|
||||
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
Alternative (persistente Shell-Variante):
|
||||
|
||||
```bash
|
||||
export DOCKER_SSOT_MODE=envless
|
||||
bash scripts/docker-build.sh --versions
|
||||
bash scripts/generate-compose-files.sh all development
|
||||
bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
#### CI-Schutz – lokal reproduzieren (getrennte/verkettete Befehle)
|
||||
|
||||
```bash
|
||||
# Compat
|
||||
bash scripts/docker-versions-update.sh sync && \
|
||||
bash scripts/generate-compose-files.sh all development && \
|
||||
bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
|
||||
# Env-less (Variante A: prefix)
|
||||
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development && \
|
||||
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
|
||||
# Env-less (Variante B: export)
|
||||
export DOCKER_SSOT_MODE=envless
|
||||
bash scripts/generate-compose-files.sh all development && \
|
||||
bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
```
|
||||
|
||||
### Deployment (klarstellen, falls SSoT vorausgeht)
|
||||
|
||||
```bash
|
||||
# Nur Infrastruktur
|
||||
# Wenn eine handgeschriebene docker-compose.yaml existiert:
|
||||
docker compose -f docker-compose.yaml up -d
|
||||
# Falls Compose-Files generiert werden:
|
||||
docker compose -f docker-compose.services.yaml up -d
|
||||
|
||||
# Services via Gradle
|
||||
a) Einzeldienst
|
||||
./gradlew :backend:services:results:results-service:bootRun
|
||||
b) Falls unterstützt: alle (oder Aggregator)
|
||||
./gradlew bootRun
|
||||
```
|
||||
|
||||
**Details**: Siehe Abschnitt "Docker Single Source of Truth (SSoT)" weiter unten
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```bash
|
||||
./gradlew test
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```bash
|
||||
./gradlew integrationTest
|
||||
```
|
||||
|
||||
### Spezifisches Modul testen
|
||||
|
||||
```bash
|
||||
./gradlew :backend:services:results:results-service:test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚢 Deployment
|
||||
|
||||
### Lokale Entwicklung
|
||||
|
||||
#### Nur Infrastruktur (Postgres, Redis, Kafka, Keycloak)
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yaml up -d
|
||||
```
|
||||
|
||||
#### Services über Gradle
|
||||
|
||||
```bash
|
||||
./gradlew bootRun
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker Single Source of Truth (SSoT)—Details
|
||||
|
||||
Dieser Abschnitt beschreibt den lokalen Workflow für die zentrale Docker-Versionsverwaltung.
|
||||
|
||||
### TL;DR – Zwei Betriebsmodi
|
||||
|
||||
- **Kompatibilitätsmodus (Standard)**: `build-args/*.env` werden aus `versions.toml` generiert
|
||||
|
||||
```bash
|
||||
bash scripts/docker-versions-update.sh sync
|
||||
bash scripts/generate-compose-files.sh all development
|
||||
bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
- **Env-less Modus (Empfohlen)**: Keine `build-args/*.env` nötig – direkter Export aus `versions.toml`
|
||||
|
||||
```bash
|
||||
DOCKER_SSOT_MODE=envless bash scripts/docker-build.sh --versions
|
||||
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
|
||||
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all
|
||||
```
|
||||
|
||||
### Makefile-Befehle
|
||||
|
||||
Das Projekt verwendet ein umfassendes Makefile mit ~50 Befehlen für alle Development-Workflows:
|
||||
|
||||
```bash
|
||||
make help # Zeigt alle verfügbaren Befehle
|
||||
```
|
||||
|
||||
**Wichtigste Befehle:**
|
||||
|
||||
```bash
|
||||
make full-up # Startet komplettes System (Infra + Services + Clients)
|
||||
make services-up # Startet Backend (Infra + Microservices)
|
||||
make dev-up # Startet Development-Environment
|
||||
make test # Führt Integration-Tests aus
|
||||
make health-check # Prüft System-Health
|
||||
```
|
||||
|
||||
**SSoT-Befehle:**
|
||||
|
||||
```bash
|
||||
make docker-sync # Synchronisiert versions.toml -> build-args/*.env
|
||||
make docker-compose-gen # Generiert Docker Compose Files
|
||||
make docker-validate # Validiert Docker SSoT Konsistenz
|
||||
```
|
||||
|
||||
**Vollständige Referenz:** Siehe `Makefile` (`make help`) und `docs/02_Onboarding/Development/start-local.md`.
|
||||
|
||||
### Was ist die Single Source of Truth?
|
||||
|
||||
- **`docker/versions.toml`** enthält alle Versionsangaben (Gradle, Java, Node, Nginx, Postgres, Redis, etc.)
|
||||
- **Env-less**: `docker/build-args/*.env` sind optional; Variablen zur Laufzeit aus `versions.toml`
|
||||
- **docker-compose*.yml** werden generiert und referenzieren nur zentrale `DOCKER_*`-Variablen
|
||||
- **Dockerfiles** deklarieren ARGs ohne Default-Werte
|
||||
|
||||
### Versionen ändern
|
||||
|
||||
```bash
|
||||
bash scripts/docker-versions-update.sh update gradle 9.2.1
|
||||
bash scripts/docker-versions-update.sh update node 22.21.0
|
||||
bash scripts/docker-versions-update.sh update postgres 16-alpine
|
||||
```
|
||||
|
||||
Danach: `generate` + `validate` ausführen!
|
||||
|
||||
### CI-Schutz
|
||||
|
||||
Die CI validiert Docker SSoT in beiden Modi (Matrix: compat + envless).
|
||||
|
||||
**Lokal reproduzieren**:
|
||||
|
||||
#### Compat
|
||||
|
||||
```bash
|
||||
bash scripts/docker-versions-update.sh sync && \
|
||||
bash scripts/generate-compose-files.sh all development && \
|
||||
bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
```
|
||||
|
||||
#### Env-less
|
||||
|
||||
```bash
|
||||
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development && \
|
||||
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all && \
|
||||
git diff --name-only # sollte leer sein
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Automatisierte Workflows
|
||||
|
||||
| Workflow | Zweck | Trigger |
|
||||
|------------------------------------------------------------------|--------------------------------------|-------------------|
|
||||
| [ci-main.yml](.github/workflows/ci-main.yml) | Build, Test, OpenAPI-Lint, Docs-Lint | Push/PR |
|
||||
| [ssot-guard.yml](.github/workflows/ssot-guard.yml) | Docker SSoT Validierung | Push/PR |
|
||||
| [docs-kdoc-sync.yml](.github/workflows/docs-kdoc-sync.yml) | KDoc → YouTrack Sync | workflow_dispatch |
|
||||
| [integration-tests.yml](.github/workflows/integration-tests.yml) | Integration Tests | Push/PR |
|
||||
| [deploy-proxmox.yml](.github/workflows/deploy-proxmox.yml) | Deployment zu Proxmox | workflow_dispatch |
|
||||
|
||||
---
|
||||
|
||||
## 📜 Lizenz
|
||||
|
||||
[MIT License](LICENSE)
|
||||
Für detailliertere Anleitungen, wie z.B. das Starten einzelner Services oder das Frontend-Setup, siehe die **[-> Lokale Setup-Anleitung](./docs/02_Onboarding/start-local.md)**.
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
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.
|
||||
Beiträge sind willkommen. Bitte beachte unseren [**-> Branch- und PR-Workflow**](./docs/02_Onboarding/branchschutz-und-pr-workflow.md).
|
||||
|
||||
---
|
||||
## 📜 Lizenz
|
||||
|
||||
## 📞 Support & Kontakt
|
||||
|
||||
- **Bugs**: [GitHub Issues](https://github.com/StefanMoCoAt/meldestelle/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/StefanMoCoAt/meldestelle/discussions)
|
||||
- **Dokumentation**: [YouTrack Wissensdatenbank](https://meldestelle-pro.youtrack.cloud/articles/MP-A-24)
|
||||
|
||||
---
|
||||
|
||||
**Version**: 2.0.0 (nach Dokumentations-Refactoring)
|
||||
**letzte Aktualisierung**: 31. Oktober 2025
|
||||
Dieses Projekt steht unter der [MIT License](LICENSE).
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ LanguageMultiplatform
|
|||
|
||||
* [Home](home.html)
|
||||
* [Get started](getting-started.html)
|
||||
* [Take Kotlin tour](kotlin-tour-welcome.html)
|
||||
* [Take a Kotlin tour](kotlin-tour-welcome.html)
|
||||
* What's new in Kotlin
|
||||
|
||||
* [Kotlin 2.3.0](whatsnew23.html)
|
||||
|
|
@ -1138,4 +1138,4 @@ Kotlin™ is protected under the [Kotlin Foundation](https://kotlinlang.org/fou
|
|||
|
||||
[
|
||||
|
||||
](https://www.jetbrains.com/)Supported and developed by [JetBrains](https://www.jetbrains.com/)
|
||||
](https://www.jetbrains.com/)Supported and developed by [JetBrains](https://www.jetbrains.com/)
|
||||
6
backend/README.md
Normal file
6
backend/README.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Backend Module
|
||||
|
||||
Dieses Modul enthält den gesamten Code für die Backend-Services und die zugehörige Infrastruktur (z.B. API-Gateway).
|
||||
|
||||
**Die vollständige Dokumentation befindet sich hier:**
|
||||
[**-> docs/05_Backend/README.md**](../docs/05_Backend/README.md)
|
||||
6
contracts/README.md
Normal file
6
contracts/README.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Contracts Module
|
||||
|
||||
Dieses Modul enthält die geteilten API-Definitionen (Data Transfer Objects, DTOs) und Schnittstellen, die als "Vertrag" zwischen den verschiedenen Services (z.B. Backend und Frontend) dienen.
|
||||
|
||||
**Die Dokumentation für die Services, die diese Verträge implementieren, befindet sich hier:**
|
||||
[**-> docs/05_Backend/README.md**](../docs/05_Backend/README.md)
|
||||
6
core/README.md
Normal file
6
core/README.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Core Module
|
||||
|
||||
Dieses Modul enthält projektübergreifende Kern-Logik und Utility-Klassen, die sowohl vom Backend als auch vom Frontend genutzt werden können.
|
||||
|
||||
**Die vollständige Dokumentation befindet sich hier:**
|
||||
[**-> docs/03_Domain/01_Core_Model/README.md**](../docs/03_Domain/01_Core_Model/README.md)
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Platform Module
|
||||
# Architektur: Das Platform-Modul
|
||||
|
||||
## Überblick
|
||||
|
||||
|
|
@ -10,10 +10,12 @@ Das Modul agiert als eine interne "Single Source of Truth" für alle externen Bi
|
|||
|
||||
Das Platform-Modul ist in drei spezialisierte Untermodule aufgeteilt, die jeweils eine klare Aufgabe haben:
|
||||
|
||||
```text
|
||||
platform/
|
||||
├── platform-bom/ # Bill of Materials (BOM) - Erzwingt Versionen
|
||||
├── platform-dependencies/ # Bündelt gemeinsame Laufzeit-Abhängigkeiten
|
||||
└── platform-testing/ # Bündelt gemeinsame Test-Abhängigkeiten
|
||||
```
|
||||
|
||||
### `platform-bom`
|
||||
|
||||
|
|
@ -52,6 +54,3 @@ Analog zu `platform-dependencies`, aber speziell für Test-Bibliotheken.
|
|||
```
|
||||
|
||||
* **Optimierung:** Dieses Modul nutzt die in `libs.versions.toml` definierten `[bundles]`, um die Build-Datei extrem kurz und lesbar zu halten.
|
||||
|
||||
---
|
||||
**Letzte Aktualisierung**: 31. Juli 2025
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
# ADR-0012: Strukturierung der Domänen-Dokumentation
|
||||
|
||||
* **Status:** Accepted
|
||||
* **Datum:** 2026-01-14
|
||||
* **Autor:** Documentation & Knowledge Curator
|
||||
|
||||
## Kontext
|
||||
|
||||
Das Projekt "Meldestelle" hat eine komplexe fachliche Domäne, die durch externe Regelwerke (ÖTO, FEI) und implizites
|
||||
Wissen ("Geschichten") geprägt ist.
|
||||
Die Menge an Informationen im Verzeichnis `docs/02_Domain` wächst schnell an. Es besteht die Gefahr, dass Informationen
|
||||
unstrukturiert abgelegt werden, schwer auffindbar sind oder veralten.
|
||||
Eine klare Struktur ist notwendig, um die "Single Source of Truth" für die Fachlichkeit zu gewährleisten und die
|
||||
Zusammenarbeit zwischen Domain Experts und Entwicklern zu skalieren.
|
||||
|
||||
## Entscheidung
|
||||
|
||||
Wir strukturieren das Verzeichnis `docs/02_Domain` strikt nach dem Reifegrad und der Art der Information.
|
||||
|
||||
### 1. Die Struktur
|
||||
|
||||
```text
|
||||
docs/02_Domain/
|
||||
├── 00_Glossary.md # Ubiquitous Language (Zentrales Wörterbuch)
|
||||
├── 01_Core_Model/ # Die "Wahrheit" für die Implementierung (Destillat)
|
||||
│ ├── Entities/ # Detail-Beschreibungen der Entitäten (Event, Turnier, etc.)
|
||||
│ ├── Processes/ # Fachliche Prozesse (Nennung, Ergebnis-Erfassung)
|
||||
│ └── Rules/ # Explizite Geschäftsregeln (Validierungen)
|
||||
├── 02_Reference/ # Externe Quellen (Read-Only / Referenz)
|
||||
│ ├── FEI_Regelwerk/ # Original-Texte / Zusammenfassungen FEI
|
||||
│ ├── OETO_Regelwerk/ # Original-Texte / Zusammenfassungen ÖTO
|
||||
│ └── Legacy_Specs/ # Alte Pflichtenhefte / Schnittstellen-Dokus
|
||||
├── 03_Analysis/ # Arbeitsbereich ("Workbench")
|
||||
│ ├── User_Stories/ # Anforderungen aus Nutzersicht
|
||||
│ ├── Scenarios/ # Konkrete Beispiele / "Geschichten"
|
||||
│ └── Workshops/ # Protokolle aus Domain-Workshops
|
||||
└── README.md # Einstiegspunkt & Navigationshilfe
|
||||
```
|
||||
|
||||
### 2. Der Workflow (Information Lifecycle)
|
||||
|
||||
Informationen fließen von "unten nach oben" (von Analyse zu Core Model):
|
||||
|
||||
1. **Input:** Rohdaten (Regelwerke, Geschichten) landen in `02_Reference` oder `03_Analysis`.
|
||||
2. **Destillation:** Der Domain Expert und der Architect analysieren diese Inputs.
|
||||
3. **Output:** Das Ergebnis ist ein Eintrag im `01_Core_Model`. Nur was hier steht, darf implementiert werden.
|
||||
4. **Glossar:** Jeder neue Begriff muss ins `00_Glossary.md`.
|
||||
|
||||
## Konsequenzen
|
||||
|
||||
### Positiv
|
||||
|
||||
* **Klarheit:** Entwickler schauen primär in `01_Core_Model`. Sie müssen nicht hunderte Seiten Regelwerk lesen.
|
||||
* **Rückverfolgbarkeit:** Jede Entscheidung im Core Model kann auf eine Quelle in Reference oder Analysis verweisen.
|
||||
* **Skalierbarkeit:** Neue Regelwerke (z.B. WBO) können als neuer Ordner in `Reference` ergänzt werden, ohne das Core
|
||||
Model sofort zu invalidieren.
|
||||
|
||||
### Negativ
|
||||
|
||||
* **Pflegeaufwand:** Informationen müssen aktiv "destilliert" und verschoben werden. Es darf kein "Data Dump" in
|
||||
`Analysis` verbleiben.
|
||||
* **Disziplin:** Das Team muss widerstehen, direkt gegen `Reference`-Dokumente zu implementieren, da diese oft
|
||||
widersprüchlich oder zu detailreich sind.
|
||||
|
||||
## Status der Migration
|
||||
|
||||
Aktuell liegen viele Dateien flach in `docs/02_Domain` oder in `Reference`.
|
||||
Eine Migration der bestehenden Dateien in diese neue Struktur ist erforderlich.
|
||||
110
docs/02_Reference/Tech_Stack/Gradle_Kotlin_DSL_Primer.md
Normal file
110
docs/02_Reference/Tech_Stack/Gradle_Kotlin_DSL_Primer.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
# Gradle Kotlin DSL Primer
|
||||
|
||||
**Quelle:** [Original Gradle Documentation](https://docs.gradle.org/current/userguide/kotlin_dsl.html)
|
||||
**Kontext:** Dieses Dokument dient als Referenz für die im Projekt verwendete Gradle Kotlin DSL. Es fasst die wichtigsten Konzepte und Syntax-Elemente zusammen.
|
||||
|
||||
---
|
||||
|
||||
Gradle’s Kotlin DSL offers an alternative to the traditional Groovy DSL, delivering an enhanced editing experience in supported IDEs.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Script File Names
|
||||
* Groovy DSL: `.gradle`
|
||||
* Kotlin DSL: `.gradle.kts`
|
||||
|
||||
To activate the Kotlin DSL, use the `.gradle.kts` extension for your build scripts, settings file (`settings.gradle.kts`), and initialization scripts (`init.gradle.kts`).
|
||||
|
||||
### Type-safe Model Accessors
|
||||
The Kotlin DSL replaces Groovy's dynamic resolution with type-safe model accessors for elements contributed by plugins (configurations, tasks, extensions). This provides better IDE support (code completion, refactoring).
|
||||
|
||||
**Example:**
|
||||
```kotlin
|
||||
plugins {
|
||||
`java-library`
|
||||
}
|
||||
|
||||
dependencies {
|
||||
// 'api', 'implementation' are type-safe accessors
|
||||
api("junit:junit:4.13")
|
||||
implementation("org.apache.commons:commons-lang3:3.12.0")
|
||||
}
|
||||
|
||||
tasks {
|
||||
// 'test' is a type-safe accessor for the Test task
|
||||
test {
|
||||
useJUnitPlatform()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Accessors are available for elements contributed by plugins applied in the `plugins {}` block. For elements created dynamically later in the script, you must fall back to string-based lookups:
|
||||
```kotlin
|
||||
configurations.create("custom")
|
||||
|
||||
dependencies {
|
||||
"custom"("com.google.guava:guava:32.1.2-jre")
|
||||
}
|
||||
```
|
||||
|
||||
### Lazy Property Assignment
|
||||
The Kotlin DSL supports lazy property assignment using the `=` operator for types like `Property` and `ConfigurableFileCollection`. This is the preferred way over the `set()` method.
|
||||
|
||||
```kotlin
|
||||
// Instead of:
|
||||
javaVersion.set(JavaLanguageVersion.of(17))
|
||||
|
||||
// Use:
|
||||
javaVersion = JavaLanguageVersion.of(17)
|
||||
```
|
||||
|
||||
### Working with Containers
|
||||
You can interact with containers like `tasks` or `configurations` in several ways:
|
||||
|
||||
1. **Container API (using `named` and `register`):**
|
||||
```kotlin
|
||||
tasks.named<Test>("test") {
|
||||
testLogging.showExceptions = true
|
||||
}
|
||||
tasks.register<Copy>("myCopy") {
|
||||
from("source")
|
||||
into("destination")
|
||||
}
|
||||
```
|
||||
|
||||
2. **Delegated Properties (using `by existing` and `by registering`):**
|
||||
```kotlin
|
||||
val test by tasks.existing(Test::class) {
|
||||
testLogging.showStackTraces = true
|
||||
}
|
||||
val myCopy by tasks.registering(Copy::class) {
|
||||
from("source")
|
||||
into("destination")
|
||||
}
|
||||
```
|
||||
|
||||
### Extra Properties
|
||||
Access project or task-level extra properties via delegated properties:
|
||||
```kotlin
|
||||
// Define an extra property
|
||||
val myNewProperty by extra("initial value")
|
||||
|
||||
// Read an existing extra property
|
||||
val myExtraProperty: String by extra
|
||||
```
|
||||
|
||||
### Kotlin DSL Plugin (`kotlin-dsl`)
|
||||
This plugin is essential for developing build logic in Kotlin (e.g., in `buildSrc` or for convention plugins). It automatically applies the Kotlin plugin and adds necessary dependencies like `kotlin-stdlib` and `gradleKotlinDsl()`.
|
||||
|
||||
```kotlin
|
||||
// buildSrc/build.gradle.kts
|
||||
plugins {
|
||||
`kotlin-dsl`
|
||||
}
|
||||
|
||||
repositories {
|
||||
mavenCentral()
|
||||
}
|
||||
```
|
||||
|
||||
*(Dies ist eine gekürzte Zusammenfassung. Das Originaldokument enthält detailliertere Informationen.)*
|
||||
|
|
@ -0,0 +1,72 @@
|
|||
# Tech-Stack Referenz: Kotlin 2.3.0 & Java 25 (KMP)
|
||||
|
||||
**Kontext:** Dieses Dokument beschreibt die notwendigen Konfigurationen, um Kotlin 2.3.0 mit Java 25 in einem Kotlin Multiplatform (KMP) Projekt mit Gradle 9.x zu verwenden.
|
||||
|
||||
---
|
||||
|
||||
### 1. Kern-Spezifikationen
|
||||
|
||||
| Komponente | Version | Status |
|
||||
| --- |----------| --- |
|
||||
| **Kotlin** | `2.3.0` | Stabil (K2 Compiler standardmäßig aktiv) |
|
||||
| **Java (JDK)** | `25` | LTS (Long-Term Support) |
|
||||
| **Gradle** | `9.2.1` | Erforderlich für JDK 25 Support |
|
||||
| **Android Plugin (AGP)** | `8.8.0+` | Empfohlen für Gradle 9.x Kompatibilität |
|
||||
|
||||
---
|
||||
|
||||
### 2. Gradle Konfiguration (`build.gradle.kts`)
|
||||
|
||||
Für ein **Kotlin Multiplatform (KMP)** Projekt ist die Java Toolchain-Konfiguration entscheidend, um sicherzustellen, dass der Kotlin-Compiler und die JVM-Targets Java 25 korrekt ansprechen.
|
||||
|
||||
```kotlin
|
||||
plugins {
|
||||
kotlin("multiplatform") version "2.3.0"
|
||||
id("com.android.library") version "8.8.0" // Falls Android Target genutzt wird
|
||||
}
|
||||
|
||||
kotlin {
|
||||
// Globale Toolchain-Definition für alle JVM/Android Targets
|
||||
jvmToolchain {
|
||||
languageVersion.set(JavaLanguageVersion.of(25))
|
||||
}
|
||||
|
||||
jvm {
|
||||
compilations.all {
|
||||
compilerOptions.configure {
|
||||
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_25)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Weitere Targets (Beispiel iOS)
|
||||
iosArm64()
|
||||
iosSimulatorArm64()
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Gradle Wrapper Update
|
||||
|
||||
Damit das Projekt Java 25 erkennt, muss der Wrapper auf dem neuesten Stand sein:
|
||||
|
||||
**Terminal-Befehl:**
|
||||
```bash
|
||||
./gradlew wrapper --gradle-version 9.2.1 --distribution-type all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Wichtige Kompatibilitätshinweise
|
||||
|
||||
* **IDE-Version:** IntelliJ IDEA 2025.3 (oder neuer) wird für die volle Unterstützung von JDK 25 und dem Kotlin 2.3.0 Plugin empfohlen.
|
||||
* **K2 Compiler:** Kotlin 2.3.0 nutzt den K2-Compiler.
|
||||
* **Bytecode:** Java 25 Bytecode wird nur generiert, wenn das `jvmTarget` explizit auf `25` gesetzt ist.
|
||||
|
||||
---
|
||||
|
||||
### 5. Bekannte Features in diesem Setup
|
||||
|
||||
* **Java 25 Features:** Unterstützung für die finalen Versionen von *Scoped Values* und *Structured Concurrency*.
|
||||
* **Kotlin 2.3.0 Features:** Nutzung von `explicit backing fields` und dem verbesserten `unused return value` Checker.
|
||||
72
docs/02_Reference/Tech_Stack/Kotlin_2-3-0_ReleaseNotes.md
Normal file
72
docs/02_Reference/Tech_Stack/Kotlin_2-3-0_ReleaseNotes.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# What's new in Kotlin 2.3.0 | Kotlin Documentation
|
||||
|
||||
**Quelle:** [Original Kotlin Documentation](https://kotlinlang.org/docs/whatsnew23.html)
|
||||
**Datum des Dokuments:** 16. Dezember 2025
|
||||
**Kontext:** Dieses Dokument dient als Referenz für die im Projekt verwendete Kotlin-Version.
|
||||
|
||||
---
|
||||
|
||||
The Kotlin 2.3.0 release is out! Here are the main highlights:
|
||||
|
||||
* **Language:** More stable and default features, unused return value checker, explicit backing fields, and changes to context-sensitive resolution.
|
||||
* **Kotlin/JVM:** Support for Java 25.
|
||||
* **Kotlin/Native:** Improved interop through Swift export, faster build time for release tasks, C and Objective-C library import in Beta.
|
||||
* **Kotlin/Wasm:** Fully qualified names and new exception handling proposal enabled by default, as well as new compact storage for Latin-1 characters.
|
||||
* **Kotlin/JS:** New experimental suspend function export, `LongArray` representation, unified companion object access, and more.
|
||||
* **Gradle:** Compatibility with Gradle 9.0 and a new API for registering generated sources.
|
||||
* **Compose compiler:** Stack traces for minified Android applications.
|
||||
* **Standard library:** Stable time tracking functionality and improved UUID generation and parsing.
|
||||
|
||||
## Language
|
||||
|
||||
Kotlin 2.3.0 focuses on feature stabilization, introduces a new mechanism for detecting unused return values, and improves context-sensitive resolution.
|
||||
|
||||
### Stable features
|
||||
|
||||
The following features have now graduated to Stable:
|
||||
* Support for nested type aliases
|
||||
* Data-flow-based exhaustiveness checks for `when` expressions
|
||||
|
||||
### Features enabled by default
|
||||
* Support for `return` statements in expression bodies with explicit return types is now enabled by default.
|
||||
|
||||
### Experimental: Unused return value checker
|
||||
Kotlin 2.3.0 introduces the unused return value checker to help prevent ignored results. It warns you whenever an expression returns a value other than `Unit` or `Nothing` and isn't used.
|
||||
|
||||
### Experimental: Explicit backing fields
|
||||
A new syntax for explicitly declaring the underlying field that holds a property's value, simplifying the common backing properties pattern.
|
||||
|
||||
## Kotlin/JVM: Support for Java 25
|
||||
Starting with Kotlin 2.3.0, the compiler can generate classes containing Java 25 bytecode.
|
||||
|
||||
## Kotlin/Native
|
||||
* **Improved Swift Export:** Direct mapping for native enum classes and variadic function parameters.
|
||||
* **C and Objective-C Library Import is in Beta:** Better diagnostics for binary compatibility issues.
|
||||
* **Faster Build Time:** Up to 40% faster release builds, especially for iOS targets.
|
||||
|
||||
## Kotlin/Wasm
|
||||
* **Fully Qualified Names Enabled by Default:** `KClass.qualifiedName` is now available at runtime without extra configuration.
|
||||
* **Compact Storage for Latin-1 Characters:** Reduces metadata and binary size.
|
||||
* **New Exception Handling for `wasmWasi`:** Enabled by default for better compatibility with modern WebAssembly runtimes.
|
||||
|
||||
## Kotlin/JS
|
||||
* **Experimental Suspend Function Export:** Export suspend functions directly to JavaScript using `@JsExport`.
|
||||
* **`BigInt64Array` for `LongArray`:** Simplifies interop with JavaScript APIs that use typed arrays.
|
||||
* **Unified Companion Object Access:** Consistent access to companion objects in interfaces across all JS module systems.
|
||||
* **`@JsStatic` in Interfaces:** Now supported in interfaces with companion objects.
|
||||
* **`@JsQualifier` on individual declarations:** Can now be applied to individual functions and classes.
|
||||
* **`@JsExport.Default`:** New annotation for generating JavaScript default exports.
|
||||
|
||||
## Gradle
|
||||
* Fully compatible with Gradle 7.6.3 through 9.0.0.
|
||||
* Minimum supported Android Gradle plugin version is now 8.2.2.
|
||||
* New experimental API for registering generated sources.
|
||||
|
||||
## Standard library
|
||||
* **Stable Time Tracking:** `kotlin.time.Clock` and `kotlin.time.Instant` are now stable.
|
||||
* **Improved UUID Generation:** New functions like `Uuid.parseOrNull()`, `Uuid.generateV4()`, and `Uuid.generateV7()`.
|
||||
|
||||
## Compose compiler
|
||||
* **Stack Traces for Minified Android Apps:** The compiler now outputs ProGuard mappings for Compose stack traces when applications are minified by R8.
|
||||
|
||||
*(Dies ist eine gekürzte Zusammenfassung. Das Originaldokument enthält detailliertere Informationen und Code-Beispiele.)*
|
||||
|
|
@ -1,19 +0,0 @@
|
|||
# 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)
|
||||
8
docs/03_Domain/00_Glossary.md
Normal file
8
docs/03_Domain/00_Glossary.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
# Glossar der Domäne "Meldestelle"
|
||||
|
||||
Dieses Dokument definiert die Ubiquitous Language des Projekts.
|
||||
|
||||
* **Event:** Der organisatorische Rahmen für eine Veranstaltung.
|
||||
* **Turnier:** Die administrative, regelbasierte Einheit innerhalb eines Events.
|
||||
* ...
|
||||
|
||||
6
docs/03_Domain/01_Core_Model/Entities/README.md
Normal file
6
docs/03_Domain/01_Core_Model/Entities/README.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Entitäten des Kern-Modells
|
||||
|
||||
Dieses Verzeichnis enthält detaillierte Beschreibungen der zentralen fachlichen Entitäten des "Meldestelle"-Projekts.
|
||||
Jede Datei beschreibt eine Entität und ihre Attribute.
|
||||
|
||||
Diese Dokumente sind die "Wahrheit" für die Implementierung.
|
||||
|
|
@ -2254,7 +2254,7 @@ sprüchen zur Verfügung zu stehen.
|
|||
4. Die Zusage der Richtertätigkeit ist dem Veranstalter unter Anga-
|
||||
be allfälliger Einschränkungen schriftlich zu bestätigen.
|
||||
5. Aufgaben des/der Stewards bzw. Richters am Abreiteplatz.
|
||||
Aufsicht am Abreiteplatz: Aufsicht des Trainings und des Abrei-
|
||||
Aufsicht am Abreitplatz: Aufsicht des Trainings und des Abrei-
|
||||
tens, Überprüfung der Ausrüstung von Reiter und Pferd, der
|
||||
Hilfsmittel und insbesondere der Sicherheitsausrüstung.
|
||||
Erhalten eines geordneten Abreitens für alle Teilnehmer mit
|
||||
27
docs/04_Agents/Playbooks/Architect.md
Normal file
27
docs/04_Agents/Playbooks/Architect.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# Playbook: Lead Architect (System & Build)
|
||||
|
||||
## Beschreibung
|
||||
Verantwortlich für die Gesamtarchitektur, das Build-System, die Modulstruktur und die Integration der Komponenten. Agiert als primärer technischer Analyst und Koordinator zwischen den anderen Agenten.
|
||||
|
||||
## System Prompt
|
||||
|
||||
```text
|
||||
Software Architect
|
||||
|
||||
Du bist der Lead Software Architect des Projekts "Meldestelle".
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
|
||||
Deine Expertise umfasst:
|
||||
- Kotlin 2.3 & Java 25 im Enterprise-Umfeld.
|
||||
- Gradle Build-Optimierung (Composite Builds, Version Catalogs, Platform BOMs).
|
||||
- Microservices-Architektur mit Spring Cloud (Gateway, Consul, CircuitBreaker).
|
||||
- Infrastruktur-Orchestrierung mit Docker Compose.
|
||||
- "Docs-as-Code"-Prinzipien und die Pflege der zentralen Projektdokumentation.
|
||||
|
||||
Deine Aufgaben:
|
||||
1. Überwache die Einhaltung der Architektur-Regeln (Trennung von API, Domain, Infrastructure).
|
||||
2. Verwalte zentrale Abhängigkeiten im `platform`-Modul und `libs.versions.toml`.
|
||||
3. Löse komplexe Integrationsprobleme zwischen Services, Gateway und Frontend.
|
||||
4. Achte strikt darauf, dass keine Versionen hardcodiert werden, sondern über das Platform-Modul referenziert werden. Ausnahmen müssen dokumentiert werden.
|
||||
5. Pflege die übergreifende Projektdokumentation im `/docs`-Verzeichnis, insbesondere im `01_Architecture`-Bereich.
|
||||
```
|
||||
30
docs/04_Agents/Playbooks/BackendDeveloper.md
Normal file
30
docs/04_Agents/Playbooks/BackendDeveloper.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Playbook: Senior Backend Developer (Spring Boot & DDD)
|
||||
|
||||
## Beschreibung
|
||||
Spezialist für die Implementierung der Fachlogik in den Backend-Services.
|
||||
|
||||
## System Prompt
|
||||
|
||||
```text
|
||||
Backend Developer
|
||||
|
||||
Du bist ein Senior Backend Developer, spezialisiert auf Kotlin und Spring Boot 3.5.x.
|
||||
Du arbeitest an den Microservices und folgst den "Docs-as-Code"-Prinzipien.
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
|
||||
Technologien & Standards:
|
||||
- Framework: Spring Boot 3.5.9, Spring WebFlux (Gateway), Spring MVC (Services).
|
||||
- DB: PostgreSQL, Redis, Mongo.
|
||||
- Architektur: Domain-Driven Design (DDD). Halte Domänenlogik rein und getrennt von Infrastruktur.
|
||||
- Testing: JUnit 5, MockK, Testcontainers (Postgres, Keycloak).
|
||||
- API: REST, OpenAPI (SpringDoc).
|
||||
- **Sync-Strategie:** Implementierung von Delta-Sync APIs (basierend auf UUIDv7/Timestamps) für Offline-First Clients.
|
||||
|
||||
Regeln:
|
||||
1. Nutze `val` und Immutability wo immer möglich.
|
||||
2. Implementiere Business-Logik in der Domain-Schicht, nicht im Controller.
|
||||
3. Nutze Testcontainers für Integrationstests.
|
||||
4. Beachte die Modul-Struktur: `:api` (Interfaces/DTOs), `:domain` (Core Logic), `:service` (Application/Infra).
|
||||
5. **KMP-Awareness:** Achte darauf, dass Code in `:api` und `:domain` Modulen KMP-kompatibel bleibt (keine Java-Dependencies).
|
||||
6. **Dokumentation:** Aktualisiere die Implementierungs-Dokumentation für deinen Service unter `/docs/05_Backend/Services/`.
|
||||
```
|
||||
30
docs/04_Agents/Playbooks/Curator.md
Normal file
30
docs/04_Agents/Playbooks/Curator.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Playbook: Documentation & Knowledge Curator (Pflichtrolle)
|
||||
|
||||
## Beschreibung
|
||||
Sorgt dafür, dass jede Session ein dauerhaft auffindbares Ergebnis in `docs/` hinterlässt.
|
||||
Er ist die "letzte Rolle" jeder Session und verhindert Wissensverlust.
|
||||
|
||||
## System Prompt
|
||||
|
||||
```text
|
||||
Documentation & Knowledge Curator
|
||||
|
||||
Du bist der Documentation & Knowledge Curator für das Projekt "Meldestelle".
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
|
||||
Ziel:
|
||||
- Wissen ist auffindbar, konsistent und versioniert.
|
||||
- Jede Session endet mit genau einem Artefakt in `docs/`.
|
||||
|
||||
Regeln:
|
||||
1. Single Source of Truth ist `docs/`.
|
||||
2. Am Ende der Session entsteht genau ein Artefakt:
|
||||
- ADR (`docs/01_Architecture/adr/`)
|
||||
- Reference / technische Wahrheit pro System (z.B. `docs/05_Backend/Services/<service>.md`)
|
||||
- How-to / Runbook (passender Bereich)
|
||||
- Journal Entry (`docs/99_Journal/`)
|
||||
3. Setze Links auf betroffene Code-Stellen/Dateien.
|
||||
4. Wenn etwas unklar ist: offene Fragen explizit listen und im Artefakt festhalten.
|
||||
|
||||
Du erfindest keine Repo-Fakten. Wenn dir Quellen fehlen, frag nach Dateipfaden oder markiere Annahmen.
|
||||
```
|
||||
27
docs/04_Agents/Playbooks/DevOpsEngineer.md
Normal file
27
docs/04_Agents/Playbooks/DevOpsEngineer.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# Playbook: Infrastructure & DevOps Engineer
|
||||
|
||||
## Beschreibung
|
||||
Verantwortlich für die Laufzeitumgebung, Sicherheit und Observability.
|
||||
|
||||
## System Prompt
|
||||
|
||||
```text
|
||||
DevOps & Infrastructure Engineer
|
||||
|
||||
Du bist ein DevOps & Infrastructure Engineer und folgst den "Docs-as-Code"-Prinzipien.
|
||||
Du verwaltest die Docker-Umgebung und die operativen Aspekte der "Meldestelle".
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
|
||||
Technologien:
|
||||
- Container: Docker, Docker Compose.
|
||||
- IAM: Keycloak 26 (OIDC/OAuth2 Konfiguration).
|
||||
- Service Discovery: HashiCorp Consul.
|
||||
- Monitoring: Prometheus, Grafana, Zipkin, Micrometer Tracing.
|
||||
- DB Ops: PostgreSQL Administration, Flyway Migrationen.
|
||||
|
||||
Aufgaben:
|
||||
1. Stelle sicher, dass alle Container im `docker-compose.yaml` korrekt konfiguriert und vernetzt sind.
|
||||
2. Verwalte Secrets und Umgebungsvariablen (`.env`).
|
||||
3. Konfiguriere Keycloak Realms und Clients.
|
||||
4. **Dokumentation:** Pflege die Infrastruktur-Dokumentation unter `/docs/07_Infrastructure/`.
|
||||
```
|
||||
28
docs/04_Agents/Playbooks/DomainExpert.md
Normal file
28
docs/04_Agents/Playbooks/DomainExpert.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
# Playbook: Domain/Product Expert (optional, Diskussion/Sparring)
|
||||
|
||||
## Beschreibung
|
||||
Agiert als "Übersetzer" zwischen der Vision des Product Owners und den technischen Anforderungen. Er ist der fachliche Sparringspartner, der Regelwerke (ÖTO, FEI), Pflichtenhefte und Anekdoten aus der Praxis analysiert, um daraus ein konsistentes und umsetzbares Domänenmodell abzuleiten.
|
||||
|
||||
## System Prompt
|
||||
|
||||
```text
|
||||
Domain/Product Expert
|
||||
|
||||
Du bist der Domain/Product Expert für das Projekt "Meldestelle", spezialisiert auf den Reitsport.
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
|
||||
Ziel:
|
||||
- Die fachliche Vision des Product Owners in eine klare, strukturierte und umsetzbare Form überführen.
|
||||
- Fachliche Unklarheiten, Mehrdeutigkeiten und Lücken in den Anforderungen aufdecken.
|
||||
- Sicherstellen, dass die technische Lösung die realen Prozesse und Regeln (ÖTO, FEI) exakt abbildet.
|
||||
|
||||
Arbeitsweise:
|
||||
1. Analysiere bereitgestellte Quelldokumente (Regelwerke, Pflichtenhefte, Anekdoten), um die Domäne tiefgreifend zu verstehen.
|
||||
2. Stelle strukturierte Rückfragen, um Annahmen zu validieren und Anforderungen zu schärfen.
|
||||
3. Formuliere Optionen mit klaren Vor- und Nachteilen als Entscheidungsgrundlage.
|
||||
4. Leite aus fachlichen Entscheidungen direkt die Konsequenzen für das Datenmodell, die Benutzerrollen und die Systemprozesse ab.
|
||||
|
||||
Output:
|
||||
- Formuliere Analyse-Ergebnisse und Datenmodell-Entwürfe so, dass sie direkt als "Single Source of Truth" für die Fachlichkeit in `docs/03_Domain/` übernommen werden können.
|
||||
- Erstelle die Grundlage für technische ADRs, indem du die fachlichen "Warum"-Fragen beantwortest.
|
||||
```
|
||||
29
docs/04_Agents/Playbooks/FrontendExpert.md
Normal file
29
docs/04_Agents/Playbooks/FrontendExpert.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# Playbook: KMP Frontend Expert
|
||||
|
||||
## Beschreibung
|
||||
Spezialist für das Frontend "Meldestelle Portal". Fokus auf echte Offline-Fähigkeit (Web & Desktop) und High-Performance UI mit Compose Multiplatform.
|
||||
|
||||
## System Prompt
|
||||
|
||||
```text
|
||||
Frontend Developer
|
||||
|
||||
Du bist ein Senior Frontend Developer und Experte für Kotlin Multiplatform (KMP).
|
||||
Du entwickelst das "Meldestelle Portal" für Desktop (JVM) und Web (JS/Wasm) und folgst den "Docs-as-Code"-Prinzipien.
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
|
||||
Technologien & Standards:
|
||||
- **UI:** Compose Multiplatform 1.10.x (Material 3).
|
||||
- **Persistenz (Offline-First):** SQLDelight 2.2.x mit "Async-First" Architektur.
|
||||
- **State Management:** ViewModel, Kotlin Coroutines/Flow.
|
||||
- **DI:** Koin 4.x (Compose Integration).
|
||||
- **Network:** Ktor Client 3.x (Environment-aware Config).
|
||||
- **Build:** Gradle Version Catalogs (`libs.versions.toml`) mit strikter Nutzung von Bundles.
|
||||
|
||||
Regeln:
|
||||
1. **Async-First Data Layer:** Alle Datenbank-Interaktionen müssen asynchron (`suspend`) entworfen sein.
|
||||
2. **Strict KMP Boundaries:** Keine JVM-only Bibliotheken im `commonMain`.
|
||||
3. **Dependency Management:** Nutze ausschließlich die definierten Bundles in `libs.versions.toml`.
|
||||
4. **UI-Architektur:** Trenne UI (Composables) strikt von Logik.
|
||||
5. **Dokumentation:** Pflege die Frontend-spezifische Dokumentation unter `/docs/06_Frontend/`.
|
||||
```
|
||||
25
docs/04_Agents/Playbooks/QASpecialist.md
Normal file
25
docs/04_Agents/Playbooks/QASpecialist.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# Playbook: QA & Testing Specialist
|
||||
|
||||
## Beschreibung
|
||||
Fokus auf Teststrategie, Testdaten und End-to-End Qualitätssicherung.
|
||||
|
||||
## System Prompt
|
||||
|
||||
```text
|
||||
Testing Specialist
|
||||
|
||||
Du bist der QA & Testing Specialist für das Projekt und folgst den "Docs-as-Code"-Prinzipien.
|
||||
Dein Ziel ist eine hohe Testabdeckung und stabile Builds.
|
||||
Kommuniziere ausschließlich auf Deutsch.
|
||||
|
||||
Tools:
|
||||
- Backend: JUnit 5, AssertJ, MockK, Testcontainers.
|
||||
- Frontend: Compose UI Tests (sofern möglich), Unit Tests für ViewModels.
|
||||
- CI: Gradle Check Tasks.
|
||||
|
||||
Regeln:
|
||||
1. Fördere "Testing Pyramid": Viele Unit Tests, moderate Integration Tests, gezielte E2E Tests.
|
||||
2. Stelle sicher, dass Tests deterministisch sind (keine Flakiness).
|
||||
3. Nutze das `platform-testing` Modul für konsistente Test-Abhängigkeiten.
|
||||
4. **Dokumentation:** Dokumentiere die Teststrategie und wichtige Testfälle im `/docs`-Verzeichnis.
|
||||
```
|
||||
|
|
@ -10,6 +10,19 @@ Das Frontend ist eine **Kotlin Multiplatform (KMP)**-Anwendung, die für die fol
|
|||
|
||||
Die Architektur ist auf **Offline-Fähigkeit** und eine reaktive UI ausgelegt.
|
||||
|
||||
## Modul-Struktur
|
||||
|
||||
Das `frontend`-Verzeichnis ist wie folgt strukturiert, um eine klare Trennung der Verantwortlichkeiten zu gewährleisten:
|
||||
|
||||
* `shells/`: Die ausführbaren Anwendungen (Assembler-Module), die die App für eine bestimmte Plattform (Desktop, Web) zusammenbauen.
|
||||
* `features/`: Vertikale Slices der Anwendung. Jedes Feature-Modul kapselt eine bestimmte Funktionalität (z.B. `auth-feature`, `ping-feature`). Wichtig: Ein Feature-Modul darf niemals von einem anderen Feature-Modul abhängen.
|
||||
* `core/`: Gemeinsame Basis-Module, die von allen Features genutzt werden. Dazu gehören:
|
||||
* `design-system/`: Compose-Komponenten, Themes, Farben.
|
||||
* `domain/`: Fachliche Kernlogik und Datenmodelle des Frontends.
|
||||
* `local-db/`: SQLDelight-Datenbank-Setup und Queries.
|
||||
* `navigation/`: Navigations-Logik und Routen-Definitionen.
|
||||
* `network/`: Ktor-Client und API-Definitionen.
|
||||
|
||||
## Kerntechnologien
|
||||
|
||||
* **UI:** [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/) für eine deklarative, plattformübergreifende UI.
|
||||
|
|
@ -18,12 +31,6 @@ Die Architektur ist auf **Offline-Fähigkeit** und eine reaktive UI ausgelegt.
|
|||
* **Dependency Injection:** [Koin](https://insert-koin.io/) für die lose Kopplung von Komponenten.
|
||||
* **Netzwerk:** [Ktor Client](https://ktor.io/docs/client-introduction.html) für die Kommunikation mit dem Backend.
|
||||
|
||||
## Architektur-Prinzipien
|
||||
|
||||
* **Clean Architecture / DDD:** Die Codebasis ist in Schichten unterteilt (UI, Application, Domain, Infrastructure), um eine klare Trennung der Verantwortlichkeiten zu gewährleisten.
|
||||
* **Async-First Data Layer:** Alle Datenbank- und Netzwerk-Interaktionen sind asynchron (`suspend`-Funktionen), um die UI nicht zu blockieren.
|
||||
* **Feature-basierte Modularisierung:** Die Anwendung ist in unabhängige "Feature"-Module unterteilt, die jeweils eine bestimmte Funktionalität kapseln.
|
||||
|
||||
## Wichtige Dokumente
|
||||
|
||||
* **[ADR-0010: SQLDelight für Cross-Platform-Persistenz](../01_Architecture/adr/0010-sqldelight-for-cross-platform-persistence.md):** Beschreibt die Entscheidung für SQLDelight.
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# Analyse und Strategie zur Wiederherstellung und Strukturverbesserung
|
||||
|
||||
**Datum:** 2026-01-02
|
||||
**Autor:** Junie
|
||||
**Kontext:** Dieser Bericht wurde nach einem großen Technologie-Upgrade (Kotlin 2.1.0+, Java 25, Spring Boot 3.5.x) erstellt, als die Infrastruktur und die Build-Prozesse instabil waren.
|
||||
|
||||
---
|
||||
|
||||
Es ist eine klassische Situation: Nach einem großen Technologie-Upgrade knirscht es oft an den Schnittstellen. Da der `ping-service` als technischer Blueprint dient, ist er der absolut richtige Startpunkt.
|
||||
|
||||
Hier ist der Schlachtplan, um Ordnung zu schaffen und die hexagonale Architektur sauber zu etablieren:
|
||||
|
||||
### 1. Wo beginnen? Bottom-Up vs. Top-Down
|
||||
Da die Infrastruktur aktuell nicht stabil läuft, wird ein **"Core-First"** Ansatz empfohlen, gefolgt vom **Backend-Durchstich**.
|
||||
|
||||
* **Zuerst: Core & Platform:** Ohne eine stabile Basis (`platform-bom`, `platform-dependencies`, `core-domain`) werden die anderen Module immer wieder Kompilierfehler werfen.
|
||||
* **Dann: Der technische vertikale Durchstich (`ping-service`):** Sobald die Plattform steht, wird der Weg repariert: `Infrastruktur (Docker) -> Ping-Service -> Gateway`.
|
||||
* **Zuletzt: Frontend:** Das Frontend (BFF-Gedanke) wird erst dann stabil, wenn die API-Contracts des Backends wieder verlässlich geliefert werden.
|
||||
|
||||
### 2. Ordnung schaffen: Der "Clean Desk" im Projekt
|
||||
Bevor Code gefixt wird, muss die Build-Umgebung aufgeräumt werden:
|
||||
|
||||
1. **Version Catalog Synchronität:** Die `libs.versions.toml` nutzt bereits Java 25 und Kotlin 2.1.0. Es muss geprüft werden, ob alle Gradle-Plugins (insbesondere das `compose-multiplatform` und `spring-boot` Plugin) mit Kotlin 2.1.0 kompatibel sind.
|
||||
2. **Modul-Konsolidierung (DDD):** Die "Modul-Explosion" sollte reduziert werden.
|
||||
* **Vorschlag:** Statt 5 Module pro Domain (`api`, `common`, `domain`, `infrastructure`, `service`), auf maximal zwei reduzieren:
|
||||
* `domain-api`: Nur DTOs und Interfaces (für KMP-Sharing mit dem Frontend).
|
||||
* `domain-service`: Die gesamte Implementierung (Hexagonal strukturiert in Packages).
|
||||
|
||||
### 3. Hexagonale Architektur im `ping-service` umsetzen
|
||||
Der `ping-service` ist aktuell noch sehr "Spring-lastig". Für eine echte hexagonale Vorlage sollte das Modul `ping-service` intern wie folgt umstrukturiert werden:
|
||||
|
||||
```text
|
||||
at.mocode.ping.service
|
||||
├── adapter
|
||||
│ ├── in
|
||||
│ │ └── web (PingController - Dein primärer Port-Adapter)
|
||||
│ └── out
|
||||
│ └── persistence (PingRepositoryAdapter - Sekundärer Port-Adapter)
|
||||
├── application
|
||||
│ ├── port
|
||||
│ │ ├── in (PingUseCase - Das Interface für den Controller)
|
||||
│ │ └── out (PingOutputPort - Interface für die Datenbank)
|
||||
│ └── service (PingService - Hier liegt die Business Logik, OHNE Spring-Annotationen wo möglich)
|
||||
└── domain
|
||||
└── model (PingEntity/Value Objects)
|
||||
```
|
||||
|
||||
### 4. Konkrete Schritte zur Reparatur
|
||||
|
||||
**Schritt 1: Infrastruktur-Check (Docker)**
|
||||
* Check `docker-compose.yaml`: Laufen Postgres und Keycloak?
|
||||
* `ping-service` application.yaml: Die Datenbank-Verbindung (JPA) aktivieren.
|
||||
|
||||
**Schritt 2: Backend API-Gateway Fix**
|
||||
* Die Security-Konfiguration (`SecurityConfig.kt`) wegen Bibliotheks-Änderungen in Spring Security 7/Spring Boot 3.5 prüfen.
|
||||
|
||||
**Schritt 3: Frontend (BFF) Anpassung**
|
||||
* Der `PingApiClient` im Frontend sollte gegen das **Gateway** (BFF-Pattern) laufen, nicht direkt gegen den Service.
|
||||
|
||||
### Empfehlung zur Vorgehensweise (Prioritäten):
|
||||
1. **Gradle-Build stabilisieren:** Alle `:platform:*` und `:core:*` Module müssen mit `./gradlew build` fehlerfrei durchlaufen.
|
||||
2. **Ping-SCS fertigstellen:** Eine minimale Datenbank-Speicherung im `ping-service` implementieren.
|
||||
3. **Gateway-Security:** Sicherstellen, dass das JWT von Keycloak korrekt zum `ping-service` durchgereicht wird.
|
||||
46
docs/90_Reports/2026-01-14_Domain_Structure_Plan.md
Normal file
46
docs/90_Reports/2026-01-14_Domain_Structure_Plan.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# Plan zur Strukturierung der Domänen-Dokumentation
|
||||
|
||||
* **Datum:** 2026-01-14
|
||||
* **Autor:** Documentation & Knowledge Curator
|
||||
* **Status:** Entwurf
|
||||
|
||||
## Ausgangslage
|
||||
|
||||
Das Verzeichnis `docs/02_Domain` enthält wertvolle, aber zunehmend unübersichtliche Informationen.
|
||||
Es gibt eine Mischung aus:
|
||||
* Destilliertem Wissen (`01_Core_Entities.md`)
|
||||
* Referenz-Material (`Reference/FEI...`, `Reference/OETO...`)
|
||||
* Entwicklungs-Infos (`Development/`)
|
||||
* Implizitem Wissen (`Reference/Geschichten`)
|
||||
|
||||
## Zielbild
|
||||
|
||||
Gemäß **ADR-0012** (Proposed) soll eine strikte Trennung nach Reifegrad eingeführt werden.
|
||||
|
||||
## Migrations-Schritte
|
||||
|
||||
1. **Verzeichnisse erstellen:**
|
||||
* `docs/02_Domain/01_Core_Model/Entities`
|
||||
* `docs/02_Domain/01_Core_Model/Processes`
|
||||
* `docs/02_Domain/01_Core_Model/Rules`
|
||||
* `docs/02_Domain/03_Analysis/Scenarios`
|
||||
|
||||
2. **Dateien verschieben & umbenennen:**
|
||||
* `01_Core_Entities.md` -> `01_Core_Model/Entities/Overview.md` (oder aufsplitten)
|
||||
* `Reference/Geschichten` -> `03_Analysis/Scenarios`
|
||||
* `Reference/FEI_01-2026` -> `02_Reference/FEI_Regelwerk`
|
||||
* `Reference/OETO_01-2026` -> `02_Reference/OETO_Regelwerk`
|
||||
|
||||
3. **Development-Ordner auflösen:**
|
||||
* Die Inhalte von `docs/02_Domain/Development` (`kdoc-style.md`, `start-local.md`, `branchschutz...`) gehören **nicht** in die Domäne.
|
||||
* `start-local.md` -> `docs/02_Onboarding/`
|
||||
* `branchschutz...` -> `docs/02_Onboarding/`
|
||||
* `kdoc-style.md` -> `docs/02_Onboarding/CodingGuidelines/`
|
||||
|
||||
4. **Glossar anlegen:**
|
||||
* Erstellung von `docs/02_Domain/00_Glossary.md` als leere Hülle für den Start.
|
||||
|
||||
## Nächste Schritte für den User
|
||||
|
||||
* Bestätigung des ADR-0012.
|
||||
* Freigabe zur Durchführung der Datei-Operationen (Verschieben/Umbenennen).
|
||||
53
docs/90_Reports/2026-01-14_Project_Analysis.md
Normal file
53
docs/90_Reports/2026-01-14_Project_Analysis.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
# Projektanalyse Bericht: Meldestelle
|
||||
|
||||
* **Datum:** 2026-01-14
|
||||
* **Autor:** Documentation & Knowledge Curator
|
||||
* **Status:** Final
|
||||
|
||||
## 1. Einleitung
|
||||
|
||||
Dieser Bericht fasst die Ergebnisse einer vertieften Analyse des Projekts "Meldestelle" zusammen. Ziel war es, den aktuellen Stand der Architektur, der Infrastruktur und der Dokumentationspraxis zu bewerten. Die Analyse basiert auf dem aktuellen Dateisystemstand und den vorhandenen Dokumentationen.
|
||||
|
||||
## 2. Architektur & Technologie-Stack
|
||||
|
||||
Das Projekt präsentiert sich als modernes, verteiltes System mit einem hohen Anspruch an technologische Aktualität.
|
||||
|
||||
* **Backend:**
|
||||
* **Architektur:** Microservices-Ansatz mit Spring Boot 3.5.9 und Java 25/Kotlin 2.3.0.
|
||||
* **Struktur:** Klare Modulith-Struktur innerhalb der Services (`api`, `domain`, `infrastructure`, `service`), was Domain-Driven Design (DDD) fördert.
|
||||
* **Kommunikation:** Event-Driven Ansätze (Redis/Kafka angedeutet) und REST via Spring Cloud Gateway.
|
||||
* **Service Discovery:** HashiCorp Consul wird konsequent genutzt.
|
||||
|
||||
* **Frontend:**
|
||||
* **Technologie:** Kotlin Multiplatform (KMP) mit Compose Multiplatform 1.10.x.
|
||||
* **Plattformen:** Desktop (JVM) und Web (Wasm/JS).
|
||||
* **Offline-First:** Starke Betonung auf Offline-Fähigkeit mit SQLDelight und Sync-Strategien.
|
||||
|
||||
* **Build-System:**
|
||||
* Gradle 9.x mit Version Catalogs (`libs.versions.toml`) ist vorbildlich umgesetzt. Die Nutzung von Bundles reduziert Boilerplate in den Modulen.
|
||||
|
||||
## 3. Infrastruktur & Betrieb
|
||||
|
||||
Die Infrastruktur-Definition via Docker Compose ist umfassend und produktionsnah für eine lokale Umgebung.
|
||||
|
||||
* **Komponenten:** PostgreSQL, Redis, Keycloak, Consul, Prometheus, Grafana, Zipkin.
|
||||
* **Konfiguration:** Detaillierte Healthchecks, Netzwerk-Aliase und Profil-Nutzung (`infra`, `backend`, `gui`).
|
||||
* **Herausforderungen:** Die Komplexität der Orchestrierung zeigt sich in den jüngsten Journal-Einträgen (Startprobleme, Race Conditions beim Build).
|
||||
|
||||
## 4. Dokumentation (Docs-as-Code)
|
||||
|
||||
Die Dokumentationsstrategie ist exzellent definiert und wird sichtbar gelebt.
|
||||
|
||||
* **Struktur:** `docs/` als Single Source of Truth ist klar erkennbar.
|
||||
* **ADRs:** Vorhandene Architecture Decision Records (z.B. `ADR-001 Koin`, `ADR-002 SQLDelight`) belegen bewusste Entscheidungen.
|
||||
* **Rollen:** Die Definition von KI-Personas (Agents) im `docs/03_Agents/` Bereich ist innovativ und sorgt für konsistente Arbeitsweisen.
|
||||
* **Journal:** Die Nutzung des Journals (`docs/99_Journal/`) zur Fehlersuche und Statusverfolgung ist vorbildlich.
|
||||
|
||||
## 5. Aktuelle Beobachtungen & Risiken
|
||||
|
||||
* **Gateway-Konfiguration:** Es gibt ein offenes Problem mit dem `CircuitBreaker` im API-Gateway (siehe Journal vom 13.01.2026). Dies deutet auf eine fehlende Runtime-Dependency oder Fehlkonfiguration hin.
|
||||
* **Komplexität:** Der Tech-Stack ist sehr "bleeding edge" (Java 25, Kotlin 2.3, Spring Boot 3.5.9). Dies birgt das Risiko von Inkompatibilitäten und Tooling-Problemen (wie bereits bei den Gradle-Locks beobachtet).
|
||||
|
||||
## 6. Fazit
|
||||
|
||||
Das Projekt "Meldestelle" ist architektonisch sehr reif und modern. Die strikte Trennung von Belangen und die konsequente Anwendung von DDD und Docs-as-Code sind hervorzuheben. Der Fokus sollte kurzfristig auf der Stabilisierung der lokalen Docker-Umgebung liegen, um die Developer Experience (DX) sicherzustellen.
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
# Journal: Umfassende Konsolidierung der Dokumentationsstruktur
|
||||
|
||||
* **Datum:** 2026-01-14
|
||||
* **Autor:** Documentation & Knowledge Curator
|
||||
* **Thema:** Eine tiefgreifende Restrukturierung und Bereinigung der gesamten Projektdokumentation, um die "Single Source of Truth"-Regel konsequent durchzusetzen.
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
In dieser Session wurde eine Reihe von Inkonsistenzen und Redundanzen in der Projektdokumentation identifiziert und systematisch beseitigt. Ziel war es, eine klare, wartbare und leicht navigierbare Struktur zu schaffen, die dem "Docs-as-Code"-Prinzip vollständig entspricht.
|
||||
|
||||
## Durchgeführte Maßnahmen
|
||||
|
||||
1. **Strukturierung der Domänen-Dokumentation (`docs/03_Domain`):**
|
||||
* Gemäß **[ADR-0012](../01_Architecture/adr/0012-domain-documentation-structure.md)** wurde eine neue, nach Reifegrad getrennte Ordnerstruktur eingeführt (`00_Glossary`, `01_Core_Model`, `02_Reference`, `03_Analysis`).
|
||||
* Bestehende Dokumente (Regelwerke, Kern-Entitäten, "Geschichten") wurden in diese neue Struktur migriert.
|
||||
* Technische Anleitungen wurden aus dem Domänen-Ordner in den `02_Onboarding`-Bereich verschoben.
|
||||
|
||||
2. **Behebung der Nummerierungs-Inkonsistenz im `docs`-Verzeichnis:**
|
||||
* Die doppelte Verwendung der Nummer `02_` wurde behoben, indem die Verzeichnisse linear von `01` bis `07` umbenannt wurden.
|
||||
* Die zentrale `docs/README.md` wurde entsprechend aktualisiert, um die neue, logische Reihenfolge widerzuspiegeln.
|
||||
|
||||
3. **Zentralisierung der Agenten-Playbooks:**
|
||||
* Die System-Prompts der KI-Agenten wurden aus der `AGENTS.md` extrahiert und in dedizierte Playbook-Dateien unter `docs/04_Agents/Playbooks/` verschoben.
|
||||
* Die `AGENTS.md` dient nun als reine Übersichts- und Einstiegsseite mit Links zu den Playbooks.
|
||||
* Die `.gemini/README.md` wurde korrigiert und vereinfacht.
|
||||
|
||||
4. **Standardisierung der Modul-READMEs:**
|
||||
* Die `README.md`-Dateien in allen Haupt-Modulen (`platform`, `frontend`, `backend`, `core`, `contracts`) wurden vereinheitlicht.
|
||||
* Sie dienen nun ausschließlich als **Wegweiser** zur zentralen Dokumentation im `docs`-Verzeichnis und enthalten keine redundanten Informationen mehr.
|
||||
|
||||
5. **Bereinigung der Root-`README.md`:**
|
||||
* Die `README.md` im Projekt-Root wurde radikal gekürzt. Sie dient jetzt als minimalistische "Visitenkarte" mit den wichtigsten Links zur Dokumentation und zum Quick-Start.
|
||||
|
||||
6. **Archivierung veralteter Berichte:**
|
||||
* Alte Berichte aus den Verzeichnissen `JunieBerichte` und `GeminiBerichte` wurden analysiert und als Referenz- oder Analyse-Dokumente in das `docs`-Verzeichnis (`90_Reports` oder `02_Reference`) überführt.
|
||||
|
||||
## Ergebnis
|
||||
|
||||
Das Projekt verfügt nun über eine hochgradig konsistente, redundanzfreie und wartbare Dokumentationsstruktur. Die Gefahr von "Dokumentations-Drift" wurde signifikant reduziert.
|
||||
39
docs/99_Journal/2026-01-14_TODO_Final-Doc-Cleanup.md
Normal file
39
docs/99_Journal/2026-01-14_TODO_Final-Doc-Cleanup.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
# TODO-Liste: Finale Bereinigung der Dokumentation
|
||||
|
||||
* **Datum:** 2026-01-14
|
||||
* **Autor:** Documentation & Knowledge Curator
|
||||
* **Status:** Offen
|
||||
|
||||
## Kontext
|
||||
|
||||
Nach der großen Dokumentations-Restrukturierung sind beim Commit-Prozess Linting-Fehler und Link-Warnungen aufgetaucht. Diese Liste dient als Plan, um diese letzten Probleme in der nächsten Session zu beheben.
|
||||
|
||||
---
|
||||
|
||||
## Offene Punkte
|
||||
|
||||
### 1. "Broken Links" in Tech-Stack-Referenzen beheben
|
||||
|
||||
* **Problem:** Die aus dem Web kopierten Dokumente (`Gradle_Kotlin_DSL_Primer.md`, `Kotlin_2-3-0_ReleaseNotes.md`) in `docs/02_Reference/Tech_Stack/` enthalten hunderte ungültige, relative Links, die von den Original-Webseiten stammen.
|
||||
* **Aktion:**
|
||||
* Öffne beide Dateien.
|
||||
* Entferne die kompletten Navigations-Sidebars und alle anderen internen Links, die Fehler verursachen.
|
||||
* Reduziere die Dateien auf ihren reinen Inhalts-Kern. Der Link zur Original-Quelle am Anfang jeder Datei ist ausreichend.
|
||||
|
||||
### 2. Ungültiges HTML in Legacy-Spezifikation korrigieren
|
||||
|
||||
* **Problem:** Die Datei `docs/03_Domain/02_Reference/Legacy_Specs/OETO-2026_Meldestelle_Erweiterung-Schnittstelle_2014.md` enthält ungültige XML/HTML-Tags.
|
||||
* **Aktion:**
|
||||
* Öffne die Datei.
|
||||
* Formatiere den Inhalt als Markdown-Code-Block mit dem Typ `xml`, um die Struktur zu erhalten, ohne dass der Parser Fehler meldet.
|
||||
|
||||
### 3. Fehlende `README.md`-Dateien im `docs`-Verzeichnis erstellen
|
||||
|
||||
* **Problem:** Die Wegweiser-READMEs in den Modulen `backend`, `core` und `contracts` zeigen auf nicht-existente Zieldateien.
|
||||
* **Aktion:** Erstelle die folgenden Platzhalter-Dateien, um die Links gültig zu machen:
|
||||
* `docs/05_Backend/README.md` (mit einem kurzen Platzhaltertext)
|
||||
* `docs/03_Domain/01_Core_Model/README.md` (mit einem kurzen Platzhaltertext)
|
||||
|
||||
---
|
||||
|
||||
Nach Abarbeitung dieser Liste sollte das Projekt frei von Dokumentations-Warnungen sein.
|
||||
|
|
@ -8,10 +8,11 @@ Die Dokumentation wird nach dem **"Docs-as-Code"**-Prinzip gepflegt: Sie liegt n
|
|||
|
||||
* **/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).
|
||||
* **/03_Domain**: Fachliche Domäne (Kern-Modell, Referenzen, Analyse).
|
||||
* **/04_Agents**: Agent Operating Model (AOM) + Playbooks für KI-Unterstützung.
|
||||
* **/05_Backend**: Backend-spezifische Dokumentation (Services, Datenmodelle, Integrationen).
|
||||
* **/06_Frontend**: Frontend-spezifische Dokumentation (KMP/Compose, Offline/Synchronisierung).
|
||||
* **/07_Infrastructure**: Betrieb & Infrastruktur (Docker, Keycloak, Observability, Runbooks).
|
||||
* **/90_Reports**: Berichte/Analysen/Status-Reports (zeitlich geordnet, nicht zwingend „verbindliche Regeln“).
|
||||
* **/99_Journal**: Kurzprotokolle pro Session (Anti-Wissensverlust, Nachvollziehbarkeit).
|
||||
|
||||
|
|
@ -27,9 +28,10 @@ Jeder Entwickler und jeder KI-Agent ist dafür verantwortlich, die Dokumentation
|
|||
|
||||
### Wichtigste Einstiege
|
||||
|
||||
* Agenten/Arbeitsmodus: `docs/03_Agents/`
|
||||
* Lokales Setup/Workflow: `docs/02_Onboarding/`
|
||||
* Fachliches Modell: `docs/03_Domain/`
|
||||
* Agenten/Arbeitsmodus: `docs/04_Agents/`
|
||||
* Architekturentscheidungen: `docs/01_Architecture/adr/`
|
||||
* Backend (pro Service): `docs/04_Backend/Services/`
|
||||
* Ping-Service (Startpunkt): `docs/04_Backend/Services/ping-service.md`
|
||||
* Backend (pro Service): `docs/05_Backend/Services/`
|
||||
* Ping-Service (Startpunkt): `docs/05_Backend/Services/ping-service.md`
|
||||
* Ping-Service Implementierungs-Report (Historie): `docs/90_Reports/Ping-Service_Impl_01-2026.md`
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
# Frontend
|
||||
# Frontend Module
|
||||
|
||||
Kotlin Multiplatform Frontend layer.
|
||||
Dieses Modul enthält den gesamten Code für das Kotlin Multiplatform (KMP) Frontend "Meldestelle Portal".
|
||||
|
||||
- shells: ausführbare Anwendungen (Assembler)
|
||||
- features: Vertical Slices (kein Feature→Feature Import)
|
||||
- core: gemeinsame Basis (Design-System, Network, Local-DB, Auth, Domain)
|
||||
**Die vollständige Dokumentation befindet sich hier:**
|
||||
[**-> docs/06_Frontend/README.md**](../docs/06_Frontend/README.md)
|
||||
|
|
|
|||
6
platform/README.md
Normal file
6
platform/README.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Platform Module
|
||||
|
||||
Dieses Modul ist für die zentrale Verwaltung von Abhängigkeiten und Build-Infrastruktur zuständig.
|
||||
|
||||
**Die vollständige Dokumentation befindet sich hier:**
|
||||
[**-> docs/01_Architecture/03_Build_System_Platform_Module.md**](../docs/01_Architecture/03_Build_System_Platform_Module.md)
|
||||
Loading…
Reference in New Issue
Block a user