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:
- Willkommen mit Wallet-Angebot
- Stempel gesammelt
- Meine Karte
- Sperrfrist („Hier hast du gerade schon gestempelt“)
- Grüner Einlöse-Screen mit Wisch-Regler
- Eingelöst mit Hinweis fürs Personal
- 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.
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 |
| API | POST /cards { centerId } (BFF setzt Cookie loop_card), POST /stamps, GET /wallet/capabilities?centerId=, POST /wallet/pass |
| Gedeckt | Kartenfortschritt (stampCount, stampsRequired), Prämientext (rewardTitle), Shopname (shopName) über card.stampCards[], Wallet-Link (appleWalletUrl, androidWalletUrl), Branding aus public-visitor-surface |
| Fehlt in der API | Die 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 Screen | Android 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ücke | Das 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) |
| API | POST /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 API | Shopname 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 Screen | Variante „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ücke | Punkte 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 |
| API | GET /cards/me → card (cardNumber, pointsBalance, stampCards[]) |
| Gedeckt | Kartennummer im Kopf, Punkte, je Shop: Name, Fortschrittsbalken, Prämie, Badge „Einlösbar“ (rewardsAvailable > 0) |
| Fehlt in der API | Shop-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 Screen | Erster 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) |
| Hinweis | Der 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 |
| API | Fehlerantwort COOLDOWN mit details.nextAllowedAt (ISO-Zeit) |
| Gedeckt | Countdown „6:12“ aus nextAllowedAt; Hinweis fürs Personal ist reiner Frontend-Text |
| Fehlt in der API | Shopname („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 Screen | Abgrenzung 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 |
| API | POST /redemptions/counter { code } → { code, expiresAt, rewardTitle, shopName, serverTime, redemptionMode }, danach POST /redemptions/counter/confirm { redemptionCode, pin? } |
| Gedeckt | Shopname, 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 API | Nichts 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 Screen | Auswahl „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) |
| API | POST /redemptions/counter/confirm → { status: 'redeemed', rewardTitle, shopId, redeemedAt, card } |
| Gedeckt | Prä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 |
| Hinweis | Der 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) |
| API | POST /stamps/gift { code, stamps, pin, reason? } |
| Gedeckt | Auswahl 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 Screen | Erfolgsansicht („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) |
| Hinweis | Das 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
| Zustand | Auslöser | Signal | Vorgabe fürs Frontend |
|---|
| Erster Besuch ohne Karte | Kein Cookie loop_card | GET /cards/me → 401 INVALID_CARD, oder BFF kennt kein Cookie | Erklärung, Button „Karte anlegen“ (POST /cards), Ladezustand |
| Karte nicht mehr bekannt | Cookie gelöscht, anderes Gerät, Karte gelöscht | 401 INVALID_CARD | Cookie löschen, neue Karte anbieten, ehrlicher Hinweis, dass der alte Stand ohne Wallet-Pass nicht wiederherstellbar ist |
| Cookies blockiert | Privates Fenster, In-App-Browser, strenger Tracking-Schutz | Karte wird angelegt, der nächste Aufruf liefert 401 | Nach 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 aus | Programm im Dashboard deaktiviert | 409 PROGRAM_INACTIVE | Seite „LOOP derzeit nicht aktiv“, keine Karte anlegen, kein Stempelversuch |
| Center ohne Stempelkarten | Noch keine aktive Karte | card.stampCards ist leer | Leerzustand „Noch keine Shops dabei“, kein Fortschrittsbalken |
| Mehrere Prämien | rewardsAvailable > 1 | Feld in card.stampCards[] | Zahl statt Badge („2 Prämien bereit“) |
| Branding fehlt | public-visitor-surface nicht erreichbar | HTTP-Fehler beim Server-Fetch | Neutrales Standard-Design, nie blockieren; Branding cachen |
| Hilfe und Rechtstexte | Besucher sucht Erklärung | /loop/hilfe, public-visitor-surface.legal | Links auf jedem Screen mit Stempel- oder Einlöse-Aktion; keine Personendaten im Hilfetext |
Stempeln
| Zustand | Auslöser | Signal | Vorgabe fürs Frontend |
|---|
| Code fehlt oder ungültig | Verstümmelte URL, Tag falsch beschrieben | 400 INVALID_INPUT oder leerer code | „Code ungültig, Tag erneut antippen“, Link zur Karte |
| Stempelpunkt nicht aktiv | Punkt deaktiviert, unbekannt, anderes Center, Shop ohne aktive Stempelkarte | 404 NOT_FOUND (alle Fälle gleich) | „Stempelpunkt nicht aktiv“, Hinweis ans Personal; das Frontend kann die Ursachen nicht unterscheiden |
| Sperrfrist | Gleiche Karte im gleichen Shop zu früh | 429 COOLDOWN, details.nextAllowedAt | Countdown (Screen 4), nach Ablauf Button „Jetzt stempeln“ |
| Rate-Limit | Zu viele Anfragen von einer IP (Stempeln 60/15 min) | 429 ohne code, Header Retry-After | Eigener Text „Zu viele Versuche, in n Sekunden erneut“, nicht mit Sperrfrist verwechseln |
| Prämie bereit | Karte voll | rewardsEarned > 0 | Variante von Screen 2 mit Weg zum Einlösen |
| Karte voll beim Antippen | rewardsAvailable > 0 und Tag getippt | Kartenlage aus card | Auswahl „Prämie einlösen“ oder „Stempel sammeln“ (Vertrag Abschnitt 5) |
| Neuladen, Zurück, Doppeltippen | Seite lädt dieselbe URL erneut | Zweiter Aufruf läuft in die Sperrfrist | Ergebnis in der Sitzung halten, code nach Verarbeitung aus der Adresse entfernen, nie automatisch erneut buchen |
| Ladezustand | Langsames Netz beim Buchen | — | Button sperren und Spinner, Buchung nicht doppelt auslösen |
Einlösen (Modus B und C)
| Zustand | Auslöser | Signal | Vorgabe fürs Frontend |
|---|
| Keine Prämie bereit | Karte nicht voll, Prämie schon verbraucht | 409 NO_REWARD | „Keine Prämie bereit“, Button „Stattdessen stempeln“ |
| Vorgang abgelaufen | Mehr als 3 Minuten | 410 CODE_EXPIRED | „Erneut starten“ (Tag erneut antippen) |
| Bereits bestätigt | Zweiter Wisch, Wiederholung nach Netzabbruch | 409 CODE_USED | Nach eigenem Wischen als Erfolg behandeln und Karte neu laden; sonst „Bereits eingelöst“ |
| Einlöse-Routen nicht verfügbar | Ältere Umgebung ohne PR #334 | 404 auf …/counter | „Einlösen ist gerade noch nicht verfügbar“, Karte bleibt nutzbar |
| Netzabbruch beim Wischen | Verbindung bricht während confirm | Netzwerkfehler, Ausgang unklar | Zustand „Wird geprüft“, GET /cards/me neu laden: rewardsAvailable gesunken = eingelöst; erneuter confirm liefert CODE_USED |
| Wisch abgebrochen | Regler vor dem Ziel losgelassen | — | Regler zurückfahren, keine Fehlermeldung; Tastatur- und Long-Press-Alternative anbieten |
| Display aus oder App im Hintergrund | Handy sperrt in den 3 Minuten | visibilitychange | Beim 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 falsch | Uhr des Handys weicht ab | — | Nur serverTime und Offset nutzen, nie die Geräteuhr anzeigen |
| Bewegung reduziert | Systemeinstellung „Bewegung reduzieren“ | prefers-reduced-motion | Screenshot-Schutz nicht aufgeben: Sekundenuhr und ruhiger Fortschrittsbalken statt Animation |
| Modus C: PIN fehlt | redemptionMode === 'counter_pin', pin nicht gesendet | 403 PIN_INVALID (kein Fehlversuch) | Wischen erst nach vollständiger PIN freigeben; Feld fokussieren |
| Modus C: PIN falsch | Falsche PIN | 403 PIN_INVALID (Fehlversuch) | Feld leeren, Hinweis, Vorgang bleibt offen (3-Minuten-Frist läuft weiter) |
| Modus C: PIN gesperrt | 5 Fehlversuche | 423 PIN_LOCKED, details.lockedUntil | „PIN bis hh:mm gesperrt“; Hinweis, dass der Center-Betrieb die PIN neu setzen kann |
| Modus C: keine PIN hinterlegt | PIN nachträglich entfernt | 409 PIN_NOT_SET | Hinweis ans Personal und Center-Betrieb; kein Wischen möglich |
Stempel verschenken (nur Personal)
| Zustand | Auslöser | Signal | Vorgabe fürs Frontend |
|---|
| Flag aus | NEXT_PUBLIC_LOOP_GIFT_ENABLED=false | — | Route liefert 404, nirgends verlinkt |
| PIN-Zustände | Falsch, nicht gesetzt, gesperrt | 403 PIN_INVALID, 409 PIN_NOT_SET, 423 PIN_LOCKED | Wie beim Einlösen im Modus C |
| Grenze erreicht | Mehr als manualGrantMaxPerAction oder Tageslimit je Shop | 422 LIMIT_REACHED, Text nennt den Rest | Hinweis mit Restmenge aus der Fehlermeldung (bis die Lese-Route aus den API-Ergänzungen existiert) |
| Einstieg | Seite 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.
| Zustand | Auslöser | Signal | Vorgabe fürs Frontend |
|---|
| iPhone (Safari) | UA ist iOS | appleWalletUrl | Button „Zu Apple Wallet hinzufügen“, öffnet den .pkpass-Dialog |
| Android | UA ist Android | androidWalletUrl | Button „Zu Google Wallet hinzufügen“ |
| Desktop, unbekanntes Gerät, In-App-Browser | Kein passender Wallet-Browser | downloadPage | Link zur Download-Seite (Passcreator) oder QR-Code zum Scannen mit dem Handy; im In-App-Browser „im Browser öffnen“ anbieten |
| Gerät nicht sicher erkennbar | UA mehrdeutig | beide URLs | Beide Buttons zeigen, den passenden hervorheben |
| Wallet aus | Im Dashboard nicht aktiviert | 409 WALLET_DISABLED (oder enabled: false) | Wallet-Button ausblenden, kein Fehler |
| Wallet nicht eingerichtet | Template-ID fehlt | 409 WALLET_NOT_CONFIGURED (oder templateConfigured: false) | Wallet-Button ausblenden |
| Provider-Fehler oder Schlüssel fehlt | Passcreator nicht erreichbar, PASSCREATOR_API_KEY fehlt | 502 oder 503 WALLET_UNAVAILABLE | Wallet ausblenden, Hinweis „später erneut“, Karte bleibt im Browser nutzbar |
| Pass noch nicht angelegt | GET /wallet/pass vor dem ersten POST | 404 WALLET_NOT_LINKED | „Pass anlegen“ anbieten (POST) |
| Pass schon hinzugefügt | Besucher hat den Pass bereits | kein Signal der API | Nach dem Hinzufügen nicht erneut anbieten (lokal merken); die API sagt nicht, ob der Pass installiert ist |
| Pass-Stand hinkt hinterher | Aktualisierung nach Stempel läuft im Hintergrund | storedValue, autoSyncOnStamp | Browser-Karte ist maßgeblich; Hinweis, dass der Pass kurz verzögert aktualisiert wird |
| Rate-Limit | Mehr als 30 Wallet-Aufrufe pro Stunde und IP | 429 ohne code | Hinweis, später erneut |
Netzwerk und Offline
| Zustand | Auslöser | Signal | Vorgabe fürs Frontend |
|---|
| Offline beim Öffnen | Kein Netz | Netzwerkfehler 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ösen | Kein Netz an der Kasse | Netzwerkfehler | Nicht 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 erreichbar | Wartung, Deploy | 502 oder 503 | „Verbindung gestört“, Erneut-versuchen, kein automatisches Polling |
| Zeitüberschreitung | Langsames Netz | Timeout im BFF | Wie 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:
| Zustand | Vorgabe |
|---|
| Passive Schleife | Folien ohne Interaktion; QR-Code zeigt auf /loop (Companion), nicht auf einen Stempelpunkt-Code |
| Keine Besucherdaten | Keine Karten-, Stempel- oder Cookie-Zugriffe, keine cardNumber; im Netzwerk-Tab nur Branding und signage-surface |
| Formate | 1920x1080 quer und 1080x1920 hoch; display=<touchscreenId> in alle internen Links mitführen |
| Notfall und Wartung | Flags aus GET /api/centers/{centerId}/signage-surface haben Vorrang vor der Schleife |
| Programm aus | Folien ohne Stempel-Werbung oder neutraler Hinweis; der QR bleibt auf /loop, wo PROGRAM_INACTIVE erklärt wird |
| Netz weg | Zuletzt geladene Folien weiterspielen, kein Spinner, kein Fehlerbild; nach Rückkehr des Netzes aktualisieren |
| Neustart des Displays | Ohne Netz nur Fallback-Folie mit Center-Branding aus dem Cache |
| Barrierefreiheit | Kontrast 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ät | Ergänzung | Löst |
|---|
| Vor Frontend-Abnahme | POST /stamps liefert zusätzlich stampCardId, shopId, shopName, serverTime | Screen 2 und 1: Welcher Shop, welche Zeit, ohne Diff-Rechnung |
| Vor Frontend-Abnahme | COOLDOWN-Fehler liefert in details zusätzlich shopName, cooldownMinutes, serverTime | Screen 4: Text und Countdown ohne Annahmen |
| Vor Frontend-Abnahme | Lese-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-Abnahme | PIN_INVALID liefert details.attemptsLeft | Screen 7: Hinweis auf verbleibende Versuche |
| Nach dem Pilot | Idempotente 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 Pilot | Einstellbarer Name der Punkte-Währung und optional Verwendungstext (Programm oder public-visitor-surface) | Screens 2 und 3: „Galerie-Punkte“ ohne Hardcoding |
| Nach dem Pilot | Shop-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)
| Thema | Stand |
|---|
| Adresse der LOOP-Anwendung | Gespeichert 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 C | requireRedeemPin je Stempelkarte, pin bei counter/confirm, redemptionMode im Public-Read (API-Vertrag) |
redemptionCodeTtlMinutes | Entfernt 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.
| Thema | Wer | Hinweis |
|---|
| Alle v0-Oberflächen (sieben Screens, Zustände oben, Signage, Hilfe) | v0-Companion-Frontend | Cockpit liefert Daten und Regeln, keine Oberfläche |
| NFC-Hardware (Tags kaufen, beschreiben, an der Kasse anbringen) | Center-Betrieb und SMG-Betrieb | Der 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 Vorhaben | Vorhanden 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 Shops | Eigene Lieferung | Architekturnotiz in Abschnitt 7 des Integrationsvertrags |
So testen
- 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“).
- Screens 1 bis 3: QR-Code scannen, Karte anlegen, Stempel prüfen,
/loop öffnen.
- Screen 4: Denselben QR-Code sofort erneut scannen: Countdown muss erscheinen, Hinweis fürs Personal sichtbar.
- 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.
- Screen 7: Mit der Laden-PIN schenken; falsche PIN, bis
PIN_LOCKED erscheint.
- Modus C: An der Stempelkarte „PIN beim Einlösen verlangen“ einschalten, Einlösen mit leerer, falscher und richtiger PIN.
- 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).