Skip to main content

LOOP — Screen-Map (Companion-Entwürfe)

Was​

Diese Seite legt die sieben Entwurfs-Screens des LOOP-Companions (Stand 2026-10-09) neben den v0-Integrationsvertrag und den API-Vertrag:

  1. Willkommen mit Wallet-Angebot
  2. Stempel gesammelt
  3. Meine Karte
  4. Sperrfrist („Hier hast du gerade schon gestempelt“)
  5. Grüner Einlöse-Screen mit Wisch-Regler
  6. Eingelöst mit Hinweis fürs Personal
  7. Stempel schenken mit Laden-PIN (nur Personal)

Pro Screen steht, welche Route und welche API-Felder ihn tragen, was die API nicht liefert und welche Zustände der Entwurf noch nicht zeigt. Danach folgt die vollständige Zustandsliste (Karte, Stempeln, Einlösen, Verschenken, Wallet auf iOS und Android, Netzwerk und Offline, Signage), eine Liste vorgeschlagener, rein additiver API-Ergänzungen und eine Abgrenzung, was nicht im Cockpit liegt (v0-Oberfläche, NFC-Hardware, Passcreator-Design, vollständiger Betrugsschutz).

Warum​

Die Entwürfe zeigen den Erfolgsfall. Im Pilot entscheiden aber Sonderfälle (Sperrfrist, abgelaufener Vorgang, verlorene Karte, falsche PIN), ob Ladenpersonal und Besucher dem System vertrauen. Außerdem enthalten manche Screens Texte und Zahlen, die das Frontend heute aus keiner Antwort bekommt. Wer das vorher weiß, erfindet im Frontend keine Werte (Regel aus dem Vertrag: „Cockpit ist Wahrheit“).

Wer ist betroffen​

Die Besucher-App (v0-Integration) setzt Screens und Zustände um. Cockpit-Backend entscheidet über die vorgeschlagenen API-Ergänzungen. Center-Betrieb pflegt Texte, Prämien und die Laden-PIN im Dashboard.

Wo​

Routen und Pfade kommen aus dem Integrationsvertrag, Abschnitt 2. API-Pfade sind Cockpit-Routen unter /api/public/loyalty/… (das Besucher-Frontend ruft sie über den BFF /api/loop/…). Branding (Logo, Name, Farben, Rechtstexte) kommt aus GET /api/centers/{centerId}/public-visitor-surface.

Screen 1 — Willkommen mit Wallet-Angebot​

Route/loop/stempel?code=… beim ersten Besuch (Karte wird angelegt, erster Stempel gebucht); alternativ /loop
APIPOST /cards { centerId } (BFF setzt Cookie loop_card), POST /stamps, GET /wallet/capabilities?centerId=, POST /wallet/pass
GedecktKartenfortschritt (stampCount, stampsRequired), Prämientext (rewardTitle), Shopname (shopName) über card.stampCards[], Wallet-Link (appleWalletUrl, androidWalletUrl), Branding aus public-visitor-surface
Fehlt in der APIDie Stempel-Antwort nennt nicht, welche Stempelkarte gestempelt wurde (siehe Screen 2). Beim ersten Stempel ist es die einzige mit stampCount > 0, danach nicht mehr eindeutig
Fehlt im ScreenAndroid und Desktop: nur „Apple Wallet“ ist gezeigt. androidWalletUrl und downloadPage stehen in der Antwort; das Frontend wählt nach Gerät (Details in der Wallet-Tabelle unten). Zustände WALLET_DISABLED, WALLET_NOT_CONFIGURED, WALLET_UNAVAILABLE (Button ausblenden, kein Fehler). Ladezustand beim Anlegen
Textrisiko„bekommst Hinweise zu Aktionen“: Die Wallet-Option pushNotificationOnStamp sendet eine Mitteilung nach einem Stempel, keine Aktionshinweise. Text entweder anpassen oder Aktionshinweise sind ein eigenes Feature, das es noch nicht gibt
ProduktlückeDas Karten-Token liegt nur im Cookie und ist „nicht wiederherstellbar“. Wer Cookies löscht oder das Gerät wechselt, verliert die Karte. Der Wallet-Pass ist die einzige Sicherung. Der Screen sollte das aussprechen („Karte im Wallet sichern“)

Screen 2 — Stempel gesammelt​

