Document direct n8n Shopify triggers

This commit is contained in:
2026-08-12 18:05:55 +02:00
parent e565286280
commit 1e75ef7a24
4 changed files with 9 additions and 8 deletions
@@ -27,7 +27,7 @@ Keine vorbereiteten Kunden-, Adress-, Positions- oder Shopify-Rohdaten werden ü
6. Bei `dry_run` nur Mapping, Mengen und verfügbaren Chargenbestand prüfen. 6. Bei `dry_run` nur Mapping, Mengen und verfügbaren Chargenbestand prüfen.
7. Bei Echtlauf Bestellkopf und -positionen schreiben und jede Position genau einmal über die Lagerschnittstelle allokieren. 7. Bei Echtlauf Bestellkopf und -positionen schreiben und jede Position genau einmal über die Lagerschnittstelle allokieren.
8. Shopify-Varianten- und Produkt-GIDs beim bereits bestätigten Shopify-Alias speichern. 8. Shopify-Varianten- und Produkt-GIDs beim bereits bestätigten Shopify-Alias speichern.
9. Keine Shopify-Mutation, n8n-Zustellung, Klaviyo-Aktion, Kundenmail oder Label-Aktion ausführen. 9. Keine Shopify-Mutation und keine externe Kommunikation ausführen. Die anschliessende n8n-Auslösung gehört zum owning Delta-Prozess.
Read sources: Read sources:
@@ -25,7 +25,7 @@ Es werden keine vorbereiteten Shopify-Geschäftsdaten an nachgelagerte Module ü
4. Für jede qualifizierte Bestellung die Shopify Order-GID idempotent gegen `sales_order.shopify_order_gid` prüfen. 4. Für jede qualifizierte Bestellung die Shopify Order-GID idempotent gegen `sales_order.shopify_order_gid` prüfen.
5. Nur die Shopify Order-GID an die Bestell-Schnittstelle übergeben; diese lädt und projiziert die erforderlichen Shopify-Daten selbst. 5. Nur die Shopify Order-GID an die Bestell-Schnittstelle übergeben; diese lädt und projiziert die erforderlichen Shopify-Daten selbst.
6. Bei `dry_run` keine fachlichen DB-Writes, Lagerbewegungen oder externen Aufrufe ausführen. 6. Bei `dry_run` keine fachlichen DB-Writes, Lagerbewegungen oder externen Aufrufe ausführen.
7. Keine Shopify-Mutation, keine n8n-Zustellung, kein Klaviyo-Ereignis, keine Kundenmail und keine Label-Aktion ausführen. 7. Nach erfolgreicher Echtlauf-Projektion beide direkten n8n-Webhooks synchron auslösen: Adressetikette mit dem Legacy-Bestelldokument und Excel mit `{"Bestellnummer":"<external_ref>"}`. Im Dry-Run sowie für übersprungene oder bereits importierte Bestellungen erfolgt keine externe Zustellung.
8. Den technischen Lauf in `process_runs` abschliessen. 8. Den technischen Lauf in `process_runs` abschliessen.
Read sources: Read sources:
@@ -54,7 +54,8 @@ Kompaktes Ergebnis mit geprüfter, übersprungener, bereits vorhandener und übe
- stornierte/erstattete Bestellungen sind nicht lagerwirksam - stornierte/erstattete Bestellungen sind nicht lagerwirksam
- jede Shopify Order-GID wird höchstens einmal als ERP-Bestellung angelegt - jede Shopify Order-GID wird höchstens einmal als ERP-Bestellung angelegt
- der Dry-Run verändert keine fachlichen Daten - der Dry-Run verändert keine fachlichen Daten
- n8n, Klaviyo, Mail, Labels und Shopify bleiben unbeeinflusst - Dry-Run, übersprungene und bereits importierte Bestellungen bleiben ohne externe Wirkung.
- Eine neu projizierte Bestellung erhält HTTP-2xx von beiden n8n-Webhooks; Klaviyo und Kundenmail bleiben unbeeinflusst.
## 8. Fehlerschranke ## 8. Fehlerschranke
@@ -10,7 +10,7 @@ Shopify ist die fachlich führende Quelle für Shop-Bestellungen. Das ERP hält
Die bestehenden 93 ERP-Bestellungen bleiben mit ihren Lager-, Chargen- und Kundenrelationen erhalten. Die 536 Shopify-Bestellungen mit dem Tag `wix-import` sind historische Migrationsdaten; sie werden nicht erneut als ERP-Bestellungen angelegt. Ins ERP wird nur das Shopify-Delta nach dem ERP-Stichtag übernommen. Historische Wix-Referenzen bleiben dauerhaft sichtbar. Die bestehenden 93 ERP-Bestellungen bleiben mit ihren Lager-, Chargen- und Kundenrelationen erhalten. Die 536 Shopify-Bestellungen mit dem Tag `wix-import` sind historische Migrationsdaten; sie werden nicht erneut als ERP-Bestellungen angelegt. Ins ERP wird nur das Shopify-Delta nach dem ERP-Stichtag übernommen. Historische Wix-Referenzen bleiben dauerhaft sichtbar.
Die zwei bestehenden n8n-Schnittstellen behalten ihre jeweiligen Payload-Verträge. Historische Migrationen senden an keinen der beiden Endpunkte und lösen weder Kundenkommunikation noch Klaviyo, Labels oder Lagerbewegungen aus. Die zwei bestehenden n8n-Schnittstellen behalten ihre jeweiligen Payload-Verträge. Historische Migrationen und übersprungene Shopify-Bestellungen senden an keinen der beiden Endpunkte. Eine neu projizierte qualifizierte Shopify-Bestellung löst beide Endpunkte direkt aus, jedoch keine Kundenkommunikation oder Klaviyo-Aktion.
## 2. Belegte Ausgangslage ## 2. Belegte Ausgangslage
@@ -128,7 +128,7 @@ Die Übergaben enthalten nur stabile IDs. Weder Shopify-Rohpayloads noch vorbere
- Der abgeschlossene Delta-Lauf verarbeitet Shopify-Bestellungen nach einem festen ERP-Stichtag und läuft read-only gegenüber Shopify. `wix-import` bleibt ein historisches Herkunftsmerkmal. - Der abgeschlossene Delta-Lauf verarbeitet Shopify-Bestellungen nach einem festen ERP-Stichtag und läuft read-only gegenüber Shopify. `wix-import` bleibt ein historisches Herkunftsmerkmal.
- Für jede Bestellung wird zuerst ein Snapshot gespeichert, dann eine Zuordnung vorgeschlagen und erst nach Eindeutigkeit fachlich projiziert. - Für jede Bestellung wird zuerst ein Snapshot gespeichert, dann eine Zuordnung vorgeschlagen und erst nach Eindeutigkeit fachlich projiziert.
- Migration und Reconciliation erzeugen keine n8n-Deliveries, keine Klaviyo-Ereignisse, keine Labels und keine Kundenmails. - Historische Migration, Dry-Run, Reconciliation ohne neue ERP-Projektion sowie übersprungene oder bereits importierte Bestellungen erzeugen keine n8n-Aufrufe. Eine neue qualifizierte Shopify-Projektion löst nach erfolgreichem Commit beide direkten n8n-Webhooks aus.
- Ein technischer Fehler beim Shopify-Abruf oder bei der DB-Transaktion beendet den betroffenen Batch hart. Fachliche Einzelprobleme fehlende Wix-Referenz, Variant-Mapping oder unklare Kundenidentität werden als Klärfall isoliert und der Batch läuft weiter. - Ein technischer Fehler beim Shopify-Abruf oder bei der DB-Transaktion beendet den betroffenen Batch hart. Fachliche Einzelprobleme fehlende Wix-Referenz, Variant-Mapping oder unklare Kundenidentität werden als Klärfall isoliert und der Batch läuft weiter.
- Wiederholte Verarbeitung derselben Shopify-Version ist idempotent. Eine neuere Shopify-Version aktualisiert nur die Shopify-projizierbaren Felder und überschreibt keine ERP-eigenen Entscheidungen ohne ausdrücklich definierten Fachprozess. - Wiederholte Verarbeitung derselben Shopify-Version ist idempotent. Eine neuere Shopify-Version aktualisiert nur die Shopify-projizierbaren Felder und überschreibt keine ERP-eigenen Entscheidungen ohne ausdrücklich definierten Fachprozess.
- Ein periodischer Reconciliation-Prozess gleicht alle seit dem letzten erfolgreichen Wasserzeichen geänderten Shopify-Bestellungen ab und kompensiert verpasste Webhooks. - Ein periodischer Reconciliation-Prozess gleicht alle seit dem letzten erfolgreichen Wasserzeichen geänderten Shopify-Bestellungen ab und kompensiert verpasste Webhooks.
@@ -138,7 +138,7 @@ Die Übergaben enthalten nur stabile IDs. Weder Shopify-Rohpayloads noch vorbere
1. Datenmodell-Migration und Constraints erstellen; vorher DEV-Entwicklerbackup, danach Schema- und Regressionstests. 1. Datenmodell-Migration und Constraints erstellen; vorher DEV-Entwicklerbackup, danach Schema- und Regressionstests.
2. Snapshot- und Projektion-Schnittstelle im Bestellmodul implementieren; nur Fixtures und read-only Shopify-Tests. 2. Snapshot- und Projektion-Schnittstelle im Bestellmodul implementieren; nur Fixtures und read-only Shopify-Tests.
3. Delta-Lauf zunächst als Dry-Run durchführen: fünf Bestellungen prüfen, vier Refund/Cancel-Fälle überspringen und genau eine qualifizierte Bestellung bestätigen. 3. Delta-Lauf zunächst als Dry-Run durchführen: fünf Bestellungen prüfen, vier Refund/Cancel-Fälle überspringen und genau eine qualifizierte Bestellung bestätigen.
4. Nach fachlicher Abnahme die eine qualifizierte Bestellung kontrolliert projizieren. Dabei bleiben alle n8n-Deliveries gesperrt. 4. Nach fachlicher Abnahme die eine qualifizierte Bestellung kontrolliert projizieren und beide n8n-Webhooks mit den bestehenden Verträgen auslösen.
5. n8n-Kompatibilitätsadapter gegen die zwei archivierten Fixtures testen; keine echten n8n-Aufrufe im Test. 5. n8n-Kompatibilitätsadapter gegen die zwei archivierten Fixtures testen; keine echten n8n-Aufrufe im Test.
6. Laufenden Webhook- und Reconciliation-Sync aktivieren; n8n-Deliveries erst nach separatem End-to-End-Test mit freigegebenem Testauftrag einschalten. 6. Laufenden Webhook- und Reconciliation-Sync aktivieren; n8n-Deliveries erst nach separatem End-to-End-Test mit freigegebenem Testauftrag einschalten.
@@ -10,7 +10,7 @@ Fachliche Übergabe: `erp/bestellungen`
- [x] Shopify ist die führende Quelle für Shop-Bestellungen als Zielbild bestätigt. - [x] Shopify ist die führende Quelle für Shop-Bestellungen als Zielbild bestätigt.
- [x] Bestehende Bestellungen in der App bleiben erhalten. - [x] Bestehende Bestellungen in der App bleiben erhalten.
- [x] Initiale Analyse und Migration sind read-only gegenüber Shopify. - [x] Initiale Analyse und Migration sind read-only gegenüber Shopify.
- [x] Keine Shopify-Schreiboperationen, Kundenmails, Klaviyo-Ereignisse oder n8n-Nebenwirkungen während der Migration. - [x] Keine Shopify-Schreiboperationen, Kundenmails oder Klaviyo-Ereignisse; n8n wird nur für die qualifizierte neue Bestellung direkt ausgelöst.
- [x] Zielmodell und Prozessvertrag vor der technischen Webhook-Annahme festgelegt. - [x] Zielmodell und Prozessvertrag vor der technischen Webhook-Annahme festgelegt.
- [x] Nach den bisherigen App- und DB-Änderungen ausführliche Tests auf DEV über `ssh synology-hz` durchgeführt. - [x] Nach den bisherigen App- und DB-Änderungen ausführliche Tests auf DEV über `ssh synology-hz` durchgeführt.
- [ ] Keine lokalen Runtime-, Scheduler- oder DB-Prüfungen verwenden. - [ ] Keine lokalen Runtime-, Scheduler- oder DB-Prüfungen verwenden.
@@ -246,7 +246,7 @@ Fachliche Übergabe: `erp/bestellungen`
- [ ] Keine Shopify-Schreiboperationen nachweisen. - [ ] Keine Shopify-Schreiboperationen nachweisen.
- [ ] Keine Kundenmails nachweisen. - [ ] Keine Kundenmails nachweisen.
- [ ] Keine Klaviyo-Doppelevents nachweisen. - [ ] Keine Klaviyo-Doppelevents nachweisen.
- [x] Keine unerwarteten n8n-Aufrufe nachweisen: 0 Shopify-Outbox-Ereignisse. - [x] Keine unerwarteten n8n-Aufrufe nachweisen: 0 Shopify-Outbox-Ereignisse; die beiden direkten Webhooks für #1541 lieferten HTTP 200.
## 11. Produktivsetzung ## 11. Produktivsetzung