feat(realtime): implement SSE fallback, dual-transport hub & proxy resilience (resolves FLAW-03)

Doku/api/websocket.md

@@ -114,10 +114,57 @@ Vor Version 2.1 nutzte MindSift ein serverseitiges Lease-Locking mit 30-Sekunden
 
 ---
 
-## 🔄 5. Fallback-Strategie & Reconnect
+## 🔄 5. Fallback-Strategie & Proxy-Resilienz (Dual-Transport Architektur)
 
-In strikten Firmennetzwerken oder bei Proxy-Problemen (z.B. fehlende `Upgrade`-Header bei HTTP/1.1) kann eine WebSocket-Verbindung fehlschlagen:
+In restriktiven Firmennetzwerken, hinter Unternehmens-Proxies (z.B. Zscaler, BlueCoat) oder fehlerhaft konfigurierten Reverse-Proxies wird der `Upgrade: websocket`-Header häufig verworfen (`NS_ERROR_CONNECTION_REFUSED`, Code 1006 / 1002 / 1008). 
+
+MindSift löst dieses Problem durch eine **vollwertige Dual-Transport-Architektur** ([FLAW-03](../flaws.md)):
+
+```
+                                  ┌───────────────────────────────┐
+                                  │      MindSift Frontend        │
+                                  └───────────────┬───────────────┘
+                                                  │
+                            ┌─────────────────────┴─────────────────────┐
+                            ▼                                           ▼
+                 Standard: WebSockets                        Fallback: SSE + REST
+            (wss://.../api/v1/ws)                       (https://.../api/v1/events)
+                            │                                           │
+                            │  [Proxy Upgrade Block (Code 1006/Timeout)]│
+                            │ ────────────────────────────────────────> │
+                            ▼                                           ▼
+               ┌────────────────────────┐                  ┌────────────────────────┐
+               │    Gorilla WS Conn     │                  │  Server-Sent Events    │
+               │   Bidirektionaler      │                  │  (text/event-stream)   │
+               │    TCP-WebSocket       │                  │  Standard HTTPS Port   │
+               └────────────┬───────────┘                  └────────────┬───────────┘
+                            │                                           │
+                            └─────────────────────┬─────────────────────┘
+                                                  ▼
+                                   ┌─────────────────────────────┐
+                                   │       Realtime Hub          │
+                                   │   (Multiplexing WS & SSE)   │
+                                   └─────────────────────────────┘
+```
+
+### 1. Automatischer SSE-Fallback (`GET /api/v1/events`)
+- Scheitert der WebSocket-Handshake oder blockiert ein Proxy das Upgrade, wechselt MindSift innerhalb von 3,5 Sekunden automatisch auf einen **Server-Sent Events (SSE) Stream**.
+- Da SSE ein standardmäßiger HTTP/1.1- bzw. HTTP/2-GET-Request über Standard-Port 443/80 ist (`Content-Type: text/event-stream`), wird er von jedem Proxy und jeder Firewall ungehindert durchgeleitet.
+- Header `X-Accel-Buffering: no` und `Cache-Control: no-cache` verhindern Pufferung im Proxy; periodische Ping-Kommentare (`: ping\n\n`) alle 15 Sekunden halten Timeouts fern.
+- Der Client bleibt dadurch **vollständig echtzeitfähig** (`Live (SSE)`).
+
+### 2. REST-Endpunkte für Upstream-Aktionen im SSE-Modus
+Da SSE unidirektional (Server ➔ Client) ist, stellt MindSift für Schreibvorgänge im SSE-Modus REST-Äquivalente bereit:
+- `PUT /api/v1/documents/:id/crdt`: Unterstützt sowohl volles `state` (Compaction) als auch inkrementelles `update` (Delta). Der Hub persistiert das Update und broadcastet es sofort an alle anderen WS- und SSE-Clients im Dokumentenraum.
+- `POST /api/v1/documents/:id/awareness`: Überträgt Cursor- und Blockfokus-Präsenzen.
+- `DELETE /api/v1/documents/:id/awareness`: Informiert Peers beim Verlassen des Dokuments.
+- `POST /api/v1/events/rooms`: Erlaubt SSE-Clients, Dokument- oder Listenräumen dynamisch beizutreten (`join`) oder sie zu verlassen (`leave`).
+
+### 3. Verbindungs-Indikator
+- **Grün pulsierend:** Live verbunden über WebSockets (`Live (WebSocket)`).
+- **Türkis pulsierend:** Live verbunden über Server-Sent Events (`Live (Server-Sent Events / Proxy-Stream)`).
+- **Gelb/Amber:** Temporäre Unterbrechung mit automatischem HTTP-Polling-Schutz.
+
+Ausführliche Konfigurationsbeispiele für Nginx, Traefik, Caddy, Cloudflare und Apache finden sich im separaten Handbuch:
+👉 **[Reverse-Proxy-Konfigurationshandbuch](../reverse-proxy.md)**
 
-1. **Exponentielles Backoff:** Das Frontend ([`frontend/src/lib/api.ts`](../../frontend/src/lib/api.ts)) versucht automatisch die Wiederverbindung nach 1s, 2s, 4s, 8s, bis maximal 30s.
-2. **HTTP-Polling Fallback:** Geteilte Listen und Notizen aktivieren im Hintergrund ein periodisches Polling (5s Intervall), falls der WebSocket-Status nicht `CONNECTED` ist.
-3. **Status-Indikator:** Ein dezenter grüner bzw. gelber Indikator oben rechts im Header zeigt dem Benutzer jederzeit den aktuellen Live-Verbindungsstatus an.