Route/loop/stempel (Ergebnisansicht nach dem BFF-Aufruf; code danach per router.replace aus der Adresse entfernen)
APIPOST /stamps → { stampCount, rewardsAvailable, rewardsEarned, pointsAwarded, card }
Gedeckt„7 / 10“ (stampCount, stampsRequired), „+10“ (pointsAwarded), „240“ (card.pointsBalance), „Noch 3 Stempel bis zum Gratis-Espresso“ (Rechnung aus stampsRequired - stampCount, rewardTitle)
Fehlt in der APIShopname und Stempelkarte der Buchung („Café Linde“); Zeitpunkt („heute 10:42 Uhr“, besser als serverTime statt Gerätezeit); Name der Punkte-Währung („Galerie-Punkte“, nirgends konfigurierbar, derzeit Konstante im Frontend)
Fehlt im ScreenVariante „Prämie bereit“ (rewardsEarned > 0, rewardsAvailable): Hinweis plus Weg zum Einlösen. Mehrere Prämien gleichzeitig („2 Prämien bereit“). Seite neu laden oder Zurück darf nicht erneut buchen und nicht in die Sperrfrist laufen: Ergebnis im Speicher der Sitzung halten, nicht aus der URL ableiten
ProduktlückePunkte lassen sich sammeln, aber es gibt keine Einlösung und keinen Katalog für Punkte. Der Screen zeigt den Stand prominent. Das Team muss festlegen, wofür Punkte gelten, sonst wirkt die Zahl leer

Screen 3 — Meine Karte​

Route/loop
APIGET /cards/me → card (cardNumber, pointsBalance, stampCards[])
GedecktKartennummer im Kopf, Punkte, je Shop: Name, Fortschrittsbalken, Prämie, Badge „Einlösbar“ (rewardsAvailable > 0)
Fehlt in der APIShop-Logo oder Farbe je Stempelkarte (nur Name); Name der Punkte-Währung; Kartennummer als Barcode ist Frontend-Sache (cardNumber, Format LP-XXXX-XXXX)
Fehlt im ScreenErster Besuch ohne Karte (Erklärung, Button „Karte anlegen“, Zustand INVALID_CARD nach gelöschtem Cookie). Center ohne Stempelkarten oder Programm aus (PROGRAM_INACTIVE). rewardsAvailable > 1. Wallet-Button (GET /wallet/pass, bei WALLET_NOT_LINKED mit POST anlegen). „Aktualisieren“ statt Polling. Links zu Hilfe (/loop/hilfe) und Rechtstexten (public-visitor-surface.legal)
HinweisDer Fußtext „Zum Stempeln oder Einlösen einfach an der Kasse an den Aufsteller tippen“ ist richtig. Einlösen startet nur über den Stempelpunkt-Code, nicht aus dieser Liste

Screen 4 — Sperrfrist​

Route/loop/stempel bei 429 COOLDOWN
APIFehlerantwort COOLDOWN mit details.nextAllowedAt (ISO-Zeit)
GedecktCountdown „6:12“ aus nextAllowedAt; Hinweis fürs Personal ist reiner Frontend-Text
Fehlt in der APIShopname („Bei Café Linde“), Länge der Sperrfrist („alle 8 Minuten“; aus dem Programm, stampCooldownMinutes, nicht öffentlich), Serverzeit für einen korrekten Countdown (nur der HTTP-Header Date bleibt; der BFF muss ihn durchreichen)
Fehlt im ScreenAbgrenzung zum Rate-Limit (ebenfalls 429, aber ohne code, mit Header Retry-After: eigener Text „Zu viele Versuche“). Zustand nach Ablauf des Countdowns („Jetzt wieder stempeln“, Button, der erneut mit dem Code bucht; der Code ist dann nicht mehr in der Adresse)

Screen 5 — Grüner Einlöse-Screen​

