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.

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)

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).

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)