docs: archive outdated Ping-Service documentation and add new references

Archived obsolete Ping-Service documentation (`ping-service.md`, `PingService.md`) and replaced them with updated references (`PingService_Reference.md`, `Testing_with_Postman.md`). Improved clarity and organization of backend guides with a focus on current architecture, testing approaches, and microservice design principles. Documented the transition with a session log for traceability.
2026-01-21 14:13:34 +01:00 · 2026-01-21 14:13:34 +01:00 · a9b788aca9
commit a9b788aca9
parent 7bcf7faac9
5 changed files with 339 additions and 84 deletions
--- a/docs/05_Backend/Guides/Testing_with_Postman.md
+++ b/docs/05_Backend/Guides/Testing_with_Postman.md
@ -0,0 +1,164 @@
+---
+type: Guide
+status: ACTIVE
+owner: Backend Developer
+tags: [testing, postman, backend, api]
+---
+
+# 🧪 Testanleitung: Ping-Service & Gateway mit Postman
+
+Diese Anleitung beschreibt, wie die Backend-Services (Gateway, Ping-Service) und die Infrastruktur (Keycloak, DB) isoliert vom Frontend getestet werden können.
+
+**Voraussetzungen:**
+1.  **Infrastruktur läuft:** `docker compose --profile infra up -d` (Postgres, Keycloak, Redis, Consul).
+2.  **Backend läuft:** `docker compose --profile backend up -d` (Gateway, Ping-Service).
+3.  **Postman** ist installiert.
+
+---
+
+## 1. Vorbereitung: Keycloak User & Client
+
+Damit wir testen können, brauchen wir einen User und einen Client in Keycloak, um uns ein Token zu holen.
+
+*   **URL:** `http://localhost:8180` (oder Port aus `docker-compose logs keycloak`)
+*   **Admin Login:** `kc-admin` / `kc-password`
+*   **Realm:** Wähle oben links `meldestelle` aus (wurde beim Start importiert).
+
+**Check:**
+*   **User:** Gibt es einen User? (z.B. `testuser` / `password` mit Rolle `MELD_USER`)?
+    *   *Falls nicht:* Lege schnell einen User an, setze Credentials (temporary: off) und weise ihm unter "Role Mapping" die Rolle `MELD_USER` zu.
+*   **Client:** Gibt es einen Client? (z.B. `meldestelle-frontend` oder `postman`)?
+    *   *Falls nicht:* Lege einen Client `postman` an.
+    *   Access Type: `public` (oder `confidential` wenn du Client Secret nutzen willst, public reicht für Postman oft).
+    *   Valid Redirect URIs: `*` (für Tests ok) oder `https://oauth.pstmn.io/v1/callback`.
+
+---
+
+## 2. Postman Collection einrichten
+
+Erstelle eine neue Collection "Meldestelle Ping Test".
+
+### A. Variablen (Environment)
+Setze folgende Variablen in Postman (Environment "Local Docker"):
+*   `gateway_url`: `http://localhost:8081`
+*   `auth_url`: `http://localhost:8180/realms/meldestelle/protocol/openid-connect/token`
+*   `client_id`: `meldestelle-frontend` (oder wie dein Client heißt)
+*   `username`: `testuser` (dein User)
+*   `password`: `password` (dein Passwort)
+
+---
+
+## 3. Test-Szenarien
+
+Wir testen nun die verschiedenen Endpunkte und Sicherheitsstufen.
+
+### Szenario 1: Public Endpoints (Ohne Login)
+*Diese Requests müssen **ohne** Token funktionieren.*
+
+**1.1 Simple Ping**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/simple`
+*   **Auth:** No Auth
+*   **Erwartetes Ergebnis:**
+    *   Status: `200 OK`
+    *   Body: `{"status": "pong", "service": "ping-service", ...}`
+    *   *Bedeutung:* Gateway routet korrekt, Service ist erreichbar, DB-Schreibzugriff (Simple Ping speichert was) klappt.
+
+**1.2 Health Check**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/health`
+*   **Auth:** No Auth
+*   **Erwartetes Ergebnis:**
+    *   Status: `200 OK`
+    *   Body: `{"status": "up", "healthy": true, ...}`
+
+**1.3 Public Ping**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/public`
+*   **Auth:** No Auth
+*   **Erwartetes Ergebnis:** `200 OK`
+
+---
+
+### Szenario 2: Security Check (Negativ-Test)
+*Wir versuchen, auf geschützte Bereiche zuzugreifen, ohne eingeloggt zu sein.*
+
+**2.1 Secure Ping (Unauthenticated)**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/secure`
+*   **Auth:** No Auth
+*   **Erwartetes Ergebnis:**
+    *   Status: `401 Unauthorized`
+    *   *Bedeutung:* Gateway oder Service blockt den Request korrekt ab.
+
+**2.2 Sync Ping (Unauthenticated)**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/sync`
+*   **Auth:** No Auth
+*   **Erwartetes Ergebnis:**
+    *   Status: `401 Unauthorized` (sofern Sync auch geschützt ist).
+
+---
+
+### Szenario 3: Authenticated Endpoints (Mit Token)
+*Jetzt holen wir uns ein Token und testen die geschützten Bereiche.*
+
+**3.1 Token holen (Login)**
+*   In Postman: Tab "Authorization" -> Type "OAuth 2.0".
+*   Grant Type: `Password Credentials`
+*   Access Token URL: `{{auth_url}}`
+*   Client ID: `{{client_id}}`
+*   Username: `{{username}}`
+*   Password: `{{password}}`
+*   Klick auf "Get New Access Token".
+*   Klick auf "Use Token".
+
+**3.2 Secure Ping (Authenticated)**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/secure`
+*   **Auth:** Inherit from parent (oder OAuth 2.0 mit dem Token).
+*   **Erwartetes Ergebnis:**
+    *   Status: `200 OK`
+    *   Body: `{"status": "secure-pong", ...}`
+    *   *Bedeutung:* Token ist gültig, Signatur passt, Rolle `MELD_USER` wurde erkannt.
+
+**3.3 Sync Ping (Authenticated)**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/sync?lastSyncTimestamp=0`
+*   **Auth:** OAuth 2.0 (Token)
+*   **Erwartetes Ergebnis:**
+    *   Status: `200 OK`
+    *   Body: `[ ... Liste von Events ... ]`
+    *   *Bedeutung:* Delta-Sync funktioniert.
+
+---
+
+### Szenario 4: Resilience (Circuit Breaker)
+
+**4.1 Enhanced Ping (Normal)**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/enhanced`
+*   **Erwartetes Ergebnis:** `200 OK`
+
+**4.2 Enhanced Ping (Simulation Failure)**
+*   **Method:** `GET`
+*   **URL:** `{{gateway_url}}/api/ping/enhanced?simulate=true`
+*   **Wiederhole:** Sende den Request mehrmals schnell hintereinander.
+*   **Erwartetes Ergebnis:**
+    *   Manchmal `500 Error` (Simulation).
+    *   Nach einigen Fehlern: `200 OK` aber mit `status: "fallback"` und `circuitBreakerState: "OPEN"`.
+    *   *Bedeutung:* Resilience4j hat den Fehler erkannt und den Circuit Breaker geöffnet -> Fallback-Methode greift.
+
+---
+
+## Zusammenfassung der Checkliste
+
+| Test | URL | Auth | Erwartet |
+| :--- | :--- | :--- | :--- |
+| **Connectivity** | `/api/ping/simple` | Nein | 200 OK |
+| **Health** | `/api/ping/health` | Nein | 200 OK |
+| **Security Block** | `/api/ping/secure` | Nein | 401 Unauthorized |
+| **Auth Login** | (Keycloak Token) | - | Token erhalten |
+| **Security Access** | `/api/ping/secure` | Ja (Token) | 200 OK |
+| **Sync** | `/api/ping/sync` | Ja (Token) | 200 OK (Liste) |
+| **Resilience** | `/api/ping/enhanced?simulate=true` | Nein | Fallback Response |
--- a/docs/05_Backend/Services/PingService.md
+++ b/docs/05_Backend/Services/PingService.md
@ -1,45 +1,9 @@
-# Ping Service
+---
+type: Redirect
+status: ARCHIVED
+---

-Der `ping-service` ist der "Tracer Bullet" Service für die Meldestelle-Architektur. Er dient als Blueprint für alle weiteren Microservices.
+# MOVED

-## Verantwortlichkeit
-*   Technischer Durchstich (Frontend -> Gateway -> Service -> DB).
-*   Validierung der Infrastruktur (Security, Resilience, Observability).
-*   Referenzimplementierung für DDD, Hexagonal Architecture und KMP-Integration.
-
-## API Endpunkte
-
-| Methode | Pfad | Beschreibung | Auth |
-| :--- | :--- | :--- | :--- |
-| GET | `/ping/simple` | Einfacher Ping, speichert in DB | Public |
-| GET | `/ping/enhanced` | Ping mit Circuit Breaker Simulation | Public |
-| GET | `/ping/public` | Expliziter Public Endpoint | Public |
-| GET | `/ping/secure` | Geschützter Endpoint (benötigt Rolle) | **Secure** (MELD_USER) |
-| GET | `/ping/health` | Health Check | Public |
-| GET | `/ping/history` | Historie aller Pings | Public (Debug) |
-| GET | `/ping/sync` | Delta-Sync für Offline-Clients | Public |
-
-## Architektur
-Der Service folgt der Hexagonalen Architektur (Ports & Adapters):
-*   **Domain:** `at.mocode.ping.domain` (Pure Kotlin, keine Frameworks).
-*   **Application:** `at.mocode.ping.application` (Use Cases, Spring Service).
-*   **Infrastructure:** `at.mocode.ping.infrastructure` (Web, Persistence, Security).
-
-## Security
-*   Nutzt das zentrale Modul `backend:infrastructure:security`.
-*   OAuth2 Resource Server (JWT Validation via Keycloak).
-*   Rollen-Mapping: Keycloak Realm Roles -> Spring Security Authorities (`ROLE_...`).
-
-## Persistence
-*   Datenbank: PostgreSQL.
-*   Migration: Flyway (`V1__init_ping.sql`).
-*   ORM: Spring Data JPA (für Write Model).
-
-## Resilience
-*   Circuit Breaker: Resilience4j (für DB-Zugriffe und simulierte Fehler).
-
-## Sync-Strategie (Phase 3)
-*   Implementiert Delta-Sync via `/ping/sync`.
-*   Parameter: `lastSyncTimestamp` (Long, Epoch Millis).
-*   Response: Liste von `PingEvent` (ID, Message, LastModified).
-*   Client kann basierend auf dem Timestamp nur neue/geänderte Daten abrufen.
+This documentation has been superseded.
+Please refer to: [Ping Service Reference](PingService_Reference.md)
--- a/docs/05_Backend/Services/PingService_Reference.md
+++ b/docs/05_Backend/Services/PingService_Reference.md
@ -0,0 +1,120 @@
+---
+type: Reference
+status: ACTIVE
+owner: Backend Developer
+tags: [backend, service, reference, ping]
+---
+
+# 🎯 Ping Service Reference
+
+Der `ping-service` ist der **"Tracer Bullet"** (Leuchtspurgeschoss) der Meldestelle-Architektur. Er ist kein Wegwerf-Prototyp, sondern die **Referenzimplementierung** für alle zukünftigen Microservices.
+
+## 1. Mission & Verantwortung
+
+*   **Technischer Durchstich:** Beweist, dass die Kette *Frontend -> Gateway -> Service -> DB* funktioniert.
+*   **Blueprint:** Definiert Standards für Architektur (DDD/Hexagonal), Testing, Security und Build-Prozesse.
+*   **Infrastruktur-Validierung:** Testet die Integration mit Consul, Keycloak, Postgres, Redis und Zipkin.
+*   **Offline-First Lab:** Hier wird die Delta-Sync-Logik (`/sync`) entwickelt und validiert, bevor sie in fachliche Services einzieht.
+
+---
+
+## 2. Technologie-Stack
+
+*   **Framework:** Spring Boot 3.5.x (Spring MVC, Tomcat).
+*   **Sprache:** Kotlin 2.x (Coroutines für asynchrone Abläufe).
+*   **Datenbank:** PostgreSQL (via Spring Data JPA).
+*   **Migration:** Flyway.
+*   **Security:** OAuth2 Resource Server (JWT via Keycloak).
+*   **Resilience:** Resilience4j (Circuit Breaker).
+*   **API Contract:** KMP-Modul `:contracts:ping-api` (Shared Code mit Frontend).
+
+---
+
+## 3. Architektur (Hexagonal)
+
+Der Service folgt strikt der **Ports & Adapters** (Hexagonal) Architektur:
+
+1.  **Domain (`at.mocode.ping.domain`):**
+    *   Der Kern. Enthält Entities (`Ping`) und Business-Regeln.
+    *   Frei von Frameworks (kein Spring, kein JPA).
+    *   Definiert Interfaces für Ports (`PingRepository`).
+
+2.  **Application (`at.mocode.ping.application`):**
+    *   Orchestriert die Use Cases (`PingUseCase`).
+    *   Steuert Transaktionen (`@Transactional`).
+    *   Verbindet Domain und Infrastructure.
+
+3.  **Infrastructure (`at.mocode.ping.infrastructure`):**
+    *   **Web:** `PingController` (REST API).
+    *   **Persistence:** `PingRepositoryAdapter` (JPA Implementierung).
+    *   **Security:** Global Config für JWT-Validierung.
+
+---
+
+## 4. API Endpunkte
+
+| Methode | Pfad | Auth | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/ping/simple` | 🔓 Public | Erstellt einen Ping in der DB. Testet Schreibzugriff. |
+| `GET` | `/ping/enhanced` | 🔓 Public | Testet Circuit Breaker. Parameter `simulate=true` löst Fehler aus. |
+| `GET` | `/ping/health` | 🔓 Public | Gibt Status "UP" zurück. |
+| `GET` | `/ping/public` | 🔓 Public | Expliziter Public-Test. |
+| `GET` | `/ping/secure` | 🔒 **Secure** | Erfordert Token mit Rolle `MELD_USER`. Testet Auth-Flow. |
+| `GET` | `/ping/sync` | 🔒 **Secure** | **Delta-Sync**. Liefert Änderungen seit `lastSyncTimestamp`. |
+
+---
+
+## 5. Getting Started
+
+### A. Voraussetzungen
+*   Java 25 (oder kompatibel).
+*   Docker & Docker Compose (für Infrastruktur).
+
+### B. Infrastruktur starten
+Bevor der Service laufen kann, braucht er Datenbank und Keycloak.
+```bash
+# Im Root-Verzeichnis
+docker compose --profile infra up -d
+```
+
+### C. Starten via Gradle (Lokal)
+Ideal für Entwicklung und Debugging.
+```bash
+# Startet den Service im Profil "local"
+./gradlew :backend:services:ping:ping-service:bootRun
+```
+*   **URL:** `http://localhost:8082` (Direktzugriff)
+*   **Debug Port:** 5006
+
+### D. Starten via Docker (Integration)
+Testet den Service im Container-Verbund (hinter dem Gateway).
+```bash
+# Baut das Image und startet es zusammen mit dem Gateway
+docker compose --profile backend up -d --build
+```
+*   **URL (via Gateway):** `http://localhost:8081/api/ping/...`
+
+---
+
+## 6. Konfiguration
+
+Die Konfiguration erfolgt primär über `application.yml` und Environment-Variables (12-Factor App).
+
+| Variable | Default (Docker) | Beschreibung |
+| :--- | :--- | :--- |
+| `SERVER_PORT` | `8082` | Port des Services. |
+| `POSTGRES_DB_URL` | `jdbc:postgresql://postgres:5432/...` | JDBC URL. |
+| `SSEC_ISSUER_URI` | `http://keycloak:8080/...` | URL des Identity Providers (für Token-Check). |
+| `CONSUL_HOST` | `consul` | Host für Service Discovery. |
+
+### Profile
+*   `local`: Für lokale Entwicklung (nutzt `localhost` Adressen).
+*   `docker`: Für Betrieb im Docker-Netzwerk (nutzt Service-Namen wie `postgres`).
+*   `test`: Für Unit/Integration-Tests (nutzt H2 oder Testcontainers).
+
+---
+
+## 7. Testing
+
+*   **Unit Tests:** `./gradlew :backend:services:ping:ping-service:test`
+*   **Manuelle Tests:** Siehe [Testing with Postman](../Guides/Testing_with_Postman.md).
--- a/docs/05_Backend/Services/ping-service.md
+++ b/docs/05_Backend/Services/ping-service.md
@ -1,43 +1,9 @@
-# Ping-Service
+---
+type: Redirect
+status: ARCHIVED
+---