Route/loop/einloesen
APIPOST /redemptions/counter { code } → { code, expiresAt, rewardTitle, shopName, serverTime, redemptionMode }, danach POST /redemptions/counter/confirm { redemptionCode, pin? }
GedecktShopname, Prämie, Live-Uhr aus serverTime, Restzeit „Gilt noch 2:41 Min.“ aus expiresAt minus serverTime, Wisch-Regler. Modus C: redemptionMode === 'counter_pin' zeigt das PIN-Feld über dem Regler (Wischen erst nach vollständiger PIN)
Fehlt in der APINichts für den Erfolgsfall. Die Antwort auf confirm unterscheidet nicht, ob ein zweiter Aufruf der eigene Wiederholungsversuch oder ein fremder war (siehe Zustände)
Fehlt im ScreenAuswahl „Prämie einlösen / Stempel sammeln“, wenn eine volle Karte den Tag antippt (Vertrag Abschnitt 5, Schritt 1). CODE_EXPIRED („Erneut starten“), CODE_USED, NO_REWARD, 404 auf den Einlöse-Routen („noch nicht verfügbar“). Netzwerkfehler während confirm: Der Erfolg ist unklar; ein erneuter Aufruf liefert dann CODE_USED, obwohl die Prämie bereits eingelöst wurde. Vorschlag: Frontend behandelt CODE_USED nach eigenem Wischen als Erfolg und lädt die Karte neu. Wisch-Regler-Fehlversuch (loslassen vor dem Ziel). Modus C (PIN-Feld über dem Regler): im Entwurf nicht gezeichnet, API-seitig umgesetzt (siehe unten)

Screen 6 — Eingelöst​

Route/loop/einloesen (Ergebnisansicht)
APIPOST /redemptions/counter/confirm → { status: 'redeemed', rewardTitle, shopId, redeemedAt, card }
GedecktPrämie, Zeitpunkt (redeemedAt), Shopname über card.stampCards[] mit shopId, neuer Kartenstand aus card
Fehlt im Screen„Neue Karte gestartet“ gilt nur, wenn danach stampCount = 0. Bei Überhang (Karte war über voll) oder weiterer Prämie (rewardsAvailable > 0) braucht der Text eine andere Variante
HinweisDer Personal-Hinweis („erst jetzt die Prämie ausgeben“) ist die einzige Kontrolle vor Ort. Ein Screenshot des grünen Screens ist wegen Live-Uhr und Animation erkennbar; es gibt keine zusätzliche Prüfnummer

Screen 7 — Stempel schenken (nur Personal)​

Route/loop/schenken?code=… (hinter Flag NEXT_PUBLIC_LOOP_GIFT_ENABLED, nicht verlinkt)
APIPOST /stamps/gift { code, stamps, pin, reason? }
GedecktAuswahl 1 bis 5 (Grenze im Programm: manualGrantMaxPerAction, Standard 5), PIN-Eingabe, Hinweis „Nach 5 falschen Versuchen 15 Minuten gesperrt“ (feste Werte im Backend)
Fehlt in der API„Heute noch 17 von 20 geschenkten Stempeln“: Rest je Shop und Tag ist nirgends lesbar (nur als Fehlertext bei LIMIT_REACHED). Die Obergrenze je Vorgang (1 bis 5) steht ebenfalls nicht in einer Public-Antwort, das Frontend müsste sie raten. Anzahl PIN-Ziffern: Die API erlaubt 4 bis 6, der Screen zeigt 4 Felder; das Frontend muss ein Feld mit bis zu 6 Ziffern zulassen oder die Länge mit dem Center-Betrieb festlegen. Verbleibende Versuche stehen nicht in PIN_INVALID
Fehlt im ScreenErfolgsansicht („3 Stempel geschenkt“, neuer Stand). PIN_INVALID, PIN_NOT_SET („für diesen Shop ist keine PIN hinterlegt“), PIN_LOCKED mit details.lockedUntil („gesperrt bis hh:mm“), LIMIT_REACHED. Einstieg: Wie gelangt das Personal auf diese Seite, wenn sie nicht verlinkt ist? Offen: bewusster Einstieg (z. B. verdeckter Link oder eigener NFC-Tag-Parameter)
HinweisDas Personal tippt die PIN vor dem Kunden ein. Das ist bewusst „Link statt Konto“ ohne Gerät, schützt die PIN aber nur durch Begrenzung (5 Fehlversuche, 15 Minuten Sperre). Die PIN sollte regelmäßig gewechselt werden (Dashboard, Stempelkarten)

Vollständige Zustandsliste​

Keiner der sieben Entwürfe zeigt diese Fälle. Die Fehlercodes stehen im Integrationsvertrag, Abschnitt 8. Das Frontend mappt code auf eigene deutsche Texte und zeigt error nie ungefiltert. Jeder Zustand braucht einen ruhigen, zum Design passenden Screen oder Hinweis; Fehler-Rot nur dort, wo der Besucher etwas ändern muss (nicht bei COOLDOWN).

Karte und Einstieg​

