22a

Geräte & POS Bridge (Offline-Betrieb)

Wozu dient das?#

Der Bereich Geräte dient der Verwaltung, Registrierung und Absicherung aller Kassen-Terminals, Kellner-Tablets und Peripherie-Gateways (Cloud Terminal Gateway v1.4 / Station Controller). Dieses Kapitel erklärt nicht nur die Einrichtung, sondern beschreibt absolut konkret und praxisnah das genaue Verhalten des Kassensystems bei Netzwerkausfällen (Offline-Betrieb) im Gastronomiealltag.

Voraussetzungen#

• Ein eingerichteter und aktiver Standort (→ Kapitel 20 Ersteinrichtung).
• Ein einsatzbereites Endgerät (PC, Tablet oder Kassen-Hardware) im Betrieb.
• Administrator- oder Manager-Berechtigung zur Erstregistrierung neuer Kassen-Stationen.

Rollen#

• Administrator (admin): Kann neue POS-Terminals registrieren, Gateways verwalten (aktivieren, erneuern, deaktivieren), Geräte umbenennen und entkoppeln.
• Betriebsleiter (manager): Kann registrierte Geräte einsehen, aktivieren und den Online/Offline-Status prüfen.
• Servicepersonal (server): Meldet sich per PIN an bereits registrierten Terminals an; kann keine neuen Geräte registrieren.

Bildschirm für Bildschirm#

1. Bildschirm "Station aktivieren" (DeviceActivationView)#

• Kopfzeile:
  • Icon & Titel: Monitor-Icon mit Überschrift Station aktivieren.
  • Beschreibung: Bitte identifizieren Sie dieses POS-Terminal, um Bestellungen, Fiskalaufzeichnung und Belegdruck an diesem Standort zu aktivieren. (Please identify this POS terminal to enable orders, fiscal recording, and ticket printing at this location.).
• Modus A: Liste registrierter Stationen (wird angezeigt, wenn bereits Geräte existieren):
  • Gerätekarten: Zeigt Buttons für vorhandene Terminals mit Name, Icon und device_type-Badge.
  • Schaltfläche "+ Station registrieren": Mit Plus-Icon und Untertitel Neues POS-Terminal – Schaltet auf den Registrierungsmodus um.
• Modus B: Registrierungsformular:
  • Feld "Terminal-Name": Eingabefeld (Platzhalter z. B. Theke, Bar 1, Außenbereich POS / e.g. Front Counter, Bar 1, Outdoor POS).
  • Schaltfläche "Zurück zur Liste": Kehrt zur Auswahl bestehender Stationen zurück.
  • Schaltfläche "Registrierung bestätigen": Registriert das Terminal beim Backend.
• Fußzeilenleiste:
  • Systemversion: Cloud Terminal Gateway v1.4 (Cloud Terminal Gateway v1.4).
  • Systemstatus: Pulse-Punkt mit Text System bereit.

2. Geräte-Übersicht im Backoffice (DeviceListView)#

• 1 Eine Zeile je registriertem Gerät mit dem Namen des Geräts, den Sie bei der Registrierung vergeben haben.
• 2 ZULETZT GESEHEN: der Zeitpunkt des letzten Lebenszeichens (Heartbeat). Ein lange zurückliegender Wert zeigt ein Gerät, das offline ist.
• 3 Die Spaltenköpfe GERÄT, TYP, MAC und ZULETZT GESEHEN. Ist noch kein Gerät registriert, steht dort Keine Geräte an diesem Standort registriert.
• Kopfzeile:
  • Titel: Geräte.
  • Beschreibung: Registrierte Hardware an diesem Standort..
• Geräteliste / Tabelle:
  • Spalte "Gerät": Bezeichnung des Kassen-Terminals oder Gateways.
  • Spalte "Typ": Hardware-Typ (z. B. pos, device_gateway, tablet).
  • Spalte "MAC" (MAC): Hardware-MAC-Adresse des Geräts.
  • Spalte "Zuletzt gesehen": Zeitstempel der letzten Herzschlag-Verbindung (Heartbeat).

Schritt für Schritt (mit Verzweigungen)#

Pfad A: Neues Kassen-Terminal am Standort aktivieren#

1. Starten Sie die Kassen-App auf einem neuen Tablet oder Terminal. Der Bildschirm Station aktivieren erscheint.
2. Verzweigung A1 (Bestehendes Gerät wählen): Falls das Gerät bereits im Backoffice angelegt wurde, klicken Sie in der Liste auf den Karteneintrag Ihres Terminals.
3. Verzweigung A2 (Neues Gerät registrieren):
   • Klicken Sie auf Station registrieren.
   • Geben Sie unter Terminal-Name eine eindeutige Bezeichnung ein (z. B. "Bar 1 POS").
   • Klicken Sie auf Registrierung bestätigen.
4. Das Terminal wird aktiviert und schaltet automatisch auf den Kassen-Anmeldebildschirm um.

