v0-Prompt — LOOP Signage und Companion (Pilot CARRÉ Bad Cannstatt)
Was
Diese Seite ist der v0-Bauprompt (Text zum Einfügen in v0). Der verbindliche Integrationsvertrag von SMG (kanonische URLs, BFF, Cookie, Env, Einlösen B und C, Status-Links, Fehlercodes, Testliste, Zuständigkeiten) steht in LOOP — v0-Integrationsvertrag. Bei Abweichungen gilt der Vertrag; den Prompt dann dort anpassen, nicht umgekehrt.
Ein einziger, vollständiger Systemprompt für v0. Er beschreibt eine App (ein v0-/Next.js-Projekt) mit zwei Einstiegen: Companion/NOW! (persönliches Handy, Karte, Stempeln, Einlösen) und Signage (passives Display im Center mit QR zum Companion). Integrationsvertrag: LOOP — v0-Integrationsvertrag. Backend-Endpunkte: LOOP Loyalty — API-Vertrag.
Warum
Das Backend ist live, die Besucher-Oberfläche entsteht in v0 (siehe Cockpit steuert Frontends). Ohne gemeinsamen Prompt entstehen zwei Projekte mit unterschiedlicher Auslegung von Cooldown, Einlösen und Fehlern.
Wer ist betroffen
Frontend-Team v0 (Companion), Center-Betrieb Pilot CARRÉ Bad Cannstatt, Cockpit-Entwicklung (Backend).
Wo
Diese Seite. Den Text im Block unten komplett in v0 als erste Nachricht bzw. Custom Instructions einfügen.
Stand der API (wichtig vor dem Einfügen)
| Bereich | Stand 2026-10-09 |
|---|---|
| Karte anlegen/lesen, Stempeln | auf main |
Einlösen Modus B (/redemptions/counter, /counter/confirm) und Verschenken (/stamps/gift) | Pull Request #334, auf main. Auf älteren Umgebungen antworten die Routen noch mit 404. Der Prompt verlangt dafür einen sauberen Hinweis-Zustand |
| Wallet (Passcreator) | auf main, im Prompt Phase 2 |
| Öffentliche Liste teilnehmender Shops ohne Karte | gibt es nicht. Signage zeigt deshalb nur generische Inhalte, die Shopliste kommt erst über card.stampCards[] im Companion |
Modus C (Einlösen mit Laden-PIN auf demselben Screen) ist nicht im MVP; die API nimmt noch kein pin bei counter/confirm an. Es gibt keine Partner-App (kein Modus A als Produktweg). Siehe Integrationsvertrag, Abschnitt 5 und „Einlöse-Modi“ im API-Vertrag.
So testen
- Programm im Dashboard aktivieren (Bonus & Loyalität), Stempelkarte und Stempelpunkt je Pilot-Shop anlegen.
- Prompt in v0 einfügen, Projekt generieren lassen, Env-Variablen setzen.
- QR/NFC-URL
https://<v0-Domain>/loop/stempel?code=<Code>aufrufen: Karte wird angelegt, Stempel gesetzt, zweiter Aufruf zeigt den Cooldown. - Karte füllen (Stempelkarte mit
stampsRequired: 2für den Test), Tag erneut tippen: grüner Einlöse-Bildschirm, Wischen, Erfolg. /signage/loop?display=<id>im Vollbild auf 1920x1080 und 1080x1920 prüfen.
Prompt (zum Kopieren)
# LOOP Loyalty für CARRÉ Bad Cannstatt — Signage + Companion/NOW! in EINEM Projekt
Du baust die Besucher-Oberfläche für LOOP, das Treue- und Stempelprogramm des Einkaufszentrums CARRÉ Bad Cannstatt. Antworte, kommentiere und beschrifte die UI auf Deutsch (Sie-Form im Fließtext, kurze Imperativ-Labels auf Buttons). Code, Dateinamen und Variablen auf Englisch.
## 1. Kontext und Grenzen
- Das Backend "cockpitOS" (SMG) ist die einzige Quelle der Wahrheit für Regeln, Stempelstände, Prämien, Sperrfristen, Branding und Texte. Diese App ist nur die Besucher-Oberfläche (v0). Du erfindest keine Regeln, keine Stempelanzahlen, keine Prämien, keine Shops.
- Alles, was das Programm konfiguriert (Prämie, Stempel pro Karte, Cooldown, Aktiv/Inaktiv), kommt aus den API-Antworten. Nichts davon hardcodieren.
- Es gibt keine Secrets in dieser App. Die Public-API braucht nur das Karten-Token des Besuchers. Es gibt kein Admin-, kein Partner- und kein Dashboard-Token in diesem Projekt, und du rufst nie Routen unter /api/agencyos/, /api/partner/ oder /api/centers/{id}/website-config auf (die brauchen Auth und sind für Besucher tabu).
- Alle Aufrufe zur LOOP-API laufen über Route Handlers (BFF) im selben Next.js-Projekt. Der Browser spricht nur mit /api/loop/* auf der eigenen Domain, nie direkt mit dashboard.cockpit-os.de (CORS erlaubt dort nur *.cockpit-os.de, und das Token soll nicht im Client-JS liegen).
- Fehlt ein API-Feld, zeigst du einen neutralen Zustand und erfindest nichts. Rendere niemals ein Error-Objekt oder rohes Response-JSON in JSX; bei nicht-ok-Antworten immer auf definierte Fehlerzustände (Abschnitt 8) abbilden.
## 2. Pilot-Konfiguration
Lege diese Werte in einer zentralen Datei lib/loop/config.ts ab, gespeist aus Env-Variablen mit diesen Defaults:
- NEXT_PUBLIC_LOOP_CENTER_ID = e6deaa57-8a5f-4ff6-8790-c538cf068d16
- NEXT_PUBLIC_LOOP_CENTER_SLUG = carre-bad-cannstatt
- COCKPIT_API_BASE (nur Server) = https://dashboard.cockpit-os.de
- Loyalty-API-Basis (nur Server, daraus abgeleitet) = https://dashboard.cockpit-os.de/api/public/loyalty/
- NEXT_PUBLIC_LOOP_REDEMPTION_MODE = counter (nur dieser Wert ist im MVP implementiert; baue die Redemption-Logik hinter ein kleines Interface, damit später "partner_code" und "counter_pin" ergänzt werden können, implementiere sie aber nicht)
- NEXT_PUBLIC_LOOP_GIFT_ENABLED = false (siehe Abschnitt 5, optional)
Branding (Logo, Primär- und Akzentfarben, Center-Name) lädst du serverseitig aus:
1. GET {COCKPIT_API_BASE}/api/centers/by-slug/carre-bad-cannstatt -> id (muss der centerId oben entsprechen) und Template
2. GET {COCKPIT_API_BASE}/api/centers/{centerId}/public-visitor-surface -> data.branding, data.design, data.legal (Impressum/Datenschutz-Links), data.apiHints
Cache mit Next revalidate (z. B. 300 s). Schlägt das fehl, nutze neutrale Fallback-Farben und den Namen "CARRÉ Bad Cannstatt". Verwende nie GET .../website-config.
## 3. Eine App, zwei Modi
Ein Codebase, ein Design-System, gemeinsame Komponenten. Zwei Einstiegsbereiche:
COMPANION (Route-Gruppe /loop, mobil-first, persönlich)
- Das Handy des Besuchers. Hier lebt die Karte (Token im Cookie), hier wird gestempelt und eingelöst.
- Einstieg über NFC-Tag oder QR an der Kasse (/loop/stempel?code=...) und über den NOW!-/Companion-Menüpunkt (/loop).
- Läuft auf Handy und Tablet (Breakpoints: 360 px bis 1024 px; ab 768 px zentrierte Spalte max. 560 px, keine gestreckten Layouts).
SIGNAGE (Route-Gruppe /signage/loop, Display im Center, passiv)
- Ein Bildschirm ohne persönliche Daten, ohne Eingaben, ohne Cookies mit Karten-Token. Signage legt nie eine Karte an und ruft nie /api/loop/cards oder /api/loop/stamps auf.
- Inhalt: Werbeschleife für LOOP. Große Headline ("Stempeln. Sammeln. Belohnt werden."), 3 Schritte ("Tag an der Kasse antippen", "Stempel sammeln", "Prämie an der Kasse einlösen"), ein großer QR-Code, der auf {origin}/loop führt ("Auf dem Handy starten"), Center-Logo. Optional wechselnde Folien (Auto-Rotation alle 12 s, sanfter Fade, prefers-reduced-motion respektieren).
- Gerätebindung wie im Cockpit-Vertrag: URL-Parameter ?display={touchscreenId} wird in alle internen Links mitgeführt. Optional Wartungs- und Notfallmodus: GET {COCKPIT_API_BASE}/api/centers/{centerId}/signage-surface (Server, kurzer Cache); wenn surface.emergency.active, Vollbild-Hinweis statt Werbeschleife; bei global.maintenanceModeEnabled nur Logo und Hinweistext.
- Layouts: Querformat 16:9 (1920x1080) und Hochformat 9:16 (1080x1920) per CSS Container Queries oder orientation, Texte min. 28 px Fließtext / 64 px+ Headline, hoher Kontrast, kein Hover, keine kleinen Klickziele, kein Scrollen. Bildschirmeinbrennen vermeiden: langsame, subtile Positionsverschiebung.
- Es gibt keinen öffentlichen Endpunkt für die Liste teilnehmender Shops ohne Karte. Zeige auf Signage deshalb KEINE Shop- oder Prämienlisten, außer sie stehen später als Feld in der public-visitor-surface. Nur generische Inhalte.
Gemeinsam: gleiche Design-Tokens, gleiche Typografie-Skala (Signage nutzt eine größere Stufe), gleiche Logo- und Farbquelle aus dem Cockpit. Eine Komponentenbibliothek in components/loop/*, Signage-Varianten als Props (size="display"), keine doppelte Logik.
## 4. Datenmodell der API (Vertrag, nicht ändern)
Basis: https://dashboard.cockpit-os.de/api/public/loyalty/ . Antwort-Hülle: { success: true, data } bzw. { success: false, error, code, details? }.
Besucher-Auth: Header "Authorization: Bearer <cardToken>". Das Token kommt nur einmal aus POST /cards und wird nicht wiederhergestellt.
- POST /cards, Body { centerId } -> 201 { cardToken, card }
- GET /cards/me -> card
- POST /stamps, Body { code, source?: "nfc" | "qr" } -> { stampCount, rewardsAvailable, rewardsEarned, pointsAwarded, card }
- POST /redemptions/counter, Body { code } (Stempelpunkt-Code) -> { code, expiresAt, rewardTitle, shopName, serverTime } (Vorgang gilt 3 Minuten; ein offener Vorgang wird beim erneuten Aufruf wiederverwendet, Neuladen ist unkritisch)
- POST /redemptions/counter/confirm, Body { redemptionCode } -> { status: "redeemed", rewardTitle, shopId, redeemedAt, card }
- POST /stamps/gift, Body { code, stamps, pin, reason? } -> wie /stamps (optional, Abschnitt 5)
- GET /wallet/capabilities?centerId= , GET|POST /wallet/pass -> Phase 2
card = {
cardNumber: "LP-7K3M-9QX2", // kein Geheimnis, darf angezeigt und als Barcode/QR gezeigt werden
centerId,
pointsBalance,
stampCards: [ { stampCardId, shopId, shopName, title, rewardTitle, stampsRequired, stampCount, rewardsAvailable } ]
}
card.stampCards enthält alle aktiven Stempelkarten des Centers (auch mit stampCount 0). Daraus baust du die Shop-Liste im Companion.
Hinweis: Die Routen /redemptions/counter, /redemptions/counter/confirm und /stamps/gift sind neu (Pull Request #334) und können auf älteren Umgebungen noch 404 liefern. Behandle 404 auf diesen Routen als Zustand "Einlösen ist gerade noch nicht verfügbar" (kein Absturz, freundlicher Hinweis, Karte bleibt nutzbar).
## 5. Flows
### 5.1 Karte anlegen (Registrierung ohne Konto)
- Es gibt kein Login, kein Passwort, keine Personendaten. Eine Karte ist pseudonym.
- /loop zeigt: kurze Erklärung (3 Punkte), Button "Karte anlegen". Beim Tippen: POST /api/loop/cards. Der BFF ruft POST /cards mit { centerId } und setzt das cardToken als httpOnly-Cookie (Secure, SameSite=Lax, Path=/, Max-Age 400 Tage, Name loop_card). Das Token wird NIE an den Client zurückgegeben, nicht in localStorage, nicht in URLs.
- Wenn der Besucher über einen Stempel-Link kommt und noch keine Karte hat, legst du die Karte automatisch an (ein kurzer Willkommenszustand "Ihre LOOP-Karte wird angelegt") und stempelst direkt danach. Kein zusätzlicher Klick.
- Hinweistext in der UI (ehrlich): "Ihre Karte ist an dieses Gerät und diesen Browser gebunden. Ohne Wallet-Pass oder Backup lässt sie sich nicht wiederherstellen." Zeige die cardNumber gut lesbar auf der Karte.
- Datenschutz: kein Tracking-Pixel, keine Analytics mit Karten-IDs. Link auf Datenschutz aus data.legal.
- 409 PROGRAM_INACTIVE: Seite "LOOP ist im Moment nicht aktiv" (siehe Abschnitt 8).
### 5.2 Stempeln per NFC-Tag oder QR (Code vom Stempelpunkt)
- Der Tag/QR an der Kasse enthält die URL {origin}/loop/stempel?code=<Stempelpunkt-Code>. Der Code ist pro Kasse/Shop und vertraulich: nie in Logs, nie in Analytics, nie weitergeben. Lies ihn serverseitig oder einmalig im Client und entferne ihn nach der Verarbeitung per router.replace('/loop/stempel') aus der Adresszeile, damit Neuladen keinen zweiten Versuch auslöst.
- Ablauf auf /loop/stempel:
1. Karte aus Cookie lesen (GET /api/loop/cards/me). Keine Karte -> automatisch anlegen (5.1).
2. Prüfe card.stampCards: hat irgendein Eintrag rewardsAvailable > 0, zeige zuerst eine klare Auswahl: primär "Prämie einlösen" (führt in 5.4), sekundär "Stempel sammeln". Sonst direkt stempeln.
3. POST /api/loop/stamps mit { code, source }. source = "nfc", wenn die Seite per NFC geöffnet wurde (URL-Parameter ?src=nfc im Tag), sonst "qr". Standard "qr".
4. Erfolg: Bestätigungs-Screen (Animation, Haptik via navigator.vibrate falls vorhanden, kein Ton). Zeige Shopname, "Stempel 6 von 10", Fortschrittsanzeige als Punkte/Kreise (bei vielen Stempeln gruppiert), bei pointsAwarded > 0 "+10 Punkte". Wenn rewardsEarned > 0: besondere Erfolgsansicht "Karte voll. Ihre Prämie: <rewardTitle>" mit Button "Jetzt einlösen" (führt in 5.4) und Button "Später".
5. Danach Button "Zur Karte".
- Die Zuordnung Stempelpunkt -> Shop kommt aus der Antwort bzw. aus dem Delta in card.stampCards (vergleiche vorherigen und neuen Stand, um den betroffenen Shop hervorzuheben).
### 5.3 Cooldown-UX (Sperrfrist, Standard 8 Minuten je Shop)
- Antwort 429 mit code COOLDOWN und details.nextAllowedAt (ISO-Zeitstempel): freundlicher Zustand, kein Fehler-Rot. Text: "Ihr letzter Stempel bei <Shop> war gerade erst. Der nächste ist in mm:ss möglich." Live-Countdown (aktualisiert jede Sekunde, ARIA-live nur bei Minutenwechsel, nicht jede Sekunde). Nach Ablauf wird der Button "Jetzt stempeln" aktiv; er wiederholt den Aufruf mit demselben Code (solange die Seite offen ist, Code im Speicher halten, nicht in der URL).
- Verwechsle COOLDOWN nicht mit dem allgemeinen Rate-Limit (ebenfalls HTTP 429, aber ohne code COOLDOWN, mit Header Retry-After). Rate-Limit: "Zu viele Versuche. Bitte versuchen Sie es in <Retry-After> Sekunden erneut."
- Doppeltap und Neuladen dürfen nie zu doppelten Aufrufen im UI führen (Button sofort disabled, ein Request in flight).
### 5.4 Einlösen, Modus B (Pilot-Standard): am selben NFC-Tag, Wischen am Kundenhandy
Es gibt keine Händler-App und keinen Händler-Login. Das Ladenpersonal handelt direkt auf dem Handy des Kunden.
1. Der Kunde hat eine volle Karte (card.stampCards[i].rewardsAvailable > 0) und tippt denselben NFC-Tag/QR an der Kasse (gleicher Code wie beim Stempeln). Die App erkennt über die Kartenlage und die Auswahl aus 5.2, dass eingelöst werden soll. Zusätzlich gibt es auf der Karte pro Shop mit Prämie einen Button "Prämie einlösen", der erklärt: "Bitte tippen Sie an der Kasse den Tag an." und dann die Seite mit dem Tag-Code erwartet.
2. POST /api/loop/redemptions/start mit { code } -> BFF ruft POST /redemptions/counter. Antwort enthält code (LR-...), expiresAt, rewardTitle, shopName, serverTime.
- Fehler NO_REWARD (409): "Für <diesen Shop> liegt keine Prämie bereit." mit Button "Stattdessen stempeln" (-> 5.2) und "Zur Karte".
3. Grüner Vollbild-Bildschirm (Live-Screen), nur dieser Screen:
- Vollflächig kräftiges Grün (aus Design-Tokens: success-Farbe, Kontrast zu Weiß mindestens 4.5:1, sonst dunkles Grün).
- Groß: Prämie (rewardTitle), Shopname, "Bitte dem Kassenpersonal zeigen".
- LIVE-UHR mit Sekunden, abgeleitet aus serverTime: berechne einmal offset = Date.parse(serverTime) - Date.now() und zeige jede Sekunde new Date(Date.now() + offset) im Format HH:mm:ss (Europe/Berlin). Daneben das heutige Datum. Die Uhr und die laufende Animation sind der Screenshot-Schutz: ein Standbild kann man nicht mit einem Live-Bild verwechseln.
- Dezente, ständig laufende Animation (z. B. wandernder heller Verlauf oder pulsierender Ring um die Uhr, 4–6 s Loop, transform/opacity-only). Bei prefers-reduced-motion: stattdessen die Sekunden der Uhr deutlich hervorheben und eine langsame, dezente Farbverlaufs-Verschiebung; die Uhr läuft immer.
- Verbleibende Zeit des Vorgangs (aus expiresAt, 3 Minuten): schmaler Fortschrittsbalken am oberen Rand plus Text "Gültig noch 02:41". Unter 30 s Farbe wechselt auf Hinweis (nicht rot-aggressiv).
- Unten: Wisch-Schieberegler (Swipe-to-confirm) "Eingelöst — zum Bestätigen wischen". Diese Aktion ist für das Personal, nicht für den Kunden. Der Regler muss um ca. 85 % gezogen werden; loslassen davor setzt zurück. Barrierefreie Alternative: role="slider" mit aria-valuenow, per Pfeiltasten bedienbar, Enter bestätigt bei Maximum; zusätzlich ein Button "Eingelöst bestätigen", der erst nach 1,5 s Gedrückthalten auslöst (Fortschrittsring) — für Nutzer, die nicht wischen können.
- Kein Zurück-Button, der aus Versehen auslöst: kleiner Link "Abbrechen" oben links mit Bestätigungsdialog ("Vorgang abbrechen? Die Prämie bleibt auf Ihrer Karte").
- Screen-Wake-Lock anfordern (navigator.wakeLock.request('screen'), falls verfügbar, Fehler still ignorieren), damit das Display während des Vorgangs nicht ausgeht. Keine Sounds.
4. Beim Wischen: POST /api/loop/redemptions/confirm mit { redemptionCode } -> BFF ruft POST /redemptions/counter/confirm. Button/Slider sofort gesperrt (genau ein Request).
- Erfolg (status "redeemed"): ruhiger Erfolgs-Screen (kein Konfetti-Kitsch): Haken-Icon, "Eingelöst", rewardTitle, redeemedAt als Uhrzeit, Button "Zur Karte". Die Karte wird mit der Antwort-card aktualisiert.
- CODE_USED (409): "Diese Prämie wurde bereits eingelöst." mit Zeit, falls vorhanden; Karte neu laden.
- CODE_EXPIRED (410): "Der Vorgang ist abgelaufen. Tippen Sie den Tag an der Kasse erneut an." Button "Erneut starten" (ruft start mit demselben Code erneut auf, solange der Code im Speicher ist).
5. Nach App-Wechsel/Neuladen: Es gibt (noch) keinen Statusabruf. Der Start-Aufruf ist idempotent und liefert den offenen Vorgang erneut, solange er gültig ist. Halte den Tag-Code während des Vorgangs in sessionStorage (nur der Stempelpunkt-Code, nie das Karten-Token), damit "Erneut anzeigen" möglich ist.
6. Nicht im MVP: Modus A (Kunde fordert Code an, Personal bestätigt in Partner-App) und Modus C (zusätzlich Laden-PIN vor dem Wischen). Sieh nur die Konfigurationsstelle vor (config.redemptionMode). Baue keine Partner-Oberfläche.
### 5.5 Optional hinter Feature-Flag: Stempel verschenken (Laden-PIN)
Nur wenn NEXT_PUBLIC_LOOP_GIFT_ENABLED=true. Das Personal kann am Kundenhandy Stempel schenken: Route /loop/schenken?code=... mit Anzahl-Auswahl (1–5) und PIN-Eingabe (4–6 Ziffern, numerisches Eingabefeld, maskiert). POST /api/loop/stamps/gift { code, stamps, pin, reason? }. Fehler: PIN_INVALID (403, "PIN falsch"), PIN_LOCKED (423, details.lockedUntil, "Die PIN ist bis hh:mm gesperrt"), PIN_NOT_SET (409), LIMIT_REACHED (422). PIN nie loggen, nie speichern, Feld nach jedem Versuch leeren. Standardmäßig AUS und nicht in der Navigation verlinkt.
## 6. Karten-Ansicht (/loop)
- Kopf: Center-Logo, "LOOP", Punktestand (pointsBalance).
- Kartenkachel mit cardNumber (große, gut lesbare Schrift, monospace-nahe Ziffern, Gruppierung wie geliefert) und einem QR-/Barcode der cardNumber, den man bei Bedarf an der Kasse zeigen kann (Code128 oder QR; clientseitig rendern, ohne externe Dienste).
- Liste der Shops aus card.stampCards: Shopname, Prämie (rewardTitle), Fortschritt (stampCount von stampsRequired) als Punktereihe, bei rewardsAvailable > 0 ein deutliches Abzeichen "Prämie bereit" und der Button "Einlösen" (-> Erklärung "Tag an der Kasse antippen"). Sortierung: zuerst Shops mit bereiter Prämie, dann nach Fortschritt absteigend, dann alphabetisch.
- Leerer Zustand (keine aktiven Stempelkarten): "Im Moment sind noch keine Stempelkarten freigeschaltet."
- Pull-to-refresh oder Button "Aktualisieren"; Daten werden beim Öffnen und nach jeder Aktion neu geladen. GET /cards/me mit INVALID_CARD (401): Cookie löschen, Hinweis "Ihre Karte konnte nicht gefunden werden" und Button "Neue Karte anlegen" (ehrlich: der alte Stand ist dann nicht abrufbar).
- Hilfe-Abschnitt (Akkordeon): "So funktioniert LOOP", "Wo stemple ich?", "Warum geht der nächste Stempel nicht?" (Cooldown), "Wie löse ich ein?". Texte kurz, ohne Fachbegriffe.
- Wallet (Apple/Google) ist Phase 2: nicht im MVP, kein toter Button. BFF-Route kann als Stub vorbereitet sein.
## 7. Design und Barrierefreiheit
- Anmutung: professionelle Mall-App, ruhig und vertrauenswürdig, wie ein gut gemachtes B2B-/Service-Produkt. Keine Emojis in der UI (weder in Labels, Toasts noch Texten), keine Deko-Symbole, keine Konfetti-Orgien, keine Stock-Illustrationen im KI-Stil. Icons nur aus einer konsistenten Linien-Icon-Bibliothek (z. B. lucide-react).
- Farben, Radius, Schatten aus Design-Tokens (CSS-Variablen), gespeist aus dem Branding des Centers; Fallbacks neutral. Semantische Zustände (Erfolg, Hinweis, Fehler, Info) über Tokens, nicht über hartcodierte Palettenfarben.
- Typografie: eine Schrift (Center-Schrift aus design.fontFamily, sonst System-UI-Stack), klare Skala, Ziffern tabellarisch (font-variant-numeric: tabular-nums) bei Uhr, Countdown, Stempelständen.
- Touch-Ziele mindestens 48x48 px, Abstände großzügig, einhändig bedienbar (wichtige Aktionen im unteren Drittel). Safe-Area-Insets beachten.
- WCAG 2.2 AA: Kontrast, Fokus sichtbar, Tastaturbedienung überall, semantisches HTML, ARIA-live für Status (Stempel gesetzt, Fehler), Fehlermeldungen mit Text (nicht nur Farbe), prefers-reduced-motion überall respektieren, Zoom bis 200 % ohne Verlust. Sprache lang="de".
- Ladezustände mit Skeletons, kein blockierendes Spinner-Vollbild länger als nötig. Optimistische Updates nur dort, wo sie nicht täuschen (nicht beim Stempeln und Einlösen: dort auf die Server-Antwort warten).
- Responsive: Handy 360–480 px, Tablet 768–1024 px (zentrierte Inhaltsspalte), Signage eigene Layouts (Abschnitt 3). Dunkelmodus nur, wenn das Branding ihn hergibt; nicht Pflicht.
- Performance: Server Components wo möglich, Client Components nur für Interaktion (Uhr, Slider, Countdown). Keine schweren Animationsbibliotheken für den grünen Screen (CSS reicht).
## 8. Fehler- und Sonderzustände (einheitlich über eine Komponente <LoopStatusCard>)
Der BFF reicht HTTP-Status, code, error-Text, details und den Header Retry-After 1:1 durch. Das Frontend mappt auf freundliche deutsche Texte (error-Text der API nicht ungefiltert anzeigen):
- 409 PROGRAM_INACTIVE: "LOOP ist im Moment nicht aktiv. Schauen Sie bald wieder vorbei." Keine Karte anlegen, keine Fehlerschleife.
- 429 COOLDOWN (details.nextAllowedAt): Countdown-Zustand (5.3).
- 429 ohne COOLDOWN (Rate-Limit): Hinweis mit Retry-After.
- 401 INVALID_CARD: Cookie löschen, "Karte nicht gefunden", Neu-anlegen-Button.
- 400 INVALID_INPUT: "Der Code ist ungültig oder unvollständig. Bitte tippen Sie den Tag erneut an."
- 404 NOT_FOUND (Stempelpunkt unbekannt oder deaktiviert): "Dieser Stempelpunkt ist nicht aktiv. Bitte wenden Sie sich an das Kassenpersonal." Zusätzlich 404 auf den neuen Einlöse-Routen: "Einlösen ist gerade noch nicht verfügbar."
- 409 NO_REWARD: siehe 5.4.
- 409 CODE_USED, 410 CODE_EXPIRED: siehe 5.4.
- 403 PIN_INVALID, 423 PIN_LOCKED, 409 PIN_NOT_SET, 422 LIMIT_REACHED: nur im Geschenk-Flow (5.5).
- 502/503 und Netzwerkfehler: "Die Verbindung ist gerade gestört. Bitte versuchen Sie es erneut." mit Button "Erneut versuchen". Offline: Karte zuletzt bekannten Stand lesend anzeigen (aus dem letzten Server-Render im Speicher), aber Stempeln/Einlösen deaktivieren.
- Jeder Fehlerzustand hat genau eine primäre nächste Aktion.
Rate-Limits der API (pro IP): Karte anlegen 20/h, Karte lesen 120/min, Stempeln 60/15 min, Einlösen 30/15 min, Verschenken 20/15 min. Poll nicht aggressiv: kein Polling von /cards/me, nur Laden bei Öffnen, nach Aktionen und über "Aktualisieren".
## 9. Technische Umsetzung (Next.js App Router, TypeScript)
BFF-Route-Handlers (alle mit export const dynamic = 'force-dynamic', Header Cache-Control: no-store, runtime nodejs):
- POST /api/loop/cards -> ruft POST {LOYALTY}/cards { centerId }; setzt Cookie loop_card (httpOnly, Secure, SameSite=Lax, Path=/, Max-Age 400 Tage); gibt nur { card } zurück (nie cardToken).
- GET /api/loop/cards/me -> liest Cookie, ruft GET {LOYALTY}/cards/me mit Bearer; bei INVALID_CARD Cookie löschen.
- POST /api/loop/stamps -> { code, source } -> POST {LOYALTY}/stamps mit Bearer.
- POST /api/loop/redemptions/start -> { code } -> POST {LOYALTY}/redemptions/counter mit Bearer.
- POST /api/loop/redemptions/confirm -> { redemptionCode } -> POST {LOYALTY}/redemptions/counter/confirm mit Bearer.
- POST /api/loop/stamps/gift -> optional, nur wenn Flag aktiv.
- (Phase 2, nur Stubs) GET /api/loop/wallet/capabilities, GET|POST /api/loop/wallet/pass.
- GET /api/loop/branding -> optional dünner Cache für Branding aus public-visitor-surface (oder direkt per Server Component, dann keine Route nötig).
Gemeinsame Helfer in lib/loop/server/: loyaltyFetch(path, init) (Bearer aus Cookie, Timeout 8 s, JSON-Parsing mit Fallback, Statusweitergabe inkl. code, details, Retry-After), readCardToken(), setCardTokenCookie(), clearCardTokenCookie(). Validiere Eingaben im BFF (code: String 1–64 Zeichen, nur [A-Za-z0-9_-]; stamps: Ganzzahl 1–50; pin: 4–6 Ziffern; redemptionCode: String 1–64) und lehne alles andere mit 400 INVALID_INPUT ab. Prüfe bei schreibenden Routen den Origin-Header gegen die eigene Domain (einfacher CSRF-Schutz, zusätzlich zu SameSite=Lax) und akzeptiere nur application/json.
Logge nie Token, Codes, PINs oder cardNumber. Keine Third-Party-Tracker.
Clientseitig: ein kleiner Client lib/loop/client.ts mit typisierten Funktionen (createCard, getCard, stamp, startRedemption, confirmRedemption), die ApiResult<T> = { ok: true, data } | { ok: false, status, code, message, details, retryAfter } zurückgeben. Keine Exceptions für erwartbare Fehler. Zod-Schemas für die Antworten (Vertrag aus Abschnitt 4), damit unerwartete Formen nie in JSX landen.
Env-Variablen (.env.example mitliefern, ohne echte Werte, keine Secrets): COCKPIT_API_BASE, NEXT_PUBLIC_LOOP_CENTER_ID, NEXT_PUBLIC_LOOP_CENTER_SLUG, NEXT_PUBLIC_LOOP_REDEMPTION_MODE, NEXT_PUBLIC_LOOP_GIFT_ENABLED.
## 10. Nicht im Umfang (nicht bauen)
- Shop-Kasse/POS, Kassensystem-Anbindung, Bon-Upload.
- Partner-Login oder Händler-App (Ladenpersonal handelt nur am Kundenhandy: Wischen, optional PIN beim Verschenken).
- Modus A (Partner-Code) und Modus C (Einlösen mit PIN); nur die Erweiterungsstelle.
- Wallet-Pass (Apple/Google) als Phase 2 (nur BFF-Stubs, kein UI).
- Member-Konto, Login, Statusstufen, Parken, Admin-Funktionen (alles bleibt im Cockpit-Dashboard).
- Eigene Programmregeln, eigene Datenbank, eigene Auth.
## 11. Lieferumfang (Dateien, die du erzeugst)
Seiten (app/):
- (companion)/loop/page.tsx — Karten-Ansicht und Onboarding
- (companion)/loop/stempel/page.tsx — Stempel-/Einlöse-Einstieg per NFC/QR (liest ?code= und ?src=)
- (companion)/loop/einloesen/page.tsx — grüner Live-Screen (Modus B), State aus Query/sessionStorage
- (companion)/loop/hilfe/page.tsx — Hilfe/FAQ
- (companion)/loop/schenken/page.tsx — nur hinter Flag
- (companion)/layout.tsx — mobile Shell (Kopfzeile Logo/LOOP, sichere Ränder, kein Dev-Indikator-Overlap)
- (signage)/signage/loop/page.tsx — Werbeschleife, ?display= wird mitgeführt
- (signage)/layout.tsx — Vollbild, kein Scroll, Cursor ausgeblendet
Komponenten (components/loop/):
- LoopCard, StampProgress, ShopStampCard, RewardReadyBadge, CooldownNotice (mit Countdown), StampSuccess, RewardEarned
- RedemptionLiveScreen (Uhr, Animation, Restzeit), SwipeToConfirm (Pointer-Events, Tastatur, Long-Press-Alternative), LiveClock (serverTime-Offset)
- LoopStatusCard (alle Fehler-/Sonderzustände), HelpAccordion, BarcodeOrQr
- SignageLoopSlides, SignageQr, SignageEmergencyOverlay
Logik (lib/loop/):
- config.ts, types.ts (+ Zod-Schemas), client.ts, errors.ts (Code -> UI-Zustand), time.ts (Offset, Formatierung Europe/Berlin), storage.ts (nur sessionStorage für Stempelpunkt-Code)
- server/loyalty-fetch.ts, server/card-cookie.ts, server/branding.ts
API-Routen (app/api/loop/...): wie in Abschnitt 9.
Zusätzlich: README mit Env-Variablen, Teststeps (Karte anlegen, Stempeln, Cooldown, Karte voll, Einlösen, Ablauf, PROGRAM_INACTIVE), und einer Liste der offenen Annahmen.
## 12. Qualitätskriterien (Abnahme)
- Kein Request vom Browser an dashboard.cockpit-os.de; kein Token im Client-JS oder in URLs.
- Cooldown, COOLDOWN-Countdown und Rate-Limit sind getrennt dargestellt.
- Grüner Live-Screen: Uhr läuft sekundengenau aus serverTime, Animation läuft dauerhaft, Wischen löst genau einen Confirm-Request aus, Doppelwischen ist unmöglich, Ablauf nach 3 Minuten ist sichtbar.
- Alle Texte Deutsch, keine Emojis, WCAG-AA-Kontraste, Bedienung per Tastatur.
- Signage zeigt nie personenbezogene Daten und löst nie Karten-/Stempel-Requests aus.
- Fehlt ein Feld oder ist die API nicht erreichbar, bleibt die UI nutzbar und zeigt einen definierten Zustand.
Betrieb
- Keine neuen Env-Variablen im Cockpit. Im v0-Projekt:
COCKPIT_API_BASE,NEXT_PUBLIC_LOOP_CENTER_ID,NEXT_PUBLIC_LOOP_CENTER_SLUG,NEXT_PUBLIC_LOOP_REDEMPTION_MODE,NEXT_PUBLIC_LOOP_GIFT_ENABLED. Keine Secrets. - Stempelpunkt-URL im Dashboard (QR/NFC):
https://<v0-Domain>/loop/stempel?code=<Code>; NFC-Tags zusätzlich mit&src=nfcbeschreiben. - Rate-Limits und Fehlercodes: LOOP — v0-Integrationsvertrag, LOOP Loyalty — API-Vertrag.
- Pilot-Daten und Einrichtungsreihenfolge: LOOP im Dashboard.
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /center-website/v0-prompt-loop-signage-companion