ZustandAuslöserSignalVorgabe fürs Frontend
Erster Besuch ohne KarteKein Cookie loop_cardGET /cards/me → 401 INVALID_CARD, oder BFF kennt kein CookieErklärung, Button „Karte anlegen“ (POST /cards), Ladezustand
Karte nicht mehr bekanntCookie gelöscht, anderes Gerät, Karte gelöscht401 INVALID_CARDCookie löschen, neue Karte anbieten, ehrlicher Hinweis, dass der alte Stand ohne Wallet-Pass nicht wiederherstellbar ist
Cookies blockiertPrivates Fenster, In-App-Browser, strenger Tracking-SchutzKarte wird angelegt, der nächste Aufruf liefert 401Nach dem Anlegen prüfen, ob der Folgeaufruf klappt; sonst Hinweis „Cookies erlauben oder im Browser öffnen“, keine Endlosschleife von Karten (Rate-Limit 20/h)
Programm ausProgramm im Dashboard deaktiviert409 PROGRAM_INACTIVESeite „LOOP derzeit nicht aktiv“, keine Karte anlegen, kein Stempelversuch
Center ohne StempelkartenNoch keine aktive Kartecard.stampCards ist leerLeerzustand „Noch keine Shops dabei“, kein Fortschrittsbalken
Mehrere PrämienrewardsAvailable > 1Feld in card.stampCards[]Zahl statt Badge („2 Prämien bereit“)
Branding fehltpublic-visitor-surface nicht erreichbarHTTP-Fehler beim Server-FetchNeutrales Standard-Design, nie blockieren; Branding cachen
Hilfe und RechtstexteBesucher sucht Erklärung/loop/hilfe, public-visitor-surface.legalLinks auf jedem Screen mit Stempel- oder Einlöse-Aktion; keine Personendaten im Hilfetext

Stempeln​

ZustandAuslöserSignalVorgabe fürs Frontend
Code fehlt oder ungültigVerstümmelte URL, Tag falsch beschrieben400 INVALID_INPUT oder leerer code„Code ungültig, Tag erneut antippen“, Link zur Karte
Stempelpunkt nicht aktivPunkt deaktiviert, unbekannt, anderes Center, Shop ohne aktive Stempelkarte404 NOT_FOUND (alle Fälle gleich)„Stempelpunkt nicht aktiv“, Hinweis ans Personal; das Frontend kann die Ursachen nicht unterscheiden
SperrfristGleiche Karte im gleichen Shop zu früh429 COOLDOWN, details.nextAllowedAtCountdown (Screen 4), nach Ablauf Button „Jetzt stempeln“
Rate-LimitZu viele Anfragen von einer IP (Stempeln 60/15 min)429 ohne code, Header Retry-AfterEigener Text „Zu viele Versuche, in n Sekunden erneut“, nicht mit Sperrfrist verwechseln
Prämie bereitKarte vollrewardsEarned > 0Variante von Screen 2 mit Weg zum Einlösen
Karte voll beim AntippenrewardsAvailable > 0 und Tag getipptKartenlage aus cardAuswahl „Prämie einlösen“ oder „Stempel sammeln“ (Vertrag Abschnitt 5)
Neuladen, Zurück, DoppeltippenSeite lädt dieselbe URL erneutZweiter Aufruf läuft in die SperrfristErgebnis in der Sitzung halten, code nach Verarbeitung aus der Adresse entfernen, nie automatisch erneut buchen
LadezustandLangsames Netz beim Buchen—Button sperren und Spinner, Buchung nicht doppelt auslösen

Einlösen (Modus B und C)​