Pfad B: Umgang mit einem Internet- / Netzwerkausfall im laufenden Service#

Wenn während der Schicht das Internet ausfällt, bewahren Sie Ruhe. Das System ist nach dem Outbox-Prinzip aufgebaut:

Was funktioniert während eines Internetausfalls uneingeschränkt weiter?#

• Bestellungen & Tischverwaltung: Sie können auf allen aktiven Kassen-Terminals weiterhin Tische öffnen, Gerichte bonieren, Umbuchungen vornehmen und Zwischenrechnungen einsehen.
• Barzahlung: Bargeldzahlungen können ohne Einschränkung kassiert und Wechselgeld berechnet werden.
• Lokaler Küchen- & Bar-Druck: Solange Ihr lokales Netzwerk (LAN/WLAN) läuft, sendet der Station Controller Druckbefehle direkt an die lokale IP-Adresse der Drucker (Port 9100). Das Internet wird dafür nicht benötigt!
• Hardware-TSE Signierung: Nutzen Sie eine physische USB/SD-Hardware-TSE, erfolgt die rechtliche Signierung komplett offline direkt am Terminal.

Was ist während eines Internetausfalls eingeschränkt / gepuffert?#

• Fiskaly Cloud-TSE: Transaktionen werden lokal in die Ausfallsicherungs-Warteschlange eingereiht. Auf dem Bon wird der Hinweis auf die spätere Nachsignierung vermerkt.
• Cloud-Kartenzahlungen: Integrierte Kartenterminals, die eine Cloud-API benötigen, schlagen fehl. (Nutzen Sie Standalone-EC-Geräte mit eigener SIM/Festnetz).
• Geräteübergreifender Echtzeit-Sync: Fällt auch das lokale WLAN aus, sieht Terminal A nicht, was Terminal B boniert hat.

Was passiert nach der Wiederherstellung der Verbindung (Reconnect)?#

1. Sobald die Verbindung steht, sendet das Terminal automatisch gepufferte Ereignisse an das Backend.
2. Der Station Controller arbeitet ausstehende DeviceCommand-Einträge ab.
3. Ausstehende Cloud-TSE-Signaturen werden nachsigniert und der Status von Ausstehend auf Synchronisiert aktualisiert.

WAS DAS PERSONAL WÄHREND EINES AUSFALLS NIEMALS TUN DARF:#

CAUTION: Befolgen Sie während eines Ausfalls strikt folgende Verhaltensregeln:

1. KEINE Einstellungen ändern: Ändern Sie während eines Internetausfalls niemals den Fiskalmodus, Standorteinstellungen oder Druckerkonfigurationen.
2. KEINE Geräteregistrierung versuchen: Registrieren Sie keine neuen Terminals, da die Aktivierung die Cloud-Authentifizierung benötigt.
3. KEINE Mandanten-Resets durchführen: Versuchen Sie niemals, App-Daten zu löschen oder den Kassen-Cache zu leeren.

Pfad C: Ein Gateway (POS Bridge) einrichten, erneuern und abschalten#

Ein Gateway ist kein Benutzer. Es hat eine eigene Identität, ein Gateway-Token, das nur für dieses eine Gerät an diesem einen Standort gilt. Ein Kellner-Login kann damit weder Befehle des Gateways abholen noch Ergebnisse (Kartenzahlung, Waage, Druck) melden, und das Gateway-Token öffnet keine Kassenfunktion.

1. Registrieren: Legen Sie das Gerät mit dem Typ device_gateway im Backoffice an. Es bleibt inaktiv, bis es aktiviert wird.
2. Aktivierung: Aktivieren Sie das Gerät (Administrator oder Betriebsleiter). Die Antwort enthält einmalig das Feld gateway_token. Tragen Sie es auf dem Gateway-Rechner als TOKEN ein; Geräte-ID und Standort liest das Gateway aus dem Token. Das Token wird nirgends sonst angezeigt.
3. Erneuern: Eine erneute Aktivierung stellt ein neues Token aus. Das alte ist sofort ungültig, das Gateway meldet sich so lange mit 401 ab, bis das neue Token eingetragen ist.
4. Deaktivierung: Das Gerät abschalten (Administrator oder Betriebsleiter). Das Token verfällt sofort. Nutzen Sie das, wenn ein Gateway-Rechner ausgetauscht wird oder verloren geht.

Bestehende Gateways müssen einmal neu aktiviert werden. Eine Übergangszeit mit Benutzer-Token gibt es nicht.

Abgelehnte Offline-Bestellung#

