Shopify-Stores

Zweck

Shopify-Stores verbinden einen externen Shopify-Shop mit SpeamCore. Pro Store synchronisieren wir Produkte, Bestellungen und Kunden — und protokollieren jeden Sync-Lauf in Sync-Logs. Der OAuth-Flow erfolgt einmalig beim Anlegen des Stores; Shop-Stammdaten (shopName, shopEmail, shopOwner, shopCurrency, shopTimezone) werden anschliessend automatisch von Shopify gepusht.

Voraussetzungen

- Shopify-Tenant-Admin-Berechtigung — der OAuth-Flow erfordert Zustimmung im Shopify Admin. - SpeamCore-App ist im Shopify Marketplace registriert (Tenant-uebergreifend). - Berechtigung `create:ShopifyStore`.

Berechtigungen (CASL)

Frontend-Page-Guard:

Action	Subject	Keycloak-Rolle
view	FE_ShopifyStore, ShopifyStore	—

Tab-Subjects:

Tab	Sub-Pfad	Subject
Produkt-Zuweisungen	/shopify-stores/:id/product-assignments	ShopifyProductAssignment:view
Produkt-Mappings	/shopify-stores/:id/product-mappings	ShopifyProductMapping:view
Bestellungen-Mappings	/shopify-stores/:id/order-mappings	ShopifyOrderMapping:view
Kunden-Mappings	/shopify-stores/:id/customer-mappings	ShopifyCustomerMapping:view
Sync-Logs	/shopify-stores/:id/sync-logs	ShopifySyncLog:view

Schritt-für-Schritt-Anleitung

Store verbinden

1. Shopify-Stores (/shopify-stores) → + Neu.
2. shopDomain eingeben (z. B. meine-firma.myshopify.com).
3. OAuth starten — Klick auf ShopifyOAuthButton öffnet die Shopify-Consent-URL.
4. Berechtigungen im Shopify Admin bestaetigen.
5. SpeamCore wird zurueckgeleitet, der Store wird angelegt, shopName/shopEmail/shopOwner/shopCurrency/shopTimezone werden automatisch befuellt.

Aktiv schalten / Sync-Stichtag setzen

1. isActive auf true setzen.
2. syncStartDate setzen — alle Bestellungen vor diesem Datum werden ignoriert.
3. Manuellen Sync über ShopifySyncActions triggern (oder warten auf den geplanten Cron-Lauf).

Produkte zuordnen — Tab „Produkt-Zuordnungen" (Juni 2026)

Im Tab Produkt-Zuordnungen (/shopify-stores/:id/product-assignments) legen Sie fest, welche Produkte in den Shop synchronisiert werden — auf vier Ebenen (beliebig kombinierbar):

Ebene	Feld	Wirkung
Einzelprodukt	productId	genau dieses Produkt
Warengruppe	productGroupId	der gesamte Teilbaum der Gruppe (alle enthaltenen Produkte)
Hersteller	manufacturerId	alle Produkte dieses Herstellers
Lieferant	supplierId	alle Produkte dieses Lieferanten

Hersteller- und Lieferant-Ebene sind neu — so lässt sich ein komplettes Sortiment mit einem Eintrag freigeben, statt jedes Produkt einzeln. Beim Sync entfaltet SpeamCore alle Zuordnungen zur Produktliste und legt/aktualisiert je Produkt ein Produkt-Mapping (Shopify-Produkt-/Varianten-ID, lastSyncAt). Ein Filter-Panel (Produkt-Nr., Titel, Hersteller-Artikelnummer) hilft bei der Auswahl; bereits zugeordnete Einträge werden ausgeblendet.

Unterschied: Produkt-Zuordnungen = was synchronisiert wird (Konfiguration). Produkt-Mappings = Ergebnis pro synchronisiertem Produkt (Sync-Status).

OAuth-Anbindung, Shopify-Webhooks und Shop-Metadaten laufen seit Juni 2026 über die zentrale **Master-Plattform**: Der Master nimmt die Shopify-Verbindung und eingehende Webhooks an und reicht Token + Shop-Infos an den Mandanten weiter; der Mandant synchronisiert lokal und meldet die **Sync-Zeitpunkte** an den Master zurück. Für Sie als Anwender ändert sich der Ablauf (Store verbinden → zuordnen → synchronisieren) nicht.

Mappings pflegen

• Produkt-Mappings: Zuordnung Shopify-Produkt-Felder zu SpeamCore-Produkt-Feldern.
• Bestellungen-Mappings: Zahlungsverhalten, Versandarten, Statusuebersetzung.
• Kunden-Mappings: Bestehender SpeamCore-Kunde vs. neue Anlage.

Toolbar (Detail-Seite)

Schlanke Toolbar oben rechts:

Icon	Aktion (aria-label)	CASL	Wirkung
←	Zurückgehen	—	Zurück zur Liste.
🏠	Zur Startseite gehen	—	Springt auf das Dashboard / /.
⏮/◀/▶/⏭	Pagination	—	Navigation durch die gefilterte Liste — Massen-Bearbeitung ohne Liste-Sprung.

Globale Floating-Drawer (links)

Wie auf jeder Detail-Seite verfuegbar — siehe Floating-Quickbar:

• KAL. (Mini-Kalender)
• ZEIT (Persoenliche Wochen-Arbeitszeit)
• ARBEIT (Eigene bevorstehende Aufträge)

