Footfall-API: Live-Anbindung & Simulator

Das Dashboard lädt Footfall zentral über GET /api/analytics/footfall?centerId=<uuid>.
Die Auflösung folgt der Reihenfolge Live → Simulator → leer — ohne verstreute Hardcoded-Mocks.

Datenmodus (global)

Modus	Verhalten
live	Nur echte Partner-/Sensor-Daten (wenn Env konfiguriert)
simulator	Deterministische Demo-Zahlen (Center + Datum als Seed)
off	Keine simulierten Daten — leere Zustände wenn Live fehlt

Priorität: COCKPIT_DATA_MODE (Env) → IntegrationConfig (service: cockpit-data-mode) → Default (simulator, wenn keine Live-Footfall-Env).

• API: GET /api/system/data-mode, PATCH nur SUPER_ADMIN
• UI: Karte „Daten-Simulator“ auf /dashboard/analytics/footfall
• KPIs: GET /api/analytics/footfall/summary?centerId=<uuid> (Admin-Dashboard-Kacheln)

# Optional: Env-Override (sperrt UI-Toggle)
COCKPIT_DATA_MODE=simulator   # live | simulator | off

Bereits im Code

Baustein	Pfad
Typen (inkl. Zonen)	apps/dashboard/src/lib/analytics/footfall/types.ts
Zentrale Auflösung	resolve-footfall.ts → resolveFootfallData, getFootfallKpis
Simulator	simulator.ts → buildSimulatedFootfallPayload
Datenmodus	apps/dashboard/src/lib/data-mode/
Env + Live-Stub	integration.ts → fetchLiveFootfall
Partner → Payload	map-partner-response.ts
API-Routen	footfall/route.ts, footfall/summary/route.ts
UI	FootfallIntegrationStatusAlert, DataSimulatorSettings, DataSourceBadge, footfall-charts.tsx

Legacy mock-footfall-data.ts bleibt nur für Tests — nicht für Produktion.

Env Footfall-Partner (Server, optional)

FOOTFALL_PROVIDER=none    # später: http
FOOTFALL_API_BASE_URL=      # Basis-URL des Anbieters
FOOTFALL_API_KEY=           # API-Key / Token
FOOTFALL_API_TIMEOUT_MS=15000

Die Route setzt integration in der JSON-Antwort (Provider, ob URL/Key gesetzt, Hinweistext).

API-Antwort

{
  "success": true,
  "source": "simulator",
  "dataMode": "simulator",
  "liveDataAvailable": false,
  "data": { "summary": { ... }, "centers": [ ... ], "hourlyToday": [ ... ], "weeklyTrend": [ ... ], "monthlyTrend": [ ... ], "zones": [ ... ], "weekdayHeatmap": [ ... ] }
}

source: live | simulator | unavailable

Wenn die API-Spec da ist

1. Response-Typ in PartnerFootfallRawResponse (map-partner-response.ts) anpassen.
2. fetchLiveFootfallHttp in integration.ts — implementiert: GET {FOOTFALL_API_BASE_URL}/centers/{centerId}/footfall?date=today, Mapping über mapPartnerFootfallToPayload.
3. Route liefert automatisch source: "live", liveDataAvailable: true (Vorrang vor Simulator).

Zonen (Bereiche)

FootfallApiPayload.zones ist optional:

{ zoneId, name, visitors, dwellMinutes?, conversionPercent? }

Der Simulator liefert Beispiel-Zonen; Live-Partner kann eigene Zonen mappen.

Trends & Heatmap (Payload)

Optional in FootfallApiPayload (Simulator liefert alle Felder für das primäre Center):

Feld	Beschreibung
weeklyTrend	7 Tage: { date, label, visitors }
monthlyTrend	12 Monate: { date, label, visitors }
weekdayHeatmap	7×14 Gitter: Wochentag × Stunde (08:00–21:00)
zones	Bereiche mit visitors, optional dwellMinutes, conversionPercent

UI: Reiter Übersicht, Trends und Heatmap auf /dashboard/analytics/footfall (footfall-charts.tsx).

Center-Mapping (später, DB)

Expand-only Vorschlag (noch nicht migriert):

• ShoppingCenter.footfallProvider (nullable)
• ShoppingCenter.footfallExternalId (nullable)

Bis dahin: globales Env oder Mapping in integration.ts.

Consumer (alle über dieselbe Auflösung)

Consumer	Pfad / API
Footfall-Dashboard	/dashboard/analytics/footfall → GET /api/analytics/footfall
Analytics-Übersicht, Admin-Kacheln	GET /api/analytics/footfall/summary
Center-Manager Apps	GET /api/center-manager/apps
Center-Manager Daten & Config	GET /api/center-manager/data, GET /api/center-manager/config
Reports, Sales, HQ-Cockpit, AI-Assistent	Client-Hook useFootfallSummary → /summary
Data-Business-Cockpit	FootfallStreamStatus

Umschalten: PATCH /api/system/data-mode oder Toggle auf der Footfall-Seite. Live-Partner (FOOTFALL_API_*) hat immer Vorrang.

Verwandt

• Analytics-Integration
• Analytics Dashboard (Nutzer)