ZustandAuslöserSignalVorgabe fürs Frontend
Keine Prämie bereitKarte nicht voll, Prämie schon verbraucht409 NO_REWARD„Keine Prämie bereit“, Button „Stattdessen stempeln“
Vorgang abgelaufenMehr als 3 Minuten410 CODE_EXPIRED„Erneut starten“ (Tag erneut antippen)
Bereits bestätigtZweiter Wisch, Wiederholung nach Netzabbruch409 CODE_USEDNach eigenem Wischen als Erfolg behandeln und Karte neu laden; sonst „Bereits eingelöst“
Einlöse-Routen nicht verfügbarÄltere Umgebung ohne PR #334404 auf …/counter„Einlösen ist gerade noch nicht verfügbar“, Karte bleibt nutzbar
Netzabbruch beim WischenVerbindung bricht während confirmNetzwerkfehler, Ausgang unklarZustand „Wird geprüft“, GET /cards/me neu laden: rewardsAvailable gesunken = eingelöst; erneuter confirm liefert CODE_USED
Wisch abgebrochenRegler vor dem Ziel losgelassen—Regler zurückfahren, keine Fehlermeldung; Tastatur- und Long-Press-Alternative anbieten
Display aus oder App im HintergrundHandy sperrt in den 3 MinutenvisibilitychangeBeim Zurückkehren Uhr und Restzeit aus serverTime und expiresAt neu berechnen, bei Ablauf CODE_EXPIRED-Zustand; Bildschirm wach halten, wo der Browser es erlaubt
Geräteuhr falschUhr des Handys weicht ab—Nur serverTime und Offset nutzen, nie die Geräteuhr anzeigen
Bewegung reduziertSystemeinstellung „Bewegung reduzieren“prefers-reduced-motionScreenshot-Schutz nicht aufgeben: Sekundenuhr und ruhiger Fortschrittsbalken statt Animation
Modus C: PIN fehltredemptionMode === 'counter_pin', pin nicht gesendet403 PIN_INVALID (kein Fehlversuch)Wischen erst nach vollständiger PIN freigeben; Feld fokussieren
Modus C: PIN falschFalsche PIN403 PIN_INVALID (Fehlversuch)Feld leeren, Hinweis, Vorgang bleibt offen (3-Minuten-Frist läuft weiter)
Modus C: PIN gesperrt5 Fehlversuche423 PIN_LOCKED, details.lockedUntil„PIN bis hh:mm gesperrt“; Hinweis, dass der Center-Betrieb die PIN neu setzen kann
Modus C: keine PIN hinterlegtPIN nachträglich entfernt409 PIN_NOT_SETHinweis ans Personal und Center-Betrieb; kein Wischen möglich

Stempel verschenken (nur Personal)​

ZustandAuslöserSignalVorgabe fürs Frontend
Flag ausNEXT_PUBLIC_LOOP_GIFT_ENABLED=false—Route liefert 404, nirgends verlinkt
PIN-ZuständeFalsch, nicht gesetzt, gesperrt403 PIN_INVALID, 409 PIN_NOT_SET, 423 PIN_LOCKEDWie beim Einlösen im Modus C
Grenze erreichtMehr als manualGrantMaxPerAction oder Tageslimit je Shop422 LIMIT_REACHED, Text nennt den RestHinweis mit Restmenge aus der Fehlermeldung (bis die Lese-Route aus den API-Ergänzungen existiert)
EinstiegSeite ist nicht verlinkt—Offen: bewusster Einstieg (verdeckter Link oder eigener NFC-Tag-Parameter)

Wallet auf iOS und Android​

GET /wallet/capabilities?centerId= sagt, ob Wallet im Center nutzbar ist. POST /wallet/pass legt den Pass an oder aktualisiert ihn, GET /wallet/pass liest einen bereits verknüpften Pass. Die Antwort enthält appleWalletUrl, androidWalletUrl und downloadPage.

ZustandAuslöserSignalVorgabe fürs Frontend
iPhone (Safari)UA ist iOSappleWalletUrlButton „Zu Apple Wallet hinzufügen“, öffnet den .pkpass-Dialog
AndroidUA ist AndroidandroidWalletUrlButton „Zu Google Wallet hinzufügen“
Desktop, unbekanntes Gerät, In-App-BrowserKein passender Wallet-BrowserdownloadPageLink zur Download-Seite (Passcreator) oder QR-Code zum Scannen mit dem Handy; im In-App-Browser „im Browser öffnen“ anbieten
Gerät nicht sicher erkennbarUA mehrdeutigbeide URLsBeide Buttons zeigen, den passenden hervorheben
Wallet ausIm Dashboard nicht aktiviert409 WALLET_DISABLED (oder enabled: false)Wallet-Button ausblenden, kein Fehler
Wallet nicht eingerichtetTemplate-ID fehlt409 WALLET_NOT_CONFIGURED (oder templateConfigured: false)Wallet-Button ausblenden
Provider-Fehler oder Schlüssel fehltPasscreator nicht erreichbar, PASSCREATOR_API_KEY fehlt502 oder 503 WALLET_UNAVAILABLEWallet ausblenden, Hinweis „später erneut“, Karte bleibt im Browser nutzbar
Pass noch nicht angelegtGET /wallet/pass vor dem ersten POST404 WALLET_NOT_LINKED„Pass anlegen“ anbieten (POST)
Pass schon hinzugefügtBesucher hat den Pass bereitskein Signal der APINach dem Hinzufügen nicht erneut anbieten (lokal merken); die API sagt nicht, ob der Pass installiert ist
Pass-Stand hinkt hinterherAktualisierung nach Stempel läuft im HintergrundstoredValue, autoSyncOnStampBrowser-Karte ist maßgeblich; Hinweis, dass der Pass kurz verzögert aktualisiert wird
Rate-LimitMehr als 30 Wallet-Aufrufe pro Stunde und IP429 ohne codeHinweis, später erneut

