Stefan Mogeritsch
c086190097
Translated all remaining English architectural documents into German, including ADRs, guides, release notes, and reference materials. Standardized formatting across translated files, updated section headings, and localized inline comments within code examples for consistency.
73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
---
|
||
type: ADR
|
||
status: ACTIVE
|
||
owner: Lead Architect
|
||
---
|
||
# ADR 001: Backend-Infrastruktur & Architekturentscheidungen
|
||
|
||
**Status:** AKZEPTIERT
|
||
**Datum:** 2026-01-15
|
||
**Autor:** Lead Architect
|
||
**Kontext:** „Operation Tracer Bullet" (Phase 1) – Härtung des `ping-service`.
|
||
|
||
---
|
||
|
||
## 1. Persistenzstrategie: JPA vs. Exposed
|
||
|
||
**Entscheidung:** **Hybrider Ansatz (Command/Query-Trennung)**
|
||
* **Primär (Command/Write):** Wir verwenden **JPA (Hibernate)** für das Standard-„Write Model" in unseren Microservices.
|
||
* *Begründung:* Beste Integration mit Spring Data, Transaktionsverwaltung und Validierung. Standard für Enterprise Spring Boot.
|
||
* **Sekundär (Query/Read/Batch):** Wir erlauben **Exposed** für komplexe Leseabfragen oder Bulk-Operationen, bei denen der JPA-Overhead zu hoch ist.
|
||
* *Begründung:* Kotlin-nativ, typsichere SQL-Generierung, bessere Performance bei leselastigen Operationen.
|
||
|
||
**Maßnahmen:**
|
||
* Das Modul `backend/infrastructure/persistence` unterstützt **beide** Ansätze.
|
||
* `ping-service` verwendet primär **JPA** für seine Entitäten (`PingEntity`).
|
||
* JPA wird NICHT aus dem `ping-service` entfernt.
|
||
* Exposed wird NICHT aus `infrastructure/persistence` entfernt.
|
||
|
||
## 2. Gemeinsames Security-Modul
|
||
|
||
**Entscheidung:** **Extraktion von `backend/infrastructure/security`**
|
||
* **Begründung:** Wir folgen konsequent dem DRY-Prinzip (Don't Repeat Yourself). Die Sicherheitskonfiguration (OAuth2 Resource Server, JWT Converter, CORS, Global Method Security) ist für alle Microservices identisch.
|
||
* **Umfang:**
|
||
* `SecurityConfig`: Standard `SecurityFilterChain`.
|
||
* `KeycloakRoleConverter`: Rollen aus JWT extrahieren.
|
||
* `CorsConfig`: Zentrale CORS-Richtlinie.
|
||
|
||
**Maßnahmen:**
|
||
* `backend/infrastructure/security` erstellen.
|
||
* Sicherheitslogik aus `ping-service` (falls vorhanden) in dieses Modul verschieben.
|
||
|
||
## 3. Messaging vs. Sync-Protokoll
|
||
|
||
**Entscheidung:** **REST-basiertes Pull (Phase 1) → Kafka (Phase 3)**
|
||
* **Phase 1 (Tracer Bullet):** Für den einfachen `ping-service` wird Kafka noch NICHT verwendet.
|
||
* *Begründung:* Die „Tracer Bullet" soll einfach bleiben. Zuerst die HTTP/Auth-Kette validieren.
|
||
* **Phase 3 (Offline-Sync):** Kafka wird später für das „Outbox Pattern" eingeführt.
|
||
* *Begründung:* Zuverlässige Event-Zustellung für Offline-Clients erfordert ein dauerhaftes Log.
|
||
|
||
**Maßnahmen:**
|
||
* `reactor-kafka`-Abhängigkeit vorerst aus `ping-service` entfernen, um die Komplexität zu reduzieren.
|
||
* Fokus auf `PingEntity` (JPA) und REST-Endpunkte.
|
||
|
||
## 4. Datenbank-Migration (Flyway)
|
||
|
||
**Entscheidung:** **Datenbank pro Service (Option A)**
|
||
* **Begründung:** Autonomie der Microservices. Jeder Service besitzt sein eigenes Schema.
|
||
* **Ablageort:** `src/main/resources/db/migration` innerhalb jedes Service-Moduls.
|
||
* **Benennung:** `V{Version}__{Beschreibung}.sql` (z.B. `V1__init_ping_schema.sql`).
|
||
|
||
**Maßnahmen:**
|
||
* `ping-service` muss `V1__init.sql` enthalten.
|
||
* `spring.flyway.enabled=true` in `application.yml`.
|
||
|
||
---
|
||
|
||
## Zusammenfassung der Aufgaben für den Senior Backend Developer
|
||
|
||
1. **Persistenz:** JPA für `PingEntity` verwenden.
|
||
2. **Security:** Auf das Modul `infrastructure/security` warten (Architect erstellt Skeleton) ODER direkt im `ping-service` implementieren und später refaktorieren (bevorzugt: Architect erstellt Modul sofort).
|
||
3. **Messaging:** Kafka vorerst ignorieren.
|
||
4. **Flyway:** `V1__init.sql` im `ping-service` erstellen.
|