docs: archive outdated reports and organize references
Archived several outdated reports (`Ping-Service_Impl_01-2026.md`, `Frontend_Integration_Status.md`, etc.) and added archival notes and references to updated documents. Introduced a centralized reference structure for tech stack documentation, consolidating files under `01_Architecture/Reference/Tech_Stack`. Added new resources (`Gradle_Kotlin_DSL_Primer`, `Kotlin_2-3-0_ReleaseNotes`) for improved project organization and clarity.
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
---
|
||||
type: Guide
|
||||
status: ACTIVE
|
||||
owner: Lead Architect
|
||||
tags: [coding-style, kdoc, documentation]
|
||||
---
|
||||
|
||||
# KDoc-Styleguide (Kurzfassung)
|
||||
|
||||
Dieser Styleguide definiert die wichtigsten Regeln für KDoc-Kommentare in Kotlin-Projekten der Meldestelle. Ziel:
|
||||
Verständliche, konsistente API-Dokumentation via Dokka (GFM/HTML).
|
||||
|
||||
## Grundregeln
|
||||
|
||||
- Sprache: Deutsch für Fließtexte; Code/Bezeichner bleiben Englisch.
|
||||
- Jeder public class, interface, object, enum, public function und public property erhält einen KDoc-Block.
|
||||
- KDoc beginnt mit einem vollständigen, aussagekräftigen Satz in der dritten Person.
|
||||
- Beispiele und wichtige Hinweise als kurze Absätze oder Listen, keine Romane.
|
||||
|
||||
## Struktur eines KDoc-Blocks
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Beschreibt prägnant, was das Element macht und warum es existiert.
|
||||
*
|
||||
* Details: Optionale Erläuterung von Parametern, Nebenwirkungen, Fehlerfällen.
|
||||
*
|
||||
* @param id Eindeutige Kennung des Members
|
||||
* @return Das gefundene Objekt oder null, wenn nicht vorhanden
|
||||
* @throws IllegalArgumentException Falls Parameter ungültig sind
|
||||
*/
|
||||
fun findMember(id: MemberId): Member?
|
||||
```
|
||||
|
||||
## Tags
|
||||
|
||||
- @param: Für jeden Parameter bei public Funktionen
|
||||
- @return: Wenn Rückgabewert semantisch relevant ist
|
||||
- @throws: Relevante Exceptions dokumentieren
|
||||
- @since, @see: Sparsam verwenden, wenn es wirklichen Mehrwert bringt
|
||||
|
||||
## Stil & Sprache
|
||||
|
||||
- Klar, knapp, aktiv. Keine Redundanz.
|
||||
- Domänenbegriffe verwenden (BCs: members, horses, events, masterdata, infrastructure).
|
||||
- Keine Interna oder Secrets dokumentieren.
|
||||
|
||||
## Beispielschnipsel
|
||||
|
||||
```kotlin
|
||||
/** Erstellt einen neuen Event und persistiert ihn transaktional. */
|
||||
fun createEvent(cmd: CreateEventCommand): EventId
|
||||
```
|
||||
|
||||
## Dokka-Hinweise
|
||||
|
||||
- Dokka erzeugt GFM (Markdown) unter build/dokka/gfm und HTML unter build/dokka/html.
|
||||
- Source-Link führt auf GitHub (main-Branch). Prüfe Links in der CI.
|
||||
|
||||
## Review
|
||||
|
||||
- PR-Checklist: "KDoc vollständig?" anhaken, wenn neue public APIs hinzugekommen sind.
|
||||
- Vale/markdownlint gelten nur für .md; KDoc wird redaktionell in Code-Reviews geprüft.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
type: Guide
|
||||
status: ACTIVE
|
||||
owner: DevOps Engineer
|
||||
tags: [git, workflow, pr, branching]
|
||||
---
|
||||
|
||||
# Branchschutz & Pull-Request Workflow
|
||||
|
||||
Diese Anleitung beschreibt einen einfachen, robusten Flow für `main` mit kurzen Feature-Branches und klaren
|
||||
Qualitätschecks.
|
||||
|
||||
## 1) Branch-Naming
|
||||
|
||||
- Feature: `feature/<kurz-beschreibung>`
|
||||
- Bugfix: `fix/<kurz-beschreibung>`
|
||||
- Docs: `docs/<kurz-beschreibung>`
|
||||
|
||||
Optional: Issue-Key voranstellen, z. B. `feature/MP-7-doku-konsolidieren`.
|
||||
|
||||
## 2) Pull Request (PR)
|
||||
|
||||
- PR-Titel nach Conventional Commits (kurz): `docs(api): Front‑Matter vereinheitlicht (MP-7)`
|
||||
- Beschreibung kurz mit Bulletpoints; DoD-Checkliste abhaken (Template vorhanden)
|
||||
- CI muss grün sein (Backend + Docs)
|
||||
|
||||
## 3) Branchschutz (GitHub Einstellungen → Branches → main)
|
||||
|
||||
- Require a pull request before merging
|
||||
- Require status checks to pass before merging
|
||||
- aktivieren: `CI Docs`, `CI` (Backend falls vorhanden)
|
||||
- Require linear history
|
||||
- Require approvals: mindestens 1 (bei Solo-Projekt optional, aber empfohlen)
|
||||
- Allow squash merging only
|
||||
- Disallow force pushes, Disallow deletions
|
||||
|
||||
## 4) Commits & YouTrack
|
||||
|
||||
- Commit-Message enthält Issue-Key (z. B. `MP-7`) → erleichtert Nachverfolgung
|
||||
- In Doku-Front‑Matter `yt_epic`/`yt_issues` pflegen
|
||||
- Optional: GitHub Secrets `YT_URL`, `YT_TOKEN` setzen → CI validiert verlinkte Issues, und `youtrack-sync.yml`
|
||||
kommentiert beim Merge automatisch ins Issue
|
||||
|
||||
## 5) Definition of Done (Auszug)
|
||||
|
||||
- Doku aktuell (README/ADR/C4/API)
|
||||
- Front‑Matter valide (`modul`, `status`, `summary`, optional `last_reviewed`, `review_cycle`, `yt_*`)
|
||||
- Links funktionieren (CI link-check grün)
|
||||
- Tests grün
|
||||
|
||||
## 6) Lokale Tipps
|
||||
|
||||
- Vor dem Push: `markdownlint`, `vale` lokal laufen lassen (optional via pre-commit hooks)
|
||||
- kleine, häufige PRs statt großer Monster-PRs
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
type: Guide
|
||||
status: ACTIVE
|
||||
owner: DevOps Engineer
|
||||
tags: [setup, local, docker, gradle]
|
||||
---
|
||||
|
||||
# Start Local (Lokales Setup)
|
||||
|
||||
Kurzanleitung, um das Projekt lokal in wenigen Minuten zu starten.
|
||||
|
||||
## Voraussetzungen
|
||||
- Docker und Docker Compose (v2)
|
||||
- Java 25 (JDK)
|
||||
- Git
|
||||
|
||||
## Schnellstart
|
||||
|
||||
```bash
|
||||
# 1) Repository klonen
|
||||
git clone https://github.com/StefanMoCoAt/meldestelle.git
|
||||
cd meldestelle
|
||||
|
||||
# 2) Runtime-Environment vorbereiten
|
||||
# Kopiere die Vorlage.
|
||||
cp .env.example .env
|
||||
|
||||
# 3) Infrastruktur starten (Postgres, Redis, Keycloak, Monitoring, Gateway)
|
||||
docker compose --profile infra up -d
|
||||
|
||||
# 4) Backend starten (Gateway + Ping Service)
|
||||
docker compose --profile backend up -d
|
||||
```
|
||||
|
||||
Sobald die Infrastruktur läuft, erreichst du unter anderem:
|
||||
- Gateway: http://localhost:8081
|
||||
- Keycloak: http://localhost:8180
|
||||
- Grafana: http://localhost:3000
|
||||
- Prometheus: http://localhost:9090
|
||||
|
||||
## Tests ausführen
|
||||
```bash
|
||||
# Führt alle Tests aus
|
||||
./gradlew test
|
||||
|
||||
# Spezifisches Backend-Modul testen
|
||||
./gradlew :backend:services:ping:ping-service:test
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
- Dienste starten nicht? Ports belegt oder Logs prüfen:
|
||||
```bash
|
||||
docker ps
|
||||
docker logs <container-name>
|
||||
```
|
||||
- Infrastruktur neu starten:
|
||||
```bash
|
||||
docker compose down -v
|
||||
docker compose --profile infra up -d
|
||||
```
|
||||
- Environment-Variablen: werden aus der `.env`-Datei im Root-Verzeichnis geladen.
|
||||
|
||||
## Weiterführende Hinweise
|
||||
- Architektur: `docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md`
|
||||
- ADRs: `docs/01_Architecture/adr/`
|
||||
- Aktuelle Reports: `docs/90_Reports/`
|
||||
Reference in New Issue
Block a user