Archive outdated journal logs and documents. Add Postman Runbook structure and centralize API testing documentation. Update Flyway configuration for ping-service with service-specific schema history.
This commit is contained in:
@@ -1,167 +1,18 @@
|
||||
---
|
||||
type: Guide
|
||||
status: ACTIVE
|
||||
owner: Backend Developer
|
||||
status: REDIRECT
|
||||
owner: Curator
|
||||
tags: [testing, postman, backend, api]
|
||||
last_update: 2026-03-15
|
||||
last_update: 2026-04-03
|
||||
---
|
||||
|
||||
# 🧪 Testanleitung: Ping-Service & Gateway mit Postman
|
||||
# 🧪 Testanleitung: Ping‑Service & Gateway mit Postman (Weiterleitung)
|
||||
|
||||
Diese Anleitung beschreibt, wie die Backend-Services (Gateway, Ping-Service) und die Infrastruktur (Keycloak, DB) isoliert vom Frontend getestet werden können.
|
||||
Diese Seite wurde in ein zentrales Runbook für Betriebsanleitungen überführt.
|
||||
|
||||
**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.
|
||||
Bitte nutze ab sofort das konsolidierte Runbook:
|
||||
|
||||
---
|
||||
- Runbook: API‑Tests mit Postman
|
||||
`docs/07_Infrastructure/runbooks/POSTMAN_API_Tests_Runbook.md`
|
||||
|
||||
## 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:** Der Standard-Admin User `admin` hat bereits die notwendige Rolle `MELD_USER`.
|
||||
* **Client:** Es gibt einen dedizierten Test-Client `postman-client`.
|
||||
* Client ID: `postman-client`
|
||||
* Client Secret: `postman-secret-123`
|
||||
* Access Type: `confidential`
|
||||
* Direct Access Grants: `Enabled`
|
||||
|
||||
---
|
||||
|
||||
## 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`: `postman-client`
|
||||
* `client_secret`: `postman-secret-123`
|
||||
* `username`: `admin`
|
||||
* `password`: `Admin#1234`
|
||||
|
||||
---
|
||||
|
||||
## 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}}`
|
||||
* Client Secret: `{{client_secret}}`
|
||||
* 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 |
|
||||
Hinweis: Dieser Eintrag bleibt als Verweis bestehen, damit bestehende Links nicht brechen.
|
||||
|
||||
@@ -3,7 +3,7 @@ type: Reference
|
||||
status: ACTIVE
|
||||
owner: Backend Developer
|
||||
tags: [backend, service, reference, ping]
|
||||
last_update: 2026-03-15
|
||||
last_update: 2026-04-03
|
||||
---
|
||||
|
||||
# 🎯 Ping Service Reference
|
||||
@@ -24,7 +24,7 @@ Der `ping-service` ist der **"Tracer Bullet"** (Leuchtspurgeschoss) der Meldeste
|
||||
* **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.
|
||||
* **Migration:** Flyway (mit service-spezifischer Historientabelle `flyway_schema_history_ping`).
|
||||
* **Security:** OAuth2 Resource Server (JWT via Keycloak).
|
||||
* **Resilience:** Resilience4j (Circuit Breaker).
|
||||
* **API Contract:** KMP-Modul `:contracts:ping-api` (Shared Code mit Frontend).
|
||||
|
||||
Reference in New Issue
Block a user