Netzwerk und Offline​

ZustandAuslöserSignalVorgabe fürs Frontend
Offline beim ÖffnenKein NetzNetzwerkfehler im BFF-Aufruf„Verbindung gestört“ mit Erneut-versuchen; zuletzt geladene Karte nur als Anzeige, klar als „Stand von …“ gekennzeichnet
Offline beim Stempeln oder EinlösenKein Netz an der KasseNetzwerkfehlerNicht lokal puffern: Stempel und Einlösung brauchen die Server-Prüfung. Hinweis „Bitte mit Netz erneut antippen“; der Code bleibt nur im Tag, nicht im Gerät
Cockpit nicht erreichbarWartung, Deploy502 oder 503„Verbindung gestört“, Erneut-versuchen, kein automatisches Polling
ZeitüberschreitungLangsames NetzTimeout im BFFWie nicht erreichbar; bei confirm wie „Netzabbruch beim Wischen“
Kein Polling——GET /cards/me nur beim Öffnen, nach Aktionen und über „Aktualisieren“

Signage (/signage/loop)​

Es gibt noch keinen Entwurf. Vorgaben für das v0-Projekt:

ZustandVorgabe
Passive SchleifeFolien ohne Interaktion; QR-Code zeigt auf /loop (Companion), nicht auf einen Stempelpunkt-Code
Keine BesucherdatenKeine Karten-, Stempel- oder Cookie-Zugriffe, keine cardNumber; im Netzwerk-Tab nur Branding und signage-surface
Formate1920x1080 quer und 1080x1920 hoch; display=<touchscreenId> in alle internen Links mitführen
Notfall und WartungFlags aus GET /api/centers/{centerId}/signage-surface haben Vorrang vor der Schleife
Programm ausFolien ohne Stempel-Werbung oder neutraler Hinweis; der QR bleibt auf /loop, wo PROGRAM_INACTIVE erklärt wird
Netz wegZuletzt geladene Folien weiterspielen, kein Spinner, kein Fehlerbild; nach Rückkehr des Netzes aktualisieren
Neustart des DisplaysOhne Netz nur Fallback-Folie mit Center-Branding aus dem Cache
BarrierefreiheitKontrast und Schriftgröße für Abstand, kein Ton

Vorgeschlagene API-Ergänzungen (nicht umgesetzt)​

Alle rein additiv (neue Felder oder neue Lese-Route). Stand: Vorschlag, noch nicht entschieden.

PrioritätErgänzungLöst
Vor Frontend-AbnahmePOST /stamps liefert zusätzlich stampCardId, shopId, shopName, serverTimeScreen 2 und 1: Welcher Shop, welche Zeit, ohne Diff-Rechnung
Vor Frontend-AbnahmeCOOLDOWN-Fehler liefert in details zusätzlich shopName, cooldownMinutes, serverTimeScreen 4: Text und Countdown ohne Annahmen
Vor Frontend-AbnahmeLese-Route für das Verschenken, z. B. GET /stamps/gift/limits?code= mit { shopName, maxPerAction, remainingToday, pinRequired, pinLength, lockedUntil } (mit Karten-Token)Screen 7: Obergrenze, Rest „17 von 20“, PIN-Länge, Sperrstatus vor der Eingabe
Vor Frontend-AbnahmePIN_INVALID liefert details.attemptsLeftScreen 7: Hinweis auf verbleibende Versuche
Nach dem PilotIdempotente Antwort bei erneutem confirm derselben Karte (status: 'redeemed' mit alreadyRedeemed: true) oder GET /redemptions/counter/{code}Screen 5 und 6: Netzwerkabbruch während des Wischens
Nach dem PilotEinstellbarer Name der Punkte-Währung und optional Verwendungstext (Programm oder public-visitor-surface)Screens 2 und 3: „Galerie-Punkte“ ohne Hardcoding
Nach dem PilotShop-Logo je Stempelkarte in card.stampCards[]Screen 3: Wiedererkennung

