Island-Mode Server

Was macht Island-Mode Server?

Ein kleiner Node-Server läuft am physischen Standort und hält eine Live-RxDB-Replikation des standortspezifischen Teils von Firestore. Während das Internet verfügbar ist, bleibt er unsichtbar; wenn das Internet ausfällt, schalten die Kiosk- und Personal-Terminals im LAN auf ihn um und der Standort kann weiterhin Bestellungen aufnehmen, Lagerbestände verwalten und Hardware steuern. Nach der Wiederherstellung der Verbindung werden die offline erfassten Änderungen zurück in die Cloud gespült. Die zentrale Erkenntnis, die alles bestimmt: Synchronisation besteht aus zwei Systemen, nicht einem – RxDB-Replikation auf Dokumentebene für den Zustand plus HTTP-Flush von Geschäftsereignissen, die die Cloud mit eigener Logik verarbeiten muss (Lagerbestandserhöhungen, Audit-Erfassung). Keines allein ist ausreichend.

Wann verwenden

• Ein Standort muss Internetausfälle mit echten Schreibvorgängen (Buchungen, Lagerbestand, Hardwaresteuerung) überstehen, nicht nur zwischengespeicherte Lesevorgänge.
• Die Terminals sind browserbasiert (PWA/Kiosk) und müssen transparent umschalten.
• Firestore ist die Cloud-Quelle der Wahrheit und bleibt es auch.

Wann NICHT verwenden

• Reines Read-Caching oder eine PWA, die nur die integrierte Offline-Persistenz von Firestore benötigt – das Firebase SDK erledigt das bereits; kein Server erforderlich.
• Eine andere Cloud-Datenbank (Supabase/Postgres): Das Konzept der Replikationsebene lässt sich übertragen, aber jede Vorlage hier ist Firestore-spezifisch.
• Multi-Master-Synchronisation zwischen Standorten untereinander – dieses Design ist strikt als Hub-and-Spoke mit der Cloud als Quelle der Wahrheit und Last-Write-Wins-Konfliktauflösung ausgelegt.

Architektur

            Internet
               |
      +--------+---------+
      | Cloud (SSoT)     |  Firestore + öffentliche API + Cron-Statusmarkierung
      +--------+---------+
        |             |
   RxDB-Replikation  HTTP-Flush (Wiederherstellung)
        |             |
      +-+-------------+-+
      | Lokaler Server   |  Node/NestJS + RxDB, LAN :443 via nginx TLS
      +--------+---------+
               |
     LAN — Kiosk-PWA, Personal-PWA, Hardware-Controller

Kritische Fakten

1. Jeder Cloud-Schreibvorgang in eine replizierte Sammlung MUSS das Prüfpunktfeld setzen (serverTimestamp: FieldValue.serverTimestamp()) und _deleted: false – das RxDB-Firestore-Plugin zieht Daten über serverTimestamp > checkpoint; ein Dokument ohne Prüfpunkt wird niemals durch die Replikation abgerufen.
2. Drei Replikationsebenen, pro Sammlung wählbar: Nur-Pull (Konfiguration, die der Standort konsumiert), bidirektional (Betriebszustand, den der Standort ändert), Nur-Push (Protokolle, die der Standort erzeugt). Die falsche Wahl der Ebene für eine Sammlung ist der häufigste Designfehler.
3. RxDB-Arbeitsspeicher-Speicherung bedeutet, dass ein Neustart im Offline-Modus alle offline erstellten Daten verliert. Das Replikat füllt sich aus Firestore neu, aber offline erstellte Dokumente sind verloren. Entscheiden Sie diesen Speicherkompromiss explizit – siehe replication.md.
4. Der Flush erfolgt mindestens einmal, daher muss die Cloud-Übernahme idempotent sein – jeden Vorgang mit der clientseitig generierten ID indizieren und bereits verarbeitete Vorgänge überspringen.
5. Push-Filter verhindern Echo: Bidirektionale Push-Vorgänge senden nur Dokumente, die mit _offlineCreated / _locallyModified gekennzeichnet sind, sodass heruntergezogene Cloud-Dokumente nicht zurückgesendet werden.
6. Terminals bevorzugen die Cloud – die Umschaltung erfolgt erst nach N aufeinanderfolgenden Fehlschlägen der Serverüberprüfung, und während des Offline-Betriebs müssen sie kontinuierlich nach dem lokalen Server suchen, nicht nur einmal beim Übergang.

