Offline-Modus

Dieser Leitfaden zeigt, wie das Kassensystem bei vorübergehenden Netzwerkausfällen (Verbindungsverlust zwischen dem Kassensystem und der SIGN FR API) weiter betrieben und Datensätze sicher für eine spätere Wiedergabe offline gepuffert werden können.

Im Online-Modus müssen zwei Werte aus jeder erfolgreichen createRecord-Antwort gespeichert werden: die ID des letzten Online-Datensatzes und die letzte Online-Journalisierungssignatur. Diese verankern die Offline-Daten im Server-Journal und liefern den anfänglichen kryptografischen Startwert.

Wenn die Verbindung unterbrochen wird, in den Offline-Modus wechseln. Jeden neuen Datensatz in der ursprünglichen Reihenfolge in einem dauerhaften lokalen Puffer speichern. Der Betrieb kann bis zu 24 Stunden ab dem ersten nicht gesendeten Datensatz offline fortgesetzt werden. Danach müssen neue Transaktionen eingestellt, das Kassensystem außer Betrieb gesetzt und zurückgesetzt werden.

Bei Wiederherstellung der Verbindung den Puffer wiedergeben. Jeden Datensatz in eine „Replay Intention” einwickeln, die den ursprünglichen Zeitstempel, eine verankernde Datensatz-ID und einen Startwert enthält. Für Transaktionen einen Offset hinzufügen, der die Transaktion mit der entsprechenden Intention im Puffer verknüpft.

Die Integrität durch Hashing des kanonisierten Inhalts (ohne Metadaten) mit SHA-256 sicherstellen. Den ersten Offline-Eintrag mit der letzten Online-Journalisierungssignatur als Startwert versehen und dann jeden nachfolgenden Eintrag mit dem Hash des vorherigen Datensatzes verketten.

Das Diagramm veranschaulicht den Arbeitsablauf und hebt die wesentlichen Schritte hervor, die für die erfolgreiche Handhabung des Offline-Modus und des Wiedergabeprozesses erforderlich sind.

Implementierungsdiagramm für Offline- und Wiedergabemodus

SCHRITT 1: Online-Modus

Während normaler Konnektivität müssen zwei spezifische Felder aus jeder erfolgreichen createRecord-Antwort im Kassensystem verfolgt werden: die ID des letzten Online-Datensatzes (content.id) und die Journalisierungssignatur des letzten Online-Datensatzes (content.journal.signature). Diese Werte sind unerlässlich für die Verankerung der Offline-Datensätze und die Bereitstellung des anfänglichen kryptografischen Startwerts für das Hashing.

SCHRITT 2: Ausfall – Lokale Pufferung (Speicherung)

Bei Verbindungsverlust in den Offline-Modus wechseln und jeden neuen Datensatz in der ursprünglichen Reihenfolge in einem dauerhaften lokalen Puffer speichern. Ein Kassensystem darf höchstens 24 Stunden ab dem ersten nicht gesendeten Datensatz offline betrieben werden; überschreitet der Ausfall dieses Limit, müssen neue Transaktionen eingestellt, das Kassensystem außer Betrieb gesetzt und zurückgesetzt werden. Wenn die Verbindung wiederhergestellt wird (Schritt 4), muss jeder gepufferte Datensatz in einen „Replay Intention”-Umschlag eingewickelt werden, der den ursprünglichen Zeitstempel, die verankernde Datensatz-ID und einen Startwert enthält. Für Transaktionsdatensätze muss auch ein Offset angegeben werden, der die Transaktion mit dem richtigen Intentions-Index im Puffer verknüpft. Die Datensätze in der richtigen Reihenfolge wiedergeben.

SCHRITT 3: Sicherheit – Hashing und Startwerte

Um die Datenintegrität sicherzustellen, einen SHA-256-Hash für den kanonisierten Inhalt jedes Datensatzes berechnen, wobei alle ursprünglichen Metadaten ausgeschlossen werden. Der erste Offline-Datensatz verwendet die letzte Online-Journalisierungssignatur als Startwert, während alle nachfolgenden Datensätze den Hash des vorherigen Datensatzes als Startwert verwenden. Dies erzeugt eine sichere Kette, die der Server während des Wiedergabeprozesses überprüfen kann.

SCHRITT 4: Wiederherstellung – Datensätze wiedergeben

Nach Wiederherstellung der Verbindung alle gepufferten Datensätze in ihrer ursprünglichen Reihenfolge mit dem createRecord-Endpunkt vom Typ INTENTION und operation.type REPLAY wiedergeben. Jede Anfrage muss zwei obligatorische Header-Parameter enthalten: X-Replay-Hash (der offline erstellte Base64-Hash) und X-Replay-Remaining (die Anzahl der noch im Puffer befindlichen Datensätze). Datensätze sollten erst dann aus dem lokalen Speicher gelöscht werden, nachdem der Server sie erfolgreich bestätigt hat.

SCHRITT 5: Abschluss – Rückkehr in den Online-Modus

Wenn der letzte Datensatz im Puffer eine Intention ist, muss der Händler die aufgelöste ID aus der Serverantwort erfassen, um sie als Anker für seine erste neue Online-Transaktion zu verwenden. Wenn die Verbindung während der Wiedergabe erneut abbricht, einfach in die Offline-Phase zurückwechseln und die ursprünglichen Verankerungsdaten weiter verwenden, bis der gesamte Puffer geleert wurde und eine neue Online-Antwort empfangen wurde.

Minimale Wiedergabe-Beispiele:

Header-Parameter

X-Replay-Hash: <offline computed SHA-256 hash, base64-encoded>
X-Replay-Remaining: <remaining after this one>

Intention → Transaktion (für Wiedergabe verpackt)

{
  "content": {
    "type": "INTENTION",
    "system": { "id": "0199147a-8627-7101-aecc-d2149aa99ea7" },
    "operation": {
      "type": "REPLAY",
      "recorded_at": "2025-11-14T10:30:00+01:00",
      "record": { "id": "01695553-c90c-745a-b76f-770d7b3dcb6d" },
      "seed": "<base64 seed>",
      "content": {
        "type": "TRANSACTION",
        "record": {
          "id": "019a7e09-1590-738f-aa21-8ca7b58d9ccc",
          "offset": "0"
        },
        "operation": { "type": "RECEIPT" }
      }
    }
  }
}