docs: update Ktor 3.4.0 migration analysis with improvements and fixes

Enhanced the migration document for Ktor 3.4.0 with structured explanations, including resource management, security updates, observability fixes, and migration checklist. Refined technical details for better clarity and compliance with recent Ktor changes.

docs/01_Architecture/Reference/TechnischeAnalyse_KtorFrameworkMigration_3-3-3_3-4-0_30-01-2026.md

@@ -91,52 +91,69 @@ implementation("io.ktor:ktor-server-routing-openapi:3.4.0")
 Tust du das nicht, wird deine Anwendung beim Start mit einer `NoClassDefFoundError` abstürzen, sobald auf Swagger
 zugegriffen wird.
 
-### 2.2 Structured Concurrency: HttpRequestLifecycle
+### 2.2 Structured Concurrency: `HttpRequestLifecycle`
-Ktor 3.4.0 führt das Plugin HttpRequestLifecycle ein.
 
-Problem in 3.3.3: Wenn ein Client die Verbindung abbrach (z.B. Browser-Tab geschlossen), lief die Verarbeitung auf dem
+Ktor 3.4.0 führt das Plugin `HttpRequestLifecycle` ein.
+
+- **Problem in 3.3.3:** Wenn ein Client die Verbindung abbrach (z.B. Browser-Tab geschlossen), lief die Verarbeitung auf
+  dem
   Server oft weiter (Datenbankabfragen, Berechnungen), was Ressourcen verschwendete.
 
-Lösung in 3.4.0: Mit diesem Plugin wird der Abbruch der TCP-Verbindung an den Kotlin-Coroutine-Scope weitergeleitet. Die
+- **Lösung in 3.4.0:** Mit diesem Plugin wird der Abbruch der TCP-Verbindung an den Kotlin-Coroutine-Scope
-Verarbeitung wird sofort abgebrochen (cancelled).
+  weitergeleitet. Die
+  Verarbeitung wird sofort abgebrochen (`cancelled`).
 
-Kotlin
+```Kotlin
 install(HttpRequestLifecycle)
+```
+
 Dies ist für deine Netty-Engine voll unterstützt.
 
-2.3 Authentifizierung & Sicherheit (ktor-server-auth-jwt, cors)
+### 2.3 Authentifizierung & Sicherheit (`ktor-server-auth-jwt`, `cors`)
-JWT Fail-Early: Wenn die JWT-Konfiguration fehlerhaft ist (z.B. fehlender Verifier), bricht der Server nun sofort beim
+
+- **JWT Fail-Early:** Wenn die JWT-Konfiguration fehlerhaft ist (z.B. fehlender Verifier), bricht der Server nun sofort
+  beim
   Start ab ("Fail-Fast"). In 3.3.3 trat der Fehler erst beim ersten Request auf, was das Debuggen in Staging/Prod
   erschwerte.
 
-CORS Fix: Ein Bug wurde behoben, bei dem OPTIONS Preflight-Requests mit 405 Method Not Allowed abgelehnt wurden, wenn
+- **CORS Fix:** Ein Bug wurde behoben, bei dem `OPTIONS` Preflight-Requests mit `405 Method Not Allowed` abgelehnt
-das CORS-Plugin innerhalb einer spezifischen route (statt global) installiert war.
+  wurden, wenn
+  das CORS-Plugin innerhalb einer spezifischen `route` (statt global) installiert war.
 
-2.4 Observability (call-logging, status-pages)
+### 2.4 Observability (`call-logging`, `status-pages`)
-MDC & Trace IDs: Ein Fehler wurde korrigiert, bei dem MDC-Kontextinformationen (wie Trace-IDs) verloren gingen, wenn
+
-innerhalb einer Route eine Exception geworfen wurde. Deine Logs sollten nun auch bei Fehlern (Stacktraces) die korrekten
+- **MDC & Trace IDs:** Ein Fehler wurde korrigiert, bei dem MDC-Kontextinformationen (wie Trace-IDs) verloren gingen,
+  wenn
+  innerhalb einer Route eine Exception geworfen wurde. Deine Logs sollten nun auch bei Fehlern (Stacktraces) die
+  korrekten
   Request-IDs enthalten.
 
-StatusPages Header: Error-Handler in StatusPages haben nun Zugriff auf die Header des OutgoingContent, was wichtig ist,
+- **StatusPages Header:** Error-Handler in `StatusPages` haben nun Zugriff auf die Header des `OutgoingContent`, was
-um korrekte Authentifizierungs-Header (z.B. WWW-Authenticate) auch im Fehlerfall zu senden.
+  wichtig ist,
+  um korrekte Authentifizierungs-Header (z.B. `WWW-Authenticate`) auch im Fehlerfall zu senden.
+
+---
+
+## 3. Checkliste für die Migration
 
-3. Checkliste für die Migration
 Hier ist ein konkreter Fahrplan für das Upgrade deiner Konfiguration:
 
-Versionen anheben: Setze die ktor Version in deinem Version-Catalog oder gradle.properties auf 3.4.0.
+- **Versionen anheben:** Setze die `ktor` Version in deinem Version-Catalog oder `gradle.properties` auf `3.4.0`.
 
-JS-Target anpassen: Suche im build.gradle.kts (Frontend) nach jsAndWasmShared und ersetze es durch web. Benenne
+- **JS-Target anpassen:** Suche im `build.gradle.kts` (Frontend) nach `jsAndWasmShared` und ersetze es durch `web`.
-entsprechende Source-Sets um (z.B. jsAndWasmSharedMain -> webMain).
+  Benenne entsprechende `Source-Sets` um (z.B. `jsAndWasmSharedMain` → `webMain`).
 
-OpenAPI fixen: Füge io.ktor:ktor-server-routing-openapi:3.4.0 explizit zu deinen Backend-Dependencies hinzu.
+- **OpenAPI fixen:** Füge `io.ktor:ktor-server-routing-openapi:3.4.0` explizit zu deinen Backend-Dependencies hinzu.
 
-Lifecycle Plugin aktivieren: Installiere das HttpRequestLifecycle Plugin in deiner Server-Initialisierung für besseres
+- **Lifecycle Plugin aktivieren:** Installiere das `HttpRequestLifecycle` Plugin in deiner Server-Initialisierung für
+  besseres
   Ressourcenmanagement.
 
-Zeit-Bibliothek prüfen: Falls du dich darauf verlassen hast, dass ktor-server-default-headers automatisch
+- **Zeit-Bibliothek prüfen:** Falls du dich darauf verlassen hast, dass `ktor-server-default-headers` automatisch
-kotlinx-datetime mitbringt: Dies wurde entfernt. Füge kotlinx-datetime ggf. explizit hinzu.
+  `kotlinx-datetime` mitbringt: Dies wurde entfernt. Füge `kotlinx-datetime` ggf. explizit hinzu.
 
-Fazit
+## Fazit
-Das Update auf Ktor 3.4.0 lohnt sich vor allem wegen der Runtime-OpenAPI-Generierung und dem besseren
+
-Ressourcenmanagement durch das Lifecycle-Plugin. Die Hürden sind primär die Umbenennung des JS-Targets und die fehlende
+Das Update auf **Ktor 3.4.0** lohnt sich vor allem wegen der **Runtime-OpenAPI-Generierung** und des **besseren
-transitive Abhängigkeit bei OpenAPI, die aber leicht manuell behoben werden kann.
+Ressourcenmanagements** durch das Lifecycle-Plugin. Die Hürden sind primär die Umbenennung des JS-Targets und die
+fehlende transitive Abhängigkeit bei OpenAPI, die aber leicht manuell behoben werden können.