Definiere Shopify-Webhook-Sync-Prozess
This commit is contained in:
+122
@@ -0,0 +1,122 @@
|
|||||||
|
# erp.import-integration.shopify_order_sync
|
||||||
|
Stand: 2026-08-12
|
||||||
|
Status: Verbindliche Prozess-Spezifikation
|
||||||
|
|
||||||
|
## 1. Zweck
|
||||||
|
|
||||||
|
Read-only-Annahme und technische Übergabe von Shopify-Bestellereignissen an das owning Bestellmodul, ohne Schreibzugriffe auf Shopify und ohne Kundenkommunikation.
|
||||||
|
|
||||||
|
## 2. Prozess-Einbettung
|
||||||
|
|
||||||
|
Direkter HTTPS-Webhook-Prozess im Submodul `erp/import-integration`. Der Prozess nimmt ein Shopify-Ereignis an, authentifiziert es, persistiert den technischen Eingang und übergibt nur die minimale Ereignisidentität an die nachgelagerte Bestellverarbeitung.
|
||||||
|
|
||||||
|
## 3. Input
|
||||||
|
|
||||||
|
- Shopify-Webhook-HTTP-Request
|
||||||
|
- `X-Shopify-Hmac-SHA256`
|
||||||
|
- `X-Shopify-Topic`
|
||||||
|
- `X-Shopify-Webhook-Id`
|
||||||
|
- `X-Shopify-Shop-Domain`
|
||||||
|
- JSON-Body des Shopify-Ereignisses
|
||||||
|
|
||||||
|
Es werden keine vorbereiteten Geschäftsdaten an nachgelagerte Prozesse übergeben; diese laden ihre Daten aus eigener Quelle beziehungsweise aus dem persistierten technischen Eingang.
|
||||||
|
|
||||||
|
## 4. Exakter Prozessablauf
|
||||||
|
|
||||||
|
1. HTTP-Methode und erforderliche Shopify-Header validieren.
|
||||||
|
2. HMAC-Signatur mit dem konfigurierten Shopify-App-Secret prüfen.
|
||||||
|
3. JSON-Body als technisches Eingangsdokument validieren.
|
||||||
|
4. Webhook-ID idempotent gegen bereits verarbeitete Eingänge prüfen.
|
||||||
|
5. Technischen Eingang mit Topic, Shop-Domain, Shopify-Webhooks-ID und Payload-Hash speichern.
|
||||||
|
6. Shopify Order-GID aus dem Ereignis oder durch den definierten Shopify-Read-Schritt bestimmen.
|
||||||
|
7. Nur die stabile Ereignis-/Order-Identität an das owning Bestellmodul übergeben.
|
||||||
|
8. Keine Shopify-Mutation, keine Fulfillment-Aktion, keine Label-Aktion, kein n8n-Versand und kein Klaviyo-Event auslösen.
|
||||||
|
9. Technischen Lauf mit kompaktem Ergebnis abschliessen.
|
||||||
|
|
||||||
|
Read sources:
|
||||||
|
|
||||||
|
- Shopify-Webhook-Request
|
||||||
|
- Shopify-API nur read-only, sofern für die Ereignisidentität erforderlich
|
||||||
|
- eigene technische Importzustandsdaten
|
||||||
|
|
||||||
|
Write targets:
|
||||||
|
|
||||||
|
- technische Importzustandsdaten im owning Submodul
|
||||||
|
- `public.process_runs` für den technischen Lauf
|
||||||
|
- nachgelagerte Bestelldaten ausschliesslich über die definierte Schnittstelle des Moduls `erp/bestellungen`
|
||||||
|
|
||||||
|
## 5. Batch, Betriebsmodell und Einbettung
|
||||||
|
|
||||||
|
Ein Request verarbeitet genau ein Webhook-Ereignis. Shopify-Retries werden über die Webhook-ID idempotent behandelt. Ein periodischer Reconciliation-Prozess ist ein separater Prozess und nicht Teil dieses Webhook-Einstiegs.
|
||||||
|
|
||||||
|
## 6. Output
|
||||||
|
|
||||||
|
HTTP 2xx mit kompaktem JSON bei akzeptiertem Eingang, einschliesslich Duplicate-Acknowledgement. HTTP 4xx bei ungültiger Authentifizierung oder Payload. HTTP 5xx bei technischem Totalfehler.
|
||||||
|
|
||||||
|
## 7. Erfolgskriterien
|
||||||
|
|
||||||
|
- gültige Shopify-Signatur wird akzeptiert
|
||||||
|
- ungültige Signatur wird abgewiesen
|
||||||
|
- derselbe Webhook erzeugt keine doppelte Verarbeitung
|
||||||
|
- Shopify Order-GID bleibt nachvollziehbar
|
||||||
|
- kein externer Schreib- oder Kommunikations-Trigger wird ausgeführt
|
||||||
|
- technischer Lauf ist vollständig protokolliert
|
||||||
|
|
||||||
|
## 8. Fehlerschranke
|
||||||
|
|
||||||
|
Ungültige Requests werden ohne fachliche Verarbeitung abgewiesen. Technische Fehler beim Persistieren oder bei der definierten Übergabe führen zu einem technischen Fehler. Wiederholte gültige Eingänge werden idempotent bestätigt. Teilfehler innerhalb der nachgelagerten Batch-/Reconciliation-Prozesse gehören nicht in diesen Einzel-Webhook-Prozess.
|
||||||
|
|
||||||
|
## 9. Fachliche Betriebsregel
|
||||||
|
|
||||||
|
Shopify ist die führende Quelle für Shop-Bestellungen. Die ERP-Anwendung liest Shopify-Daten; sie schreibt keine Bestell-, Kunden-, Produkt-, Zahlungs-, Refund- oder Fulfillmentdaten zurück nach Shopify. Historische Migration und laufender Sync sind getrennte Prozesse.
|
||||||
|
|
||||||
|
## 10. Sub-Prozess-Referenzen
|
||||||
|
|
||||||
|
- `erp.import-integration.shopify_webhook_authentication`
|
||||||
|
- `erp.import-integration.shopify_event_persistence`
|
||||||
|
- `erp.bestellungen.shopify_order_sync`
|
||||||
|
|
||||||
|
Die genannten Sub-Prozesse müssen vor der Implementierung als eigene verbindliche Verträge dokumentiert werden.
|
||||||
|
|
||||||
|
## 11. End-to-End Sub-Prozess-Kette
|
||||||
|
|
||||||
|
Shopify HTTP-Webhook → Authentifizierung → technische Eingangspersistenz → Bestellmodul-Übergabe → technischer Abschluss.
|
||||||
|
|
||||||
|
## 12. Sub-Prozess-Wiederverwendung
|
||||||
|
|
||||||
|
Bestehende technische Webhook- und DB-Bausteine werden wiederverwendet, sofern sie HMAC-Prüfung, Idempotenz und technische Laufpersistenz ohne fachliche Shopify-Annahmen unterstützen. Eine neue fachliche Bestelllogik im Import-Submodul ist nicht zulässig.
|
||||||
|
|
||||||
|
## 13. Step-Liste
|
||||||
|
|
||||||
|
1. `shopify_webhook_authentication`
|
||||||
|
2. `shopify_event_persistence`
|
||||||
|
3. `shopify_order_sync_handoff`
|
||||||
|
4. `shopify_sync_result_finalization`
|
||||||
|
|
||||||
|
## 14. Parallelisierung
|
||||||
|
|
||||||
|
Nicht anwendbar für den Einzel-Webhook. Parallelisierung erfolgt ausschließlich in einem separaten, batchbasierten Reconciliation-Prozess.
|
||||||
|
|
||||||
|
## 15. Output-Payload
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "accepted|duplicate|rejected|failed",
|
||||||
|
"webhook_id": "string",
|
||||||
|
"topic": "string",
|
||||||
|
"shop_domain": "string",
|
||||||
|
"shopify_order_gid": "string|null",
|
||||||
|
"technical_run_id": "integer|null"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Keine Rohpayloads, Kundendaten oder Geschäftsdatasets werden im Response-Payload zurückgegeben.
|
||||||
|
|
||||||
|
## 16. Done-Kriterien
|
||||||
|
|
||||||
|
- Prozess und Sub-Prozesse sind dokumentiert.
|
||||||
|
- Endpoint validiert Shopify-HMAC und Pflichtheader.
|
||||||
|
- Duplicate-Webhook ist idempotent.
|
||||||
|
- technische Eingangsdaten und Prozesslauf sind nachvollziehbar.
|
||||||
|
- die Bestellübergabe bleibt auf stabile Identitäten begrenzt.
|
||||||
|
- Shopify, Klaviyo, n8n und Kundenmail-Systeme erhalten keine unbeabsichtigten Schreib- oder Versandimpulse.
|
||||||
@@ -107,6 +107,8 @@ Fachliche Übergabe: `erp/bestellungen`
|
|||||||
- [ ] Prozess `shopify.orders.migrate` definieren.
|
- [ ] Prozess `shopify.orders.migrate` definieren.
|
||||||
- [ ] Prozess `shopify.orders.receive` definieren.
|
- [ ] Prozess `shopify.orders.receive` definieren.
|
||||||
- [ ] Prozess `shopify.orders.reconcile` definieren.
|
- [ ] Prozess `shopify.orders.reconcile` definieren.
|
||||||
|
- [x] Verbindlichen Webhook-Sync-Prozess dokumentieren.
|
||||||
|
- [ ] Verbindliche Sub-Prozess-Verträge für Authentifizierung, Persistenz und Bestellübergabe dokumentieren.
|
||||||
- [ ] Status- und Lagerübergaben zwischen den Modulen definieren.
|
- [ ] Status- und Lagerübergaben zwischen den Modulen definieren.
|
||||||
- [ ] Minimalen Identifier-Hand-off zwischen Import und Bestellungen definieren.
|
- [ ] Minimalen Identifier-Hand-off zwischen Import und Bestellungen definieren.
|
||||||
- [ ] Fehler- und Teilfehlerverhalten pro Prozess definieren.
|
- [ ] Fehler- und Teilfehlerverhalten pro Prozess definieren.
|
||||||
|
|||||||
Reference in New Issue
Block a user