Jede Ergänzung braucht in derselben Lieferung: Dashboard oder Konfig-Quelle (wo ein Wert pflegbar sein soll), Public-Read, MCP-Hints und Doku (Regel „Cockpit steuert Frontends“).

Was das Cockpit inzwischen trägt (0.1.654)​

ThemaStand
Adresse der LOOP-AnwendungGespeichert je Center im Programm (visitorAppBaseUrl), Dashboard (Programm und Stempelpunkte), AgencyOS und MCP; QR-Dialog nutzt sie
Einrichtungs-PrüflisteÜbersicht /dashboard/loyalty zeigt „Bereit für Besucher“ (Pflicht: Programm, Karte, Punkt, Zuordnung, Adresse; Empfehlung: Laden-PIN, Wallet)
Modus CrequireRedeemPin je Stempelkarte, pin bei counter/confirm, redemptionMode im Public-Read (API-Vertrag)
redemptionCodeTtlMinutesEntfernt aus API und Antwort; Senden führt zu 400 (Einlösen gilt fest 3 Minuten)

Nicht Teil des Cockpits​

Diese Punkte liegen außerhalb dieser Lieferung. Sie sind hier genannt, damit niemand sie im Cockpit erwartet.

ThemaWerHinweis
Alle v0-Oberflächen (sieben Screens, Zustände oben, Signage, Hilfe)v0-Companion-FrontendCockpit liefert Daten und Regeln, keine Oberfläche
NFC-Hardware (Tags kaufen, beschreiben, an der Kasse anbringen)Center-Betrieb und SMG-BetriebDer Tag enthält die Stempelpunkt-URL aus dem Dashboard; Tag-Typ und Beschreiben sind Betrieb, kein Cockpit-Feature
Wallet-Pass-Design (Logo, Farben, Layout)Passcreator (Template dort)Cockpit pflegt nur Template-ID und Sync (Epic im Projektstand)
Vollständiger Betrugsschutz (mehrere Karten pro Gerät oder IP, Sammelbetrug, Geräteerkennung)Offen, eigenes VorhabenVorhanden sind Sperrfrist je Karte und Shop, Rate-Limits je IP, Tageslimit und PIN-Sperre beim Verschenken, 3-Minuten-Frist beim Einlösen und Kennzahlen. Es gibt keine Erkennung mehrerer Karten pro Person oder Gerät
Status-Links ohne Login für ShopsEigene LieferungArchitekturnotiz in Abschnitt 7 des Integrationsvertrags

So testen​

  1. Programm aktivieren, Stempelkarte (mit Laden-PIN) und Stempelpunkt anlegen, Adresse der LOOP-Anwendung im Dashboard speichern (Prüfliste in der Übersicht zeigt „Bereit für Besucher“).
  2. Screens 1 bis 3: QR-Code scannen, Karte anlegen, Stempel prüfen, /loop öffnen.
  3. Screen 4: Denselben QR-Code sofort erneut scannen: Countdown muss erscheinen, Hinweis fürs Personal sichtbar.
  4. Screens 5 und 6: Karte mit stampsRequired: 2 füllen, Tag erneut scannen, Einlösen wählen, wischen. Danach zweiter Versuch: CODE_USED. Drei Minuten warten und wischen: CODE_EXPIRED.
  5. Screen 7: Mit der Laden-PIN schenken; falsche PIN, bis PIN_LOCKED erscheint.
  6. Modus C: An der Stempelkarte „PIN beim Einlösen verlangen“ einschalten, Einlösen mit leerer, falscher und richtiger PIN.
  7. Zustände: Programm im Dashboard ausschalten, Stempelpunkt deaktivieren, Cookie löschen, Handy in den Flugmodus, Wallet im Dashboard ausschalten und auf iPhone und Android prüfen.

Betrieb​

Keine neuen Umgebungsvariablen. Die Screen-Texte pflegt das Frontend; Prämien, Stempelanzahl, Sperrfrist, Limits, Laden-PIN und die Adresse der LOOP-Anwendung pflegt das Cockpit (LOOP im Dashboard).

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/loop-v0-screen-map