Harte Regeln

Setzen Sie niemals die Cloud-Synchronisations-Endpunkte ohne Authentifizierung frei. Sie verändern Lagerbestände und fügen Bestellungen hinzu. Ein gemeinsamer Geheimnis-Header ist das Minimum.

Überprüfen Sie niemals Offline-Staff-Tokens nachsichtig, während die Verbindung aktiv ist. Der Fallback der Dekodierung ohne Verifizierung ist ein akzeptabler LAN-Kompromiss; er muss durch die tatsächliche Offline-Erkennung des Servers gesperrt werden, sonst wird die Signaturprüfung umgangen.

Setzen Sie niemals lokale Bestandsdeltas für Transaktionen zurück, die nicht als synchronisiert bestätigt wurden. Nur bei Bestätigung pro-ID zurücksetzen, sonst doppelte Zählung oder Verschwinden von Beständen.

Lassen Sie niemals zu, dass der lokale Server Geschäftsregeln erfindet, die der Cloud gehören (Öffnungszeiten, Preise). Replizieren Sie die Konfiguration und berechnen Sie daraus, sonst weicht das Island-Mode-Verhalten von der Webseite ab.

Kurzanleitung

1. Modellieren Sie Sammlungen in Ebenen und benennen Sie die Schnittstellen – architecture.md.
2. RxDB + Replikation mit benutzerdefiniertem Token-Auth und Sicherheitsregeln aufsetzen – replication.md.
3. Den Wiederherstellungs-Flush und die idempotente Cloud-Übernahme hinzufügen – sync-flush.md.
4. Die Heartbeat-/Statuskette und das Client-Failover einrichten – network-failover.md.
5. Die lokale API absichern (Staff / Kiosk / Hardware HMAC / statischer Token) – auth.md.
6. Die Cloud-Endpunkte spiegeln, die die Terminals benötigen – local-api.md.
7. Vor Ort bereitstellen: systemd, nginx TLS, mDNS, Überwachung – operations.md.

Referenzverzeichnis

Szenario	Schlüsselwörter	Referenz
Topologie, Ebenen, Schnittstellen, Umbenennungstabelle	pull-only, bidirectional, push-only, dual-path, locationId, conflict	architecture.md
Replikatsetup, Schemas, Prüfpunktfalle	RxDB, replicateFirestore, serverTimestamp, custom token, storage-memory, firestore.rules	replication.md
Wiederherstellungs-Flush, Bestandsdeltas, Übernahme	flushAll, idempotent, FieldValue.increment, localDelta, syncedIds	sync-flush.md
Ausfallerkennung und API-Umschaltung	heartbeat, lastHeartbeatAt, cron, NetworkManager, apiBaseUrl, failover	network-failover.md
Lokale API-Authentifizierung	AuthGuard, HMAC, replay window, offline JWT fallback, kiosk key	auth.md
Offline-Endpunkte und Schreibvorgänge	availability, mutex, offline booking, check-in, pricing stock filter	local-api.md
Vor-Ort-Bereitstellung und Runbook	systemd, nginx, self-signed TLS, mDNS, avahi, journalctl, rollback	operations.md
Das Protokoll: Was die Prüfung geändert, behalten, hinzugefügt hat	provenance, audit, deviations, kept deliberately	provenance.md

Weiterleitung der Vitest-Suite für die sicherheitskritische Logik (HMAC-Verifikation, Offline-Token-Dekodierung, Delta-Faltung auf echtem RxDB, Failover-Rescan): assets/behavior.test.ts – in das Zielprojekt als Regressionstests übernehmen.