UI-Elemente

Button: „ShopifyOAuthButton"

Initiiert OAuth-Flow. Speichert Nonce, leitet zu Shopify-Consent-URL.

Komponente: ShopifyConnectionStatus

Zeigt: aktiver Status (isActive), letzte Sync-Zeitpunkte (lastProductSyncAt, lastOrderSyncAt, lastCustomerSyncAt), aktuelle Fehler.

Komponente: ShopifySyncActions

Buttons für manuellen Sync-Trigger pro Datentyp (Produkte / Bestellungen / Kunden).

Felder und Eingaben

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
shopDomain	ja (vor OAuth)	String	Shopify-Domain, z. B. meine-firma.myshopify.com.	Triggert beim OAuth-Start die Redirect-URL.	Shop muss existieren.
isActive	nein	Boolean (Switch)	Sync aktiv?	true: regelmaessiger Sync laeuft. false: pausiert.	—
syncStartDate	nein	DATE	Stichtag für Sync.	Bestellungen/Produkte vor diesem Datum werden ignoriert.	Liegt nicht in der Zukunft.
shopName	—	String (read-only)	Anzeigename des Shops.	Wird von Shopify gepusht.	OAuth abgeschlossen.
shopEmail	—	String (read-only)	Shop-Owner-E-Mail.	Wird gepusht.	—
shopOwner	—	String (read-only)	Owner-Name.	Wird gepusht.	—
shopCurrency	—	String (read-only)	Default-Waehrung des Shops.	Wird beim Order-Mapping verwendet.	—
shopTimezone	—	String (read-only)	Zeitzone des Shops.	Steuert Datums-Konvertierung.	—
apiVersion	—	String (read-only)	Shopify-API-Version.	Wird automatisch durch Shopify gepusht.	—
scopes	—	String (read-only)	Erteilte OAuth-Scopes.	Bestimmt verfuegbare Sync-Methoden.	—
installedAt	—	Datetime (read-only)	Installations-Zeitpunkt.	Wird bei OAuth gesetzt.	—
nonce	—	String (intern)	OAuth-Nonce zur Validierung.	Wird vor OAuth-Redirect gesetzt, beim Callback geprüft.	—

Workflows und Zustaende

Anlege-Pattern

ShopifyStoreProductMapping haelt die Verknuepfung zwischen einem SpeamCore-Product und dem entsprechenden Eintrag im Shopify-Shop:

• shopifyStoreId — welcher Shop.
• productId — SpeamCore-Produkt.
• shopifyProductId — Produkt-ID im Shopify-Shop (extern).
• lastSyncedAt — Zeitstempel des letzten Sync.

Sync-Logik laeuft via Hintergrund-Job (siehe Sync-Jobs) — Bestand und Preise werden zwischen SpeamCore (Master) und Shopify (Storefront) abgeglichen.

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Produkte — ShopifyProductAssignment und ShopifyProductMapping verbinden SpeamCore-Produkte mit Shopify-Produkten.
• Verkaufsbelege — Shopify-Bestellungen werden über ShopifyOrderMapping zu SalesDocuments transformiert.
• Kunden — ShopifyCustomerMapping verbindet SpeamCore-Kunden und Shopify-Kunden.
• Sync-Logs — Audit-Trail aller Sync-Operationen.

Häufige Fehler und Lösungen

Fehler	Lösung
OAuth-Flow bricht ab	Berechtigungen im Shopify Admin prüfen; Nonce-Validierung im BE prüfen.
Sync laeuft nicht	isActive = false; apiVersion veraltet; Token abgelaufen — Store neu autorisieren.
Bestellungen vor Stichtag fehlen	syncStartDate zurueckdatieren und nächsten Sync abwarten.
Mapping-Fehler im Sync-Log	Field-Mapping prüfen; nicht-mappbare Felder ergaenzen.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/shopify-stores	Liste	view ShopifyStore
GET	/api/shopify-stores/:id	Detail	view ShopifyStore
POST	/api/shopify-stores	Anlegen	create ShopifyStore
PATCH	/api/shopify-stores/:id	Ändern	update ShopifyStore
DELETE	/api/shopify-stores/:id	Soft-Delete	delete ShopifyStore
GET	/api/shopify-stores/:id/sync-logs	Sync-Audit	view ShopifySyncLog
GET	/api/shopify-product-assignments?filter[shopifyStoreId]	Zuordnungen lesen	view ShopifyProductAssignment
POST	/api/shopify-product-assignments	Zuordnung anlegen (Produkt/Gruppe/Hersteller/Lieferant)	create ShopifyProductAssignment
DELETE	/api/shopify-product-assignments/:id	Zuordnung entfernen	delete ShopifyProductAssignment

Versionshinweise

• 2026-06-30: Tab Produkt-Zuordnungen dokumentiert — vier Zuordnungs-Ebenen inkl. Hersteller und Lieferant (ShopifyProductAssignment), Teilbaum-Sync; Hinweis, dass OAuth/Webhooks/Shop-Metadaten über die SpeamCore-Master-Plattform laufen. Verifiziert an shopifyProductAssignment.model.ts, shopifyStore.model.ts, shopifyProductAssignment.router.ts.
• 2026-04-29: Initiale Veroeffentlichung mit FE-Tiefen-Standard.