Nach einem Ausfall meldet das Gateway die offline kassierten Verkäufe nach. Das Backend bucht eine solche Bestellung nur, wenn der Kellner ein aktiver Benutzer des Mandanten ist und an diesem Standort in der Schicht angemeldet war, und der Standort der Bestellung der des Gateways ist. Trifft das nicht zu, wird die Bestellung nicht gebucht. Sie geht aber nicht verloren: Betriebsleiter und Administrator sehen in der Kasse einen roten Hinweis Abgelehnte Offline-Bestellung mit Grund und Betrag, und die vollständigen Daten bleiben gespeichert. Das Geld ist geflossen, also muss der Vorgang von Hand geklärt werden (zum Beispiel Schicht nachtragen und den Verkauf manuell erfassen). Mit Erledigt quittieren Sie den Hinweis.

Was passiert im Hintergrund#

• Bei Ausfall der Internetverbindung speichert die Kassen-App Transaktionen im lokalen Browser-Speicher (IndexedDB/Outbox).
• Das Backend liest Befehle für den Station Controller über claim_commands ab. Welche Befehle ein Gateway bekommt, bestimmt allein sein Token. Wenn der Gateway-Dienst offline ist, verbleiben Befehle im Status QUEUED.
• Erreicht ein Befehl nach 60 Sekunden das Gateway nicht, bricht der Server mit einem Queue-Timeout ab (Command timed out waiting in queue (gateway offline / unreachable)). Das Terminal fängt diesen Zustand ab und bietet den Nachdruck an.

Häufige Probleme#

1. Device not found#

• Meldung: Device not found
• Ursache: Das Terminal versucht, Befehle unter einer Geräte-ID abzurufen, die im Backoffice gelöscht oder einem anderen Standort zugewiesen wurde.
• Lösung: Öffnen Sie den Aktivierungsbildschirm und führen Sie über Station registrieren eine erneute Registrierung durch.

2. Invalid activation code#

• Meldung: Invalid activation code
• Ursache: Bei der Manuelleingabe eines Kopplungscodes wurde ein abgelaufener oder vertauschter Code eingegeben.
• Lösung: Generieren Sie im Backoffice unter Geräte einen neuen Aktivierungscode.

3. Device command not found#

• Meldung: Device command not found
• Ursache: Das POS Gateway meldet das Ergebnis eines Druck- oder Terminalbefehls zurück, der bereits storniert oder bereinigt wurde.
• Lösung: Ignorieren Sie diese Meldung bei Wiederherstellung der Verbindung; das System synchronisiert den Folgezustand automatisch.

4. A request with this Idempotency-Key is currently in progress. Please retry after completion.#

• Meldung: A request with this Idempotency-Key is currently in progress. Please retry after completion.
• Ursache: Ein Offline-Terminal hat bei Wiederherstellung des Netzes dieselbe Transaktion doppelt an das Backend gesendet.
• Lösung: Das System schützt vor Doppelbuchungen. Warten Sie wenige Sekunden; der erste Aufruf wird verarbeitet.

5. Idempotency key reservation lost due to concurrent modification#

• Meldung: Idempotency key reservation lost due to concurrent modification
• Ursache: Zwei Kellner-Tablets haben im Offline-Betrieb gleichzeitig denselben Tisch modifiziert und nach Reconnect parallel hochgeladen.
• Lösung: Das Backend akzeptiert die erste Änderung. Aktualisieren Sie den Tischplan auf dem zweiten Tablet.

6. Idempotency key reservation lease lost due to timeout#

• Meldung: Idempotency key reservation lease lost due to timeout
• Ursache: Die Synchronisation einer komplexen Offline-Transaktion dauerte aufgrund einer instabilen Verbindung länger als das Server-Lease-Zeitfenster.
• Lösung: Wiederholen Sie den Vorgang bei stabiler Netzwerkverbindung.

7. Conflict: The order has been modified by another user.#

• Meldung: Conflict: The order has been modified by another user.
• Ursache: Ein Tisch wurde während des Netzwerkausfalls an Terminal A bearbeitet und an Terminal B zeitgleich storniert.
• Lösung: Öffnen Sie die Bestellung erneut am Kassen-Terminal, um den aktuellen Server-Zustand zu laden.

8. TSE clock reset to 1970 epoch detected. Transaction blocked until time synchronisation.#

• Meldung: TSE clock reset to 1970 epoch detected. Transaction blocked until time synchronisation.
• Ursache: Nach einem Stromausfall ist die Uhrzeit der lokalen Kassen-Hardware auf den 01.01.1970 zurückgefallen.
• Lösung: Stellen Sie sicher, dass das Endgerät mit dem Netzwerk verbunden ist, damit die Systemzeit per NTP aktualisiert werden kann.

Grenzen#

• Die Erstregistrierung eines neuen Kassen-Terminals setzt eine funktionierende Internetverbindung zum Cloud-Backend voraus.
• Bei reinem Offline-Betrieb ohne lokales WLAN ist die Echtzeit-Synchronisation zwischen mehreren Kellner-Tablets physikalisch nicht möglich.

Dieses Kapitel gehört zum Merkuron-Handbuch für Inhaber und Servicepersonal.