-Diese Seite beschreibt den **aktuellen technischen Stand** des `Ping-Service`.
-Sie ist der **stabile Einstiegspunkt** ("technische Wahrheit") für diesen Service.
+# MOVED

-Der `ping-service` dient als Health-Check-Endpunkt und als technische Blaupause für die Implementierung von Services nach den Prinzipien der Clean Architecture im "Meldestelle"-Projekt.
-
-## Architektur & Implementierung
-
-Der Service folgt einem Clean Architecture Ansatz:
-
-*   **Driving Adapter:** Der `PingController` (`infrastructure/web`) nimmt HTTP-Anfragen entgegen.
-*   **Application Port:** Das `PingUseCase` (`application`) definiert die Anwendungslogik.
-*   **Driven Adapters:** Persistenz-Adapter (nicht im Detail gezeigt) interagieren mit der Datenbank.
-
-Die Implementierung ist vollständig **asynchron** und nutzt **Kotlin Coroutines** und Spring WebFlux.
-
-## API-Definition
-
-Die API-Datenstrukturen (DTOs) und das API-Interface (`PingApi`) sind im KMP-Modul `:contracts:ping-api` definiert, um sie mit dem Frontend zu teilen.
-
-### Wichtigste Endpunkte
-
-Alle Endpunkte sind unter dem Basispfad `/` des Service-Ports (Standard: `8081`) erreichbar.
-
-*   `GET /ping/simple`:
-    *   Führt einen einfachen Ping aus, speichert das Ereignis in der Datenbank und gibt eine `PingResponse` zurück.
-*   `GET /ping/enhanced`:
-    *   Ein erweiterter Ping, der mit einem **Resilience4j Circuit Breaker** abgesichert ist.
-    *   Kann einen Fehler simulieren (`?simulate=true`).
-    *   Gibt eine `EnhancedPingResponse` mit Latenz und Circuit-Breaker-Status zurück.
-*   `GET /ping/health`:
-    *   Ein einfacher Health-Check, der den Status des Services zurückgibt (`HealthResponse`).
-*   `GET /ping/history`:
-    *   Gibt eine Liste der letzten Ping-Ereignisse aus der Datenbank zurück.
-
-### Security
-
-Die Endpunkte sind aktuell **nicht** durch Spring Security auf Service-Ebene geschützt. Die Absicherung erfolgt auf Ebene des API-Gateways.
-
-## Historie
-
-Der ursprüngliche Arbeitsauftrag zur Implementierung dieses Services ist unter `docs/90_Reports/Ping-Service_Impl_01-2026.md` zu finden, ist aber **veraltet** und spiegelt nicht mehr den aktuellen Stand wider.
+This documentation has been superseded.
+Please refer to: [Ping Service Reference](PingService_Reference.md)
--- a/docs/99_Journal/2026-01-21_Session_Log.md
+++ b/docs/99_Journal/2026-01-21_Session_Log.md
@ -0,0 +1,41 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-21
+participants:
+  - Backend Developer
+  - Lead Architect
+---
+
+# Session Log: 21. Jänner 2026
+
+## Zielsetzung
+Wissens-Transfer, Konsolidierung der Dokumentation und detaillierte Analyse der "Tracer Bullet" Architektur (Ping-Service & Infrastruktur).
+
+## Durchgeführte Arbeiten
+
+### 1. Infrastruktur & Status
+*   **Review:** Analyse der Docker-Compose Dateien (`dc-infra`, `dc-backend`, `dc-gui`, `dc-ops`) und Konfigurationen.
+*   **Report Update:** Aktualisierung des `Infrastructure_Status_Report_01-2026.md`. Bestätigung, dass die Infrastruktur Phase 1 (Hardening) und Phase 3 (Sync) erfolgreich unterstützt hat.
+*   **Anleitung:** Klärung des Start-Prozesses für das API-Gateway via Docker.
+
+### 2. Architektur-Diskussion (Deep Dive)
+*   **Ping-Service:** Definition als "Tracer Bullet" (Infrastruktur-Validierung, Blueprint, Offline-Lab).
+*   **Datenbank-Strategie:** Entscheidung für **PostgreSQL** (statt SQLite/Kafka) auch für den Ping-Service, um konsistente Patterns ("Database per Service") zu wahren.
+*   **Redis:** Bestätigung der Rolle als Cache und Infrastruktur-Store (Rate Limiting).
+*   **Security Flow:** Detaillierte Aufschlüsselung des OAuth2/OIDC Flows (Frontend -> Keycloak -> Gateway -> Service).
+
+### 3. Dokumentation (Single Source of Truth)
+*   **Neu:** Erstellung von `docs/05_Backend/Guides/Testing_with_Postman.md` als Anleitung für isolierte Backend-Tests.
+*   **Neu:** Erstellung von `docs/05_Backend/Services/PingService_Reference.md` als definitive Referenz für den Service.
+*   **Cleanup:** Archivierung veralteter Ping-Service Dokumentationen (`ping-service.md`, `PingService.md`).
+
+## Ergebnisse
+*   Das Verständnis über das Zusammenspiel der Komponenten (Docker, Auth, Service) ist vollständig synchronisiert.
+*   Die Dokumentation ist aufgeräumt und spiegelt den aktuellen technischen Stand wider.
+*   Eine klare Test-Strategie (Postman) für das Backend liegt vor.
+
+## Nächste Schritte
+*   **Backend:** Start der Modellierung der **Events Domain** (Veranstaltungen).
+*   **Frontend:** Implementierung des Login-Flows (basierend auf den Erkenntnissen dieser Session).