From a9b788aca9296d836c9a8a1f097c80be5aa1a7ae Mon Sep 17 00:00:00 2001 From: Stefan Mogeritsch Date: Wed, 21 Jan 2026 14:13:34 +0100 Subject: [PATCH] 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. --- .../05_Backend/Guides/Testing_with_Postman.md | 164 ++++++++++++++++++ docs/05_Backend/Services/PingService.md | 50 +----- .../Services/PingService_Reference.md | 120 +++++++++++++ docs/05_Backend/Services/ping-service.md | 48 +---- docs/99_Journal/2026-01-21_Session_Log.md | 41 +++++ 5 files changed, 339 insertions(+), 84 deletions(-) create mode 100644 docs/05_Backend/Guides/Testing_with_Postman.md create mode 100644 docs/05_Backend/Services/PingService_Reference.md create mode 100644 docs/99_Journal/2026-01-21_Session_Log.md diff --git a/docs/05_Backend/Guides/Testing_with_Postman.md b/docs/05_Backend/Guides/Testing_with_Postman.md new file mode 100644 index 00000000..3bd5cca7 --- /dev/null +++ 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 | diff --git a/docs/05_Backend/Services/PingService.md b/docs/05_Backend/Services/PingService.md index 05ea3921..8bd82fc1 100644 --- 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) diff --git a/docs/05_Backend/Services/PingService_Reference.md b/docs/05_Backend/Services/PingService_Reference.md new file mode 100644 index 00000000..a761f2e2 --- /dev/null +++ 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). diff --git a/docs/05_Backend/Services/ping-service.md b/docs/05_Backend/Services/ping-service.md index 8ff5193f..8bd82fc1 100644 --- 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) diff --git a/docs/99_Journal/2026-01-21_Session_Log.md b/docs/99_Journal/2026-01-21_Session_Log.md new file mode 100644 index 00000000..552c91dd --- /dev/null +++ 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).