Definiere Shopify-Webhook-Subprozesse
This commit is contained in:
+98
@@ -0,0 +1,98 @@
|
||||
# erp.import-integration.shopify_event_persistence
|
||||
Stand: 2026-08-12
|
||||
Status: Verbindliche Prozess-Spezifikation
|
||||
|
||||
## 1. Zweck
|
||||
|
||||
Einen authentifizierten Shopify-Webhook technisch idempotent und nachvollziehbar speichern.
|
||||
|
||||
## 2. Prozess-Einbettung
|
||||
|
||||
Synchroner Sub-Prozess von `erp.import-integration.shopify_order_sync` nach erfolgreicher Authentifizierung.
|
||||
|
||||
## 3. Input
|
||||
|
||||
- `topic`
|
||||
- `webhook_id`
|
||||
- `shop_domain`
|
||||
- `raw_body`
|
||||
- `payload_sha256`
|
||||
|
||||
## 4. Exakter Prozessablauf
|
||||
|
||||
1. Technische Eingangstabelle über die owning Import-Schnittstelle verwenden.
|
||||
2. Nach vorhandener `webhook_id` suchen.
|
||||
3. Vorhandenen Eingang als Duplicate zurückgeben, ohne Business-Verarbeitung.
|
||||
4. Neuen Eingang mit Topic, Shop-Domain, Hash, Payload und Empfangszeitpunkt speichern.
|
||||
5. JSON-Body nur zur Ermittlung der technischen Shopify Order-GID auswerten.
|
||||
6. Keine Bestell-, Kunden-, Produkt-, Fulfillment- oder Zahlungsdaten in diesem Sub-Prozess fachlich interpretieren.
|
||||
|
||||
Read sources:
|
||||
|
||||
- authentifizierte technische Metadaten
|
||||
- technische Importzustandsdaten
|
||||
|
||||
Write targets:
|
||||
|
||||
- technische Shopify-Webhook-Eingangstabelle im owning Import-Submodul
|
||||
|
||||
## 5. Batch, Betriebsmodell und Einbettung
|
||||
|
||||
Ein Webhook pro Lauf. Idempotenz über eindeutige `webhook_id`.
|
||||
|
||||
## 6. Output
|
||||
|
||||
`accepted` oder `duplicate`, jeweils mit technischer Eingang-ID und ermittelter Shopify Order-GID.
|
||||
|
||||
## 7. Erfolgskriterien
|
||||
|
||||
- gültiger Eingang ist persistent
|
||||
- Duplicate erzeugt keinen zweiten technischen Eingang
|
||||
- Raw Payload bleibt zur Nachvollziehbarkeit erhalten
|
||||
- keine externen Nebenwirkungen entstehen
|
||||
|
||||
## 8. Fehlerschranke
|
||||
|
||||
DB- oder Persistenzfehler sind technische Totalfehler. Doppelte Eingänge sind kein Fehler und werden mit `duplicate` quittiert.
|
||||
|
||||
## 9. Fachliche Betriebsregel
|
||||
|
||||
Die technische Payload ist Beleg des Shopify-Eingangs, aber nicht automatisch die fachliche Wahrheit der ERP-Bestellung.
|
||||
|
||||
## 10. Sub-Prozess-Referenzen
|
||||
|
||||
Keine.
|
||||
|
||||
## 11. End-to-End Sub-Prozess-Kette
|
||||
|
||||
Authentifizierte Metadaten → Duplicate-Prüfung → technische Persistenz → technische Shopify Order-GID.
|
||||
|
||||
## 12. Sub-Prozess-Wiederverwendung
|
||||
|
||||
Vorhandene DB- und Prozesslauf-Schnittstellen sind wiederzuverwenden. Keine neue fachliche Importtabelle ohne DB-Ownership-Dokumentation.
|
||||
|
||||
## 13. Step-Liste
|
||||
|
||||
1. `find_existing_webhook`
|
||||
2. `persist_webhook_event`
|
||||
3. `extract_shopify_order_identity`
|
||||
|
||||
## 14. Parallelisierung
|
||||
|
||||
Nicht anwendbar.
|
||||
|
||||
## 15. Output-Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "accepted|duplicate",
|
||||
"technical_event_id": "integer",
|
||||
"shopify_order_gid": "string|null"
|
||||
}
|
||||
```
|
||||
|
||||
## 16. Done-Kriterien
|
||||
|
||||
- Eindeutigkeit der Webhook-ID ist technisch abgesichert.
|
||||
- Duplicate-Verarbeitung ist ohne fachliche Nebenwirkung.
|
||||
- Raw Payload ist nachvollziehbar gespeichert.
|
||||
+102
@@ -0,0 +1,102 @@
|
||||
# erp.import-integration.shopify_order_sync_handoff
|
||||
Stand: 2026-08-12
|
||||
Status: Verbindliche Prozess-Spezifikation
|
||||
|
||||
## 1. Zweck
|
||||
|
||||
Die technische Shopify Order-GID kontrolliert an das owning Modul `erp/bestellungen` übergeben.
|
||||
|
||||
## 2. Prozess-Einbettung
|
||||
|
||||
Synchroner Sub-Prozess von `erp.import-integration.shopify_order_sync` nach technischer Ereignispersistenz.
|
||||
|
||||
## 3. Input
|
||||
|
||||
- `technical_event_id`
|
||||
- `shopify_order_gid`
|
||||
- `topic`
|
||||
|
||||
Keine vorbereiteten Kunden-, Produkt-, Zahlungs- oder Positionsdaten werden übergeben.
|
||||
|
||||
## 4. Exakter Prozessablauf
|
||||
|
||||
1. Topic gegen die unterstützten read-only Order-Topics prüfen.
|
||||
2. Shopify Order-GID validieren, wenn das Topic eine Bestellung betrifft.
|
||||
3. Nur `technical_event_id`, `shopify_order_gid` und `topic` an die Schnittstelle von `erp/bestellungen` übergeben.
|
||||
4. Ergebnis des owning Bestellmoduls technisch übernehmen.
|
||||
5. Keine direkten Writes in Bestell-, Kontakt- oder Lagertabellen aus dem Import-Submodul ausführen.
|
||||
6. Keine n8n-, Klaviyo-, Mail-, Label- oder Shopify-Mutationsaktion ausführen.
|
||||
|
||||
Read sources:
|
||||
|
||||
- technische Shopify-Webhook-Eingangsdaten
|
||||
- definierte Schnittstelle von `erp/bestellungen`
|
||||
|
||||
Write targets:
|
||||
|
||||
- technische Übergabe-/Laufdaten im Import-Submodul
|
||||
- fachliche Bestelldaten ausschließlich über die owning Bestell-Schnittstelle
|
||||
|
||||
## 5. Batch, Betriebsmodell und Einbettung
|
||||
|
||||
Ein Ereignis pro Lauf. Die fachliche Verarbeitung kann intern eigene Batch- oder Reconciliation-Prozesse verwenden.
|
||||
|
||||
## 6. Output
|
||||
|
||||
Kompaktes Übergabeergebnis mit technischem Status und stabilem Shopify-Identifier.
|
||||
|
||||
## 7. Erfolgskriterien
|
||||
|
||||
- nur definierte Topics werden weitergegeben
|
||||
- Übergabe enthält keine vorbereiteten Geschäftsdatasets
|
||||
- Import-Submodul schreibt nicht direkt in fremde fachliche Tabellen
|
||||
- Nebenwirkungsverbote bleiben eingehalten
|
||||
|
||||
## 8. Fehlerschranke
|
||||
|
||||
Nicht unterstützte Topics oder ungültige Order-GIDs werden abgewiesen. Fehler der owning Bestell-Schnittstelle werden als technische Übergabefehler protokolliert.
|
||||
|
||||
## 9. Fachliche Betriebsregel
|
||||
|
||||
Shopify bleibt führende Quelle. Die Übergabe darf keine Rückschreibungen nach Shopify oder Kundenkommunikation auslösen.
|
||||
|
||||
## 10. Sub-Prozess-Referenzen
|
||||
|
||||
- `erp.bestellungen.shopify_order_sync`
|
||||
|
||||
## 11. End-to-End Sub-Prozess-Kette
|
||||
|
||||
Technischer Eingang → Topic-/GID-Prüfung → identifier-only Hand-off → Bestellmodul-Ergebnis.
|
||||
|
||||
## 12. Sub-Prozess-Wiederverwendung
|
||||
|
||||
Die bestehende Bestell-Schnittstelle wird verwendet oder minimal erweitert. Eine parallele Bestellfachlogik im Import-Submodul ist ausgeschlossen.
|
||||
|
||||
## 13. Step-Liste
|
||||
|
||||
1. `validate_shopify_topic`
|
||||
2. `validate_shopify_order_identity`
|
||||
3. `handoff_to_orders_module`
|
||||
4. `capture_handoff_result`
|
||||
|
||||
## 14. Parallelisierung
|
||||
|
||||
Nicht anwendbar.
|
||||
|
||||
## 15. Output-Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "accepted|rejected|failed",
|
||||
"technical_event_id": "integer",
|
||||
"shopify_order_gid": "string|null",
|
||||
"orders_module_status": "string|null"
|
||||
}
|
||||
```
|
||||
|
||||
## 16. Done-Kriterien
|
||||
|
||||
- Übergabe ist identifier-only.
|
||||
- Bestellfachlichkeit bleibt im Modul `erp/bestellungen`.
|
||||
- Nicht unterstützte Topics werden nicht verarbeitet.
|
||||
- Keine externen Kommunikations- oder Shopify-Schreibwirkungen entstehen.
|
||||
+103
@@ -0,0 +1,103 @@
|
||||
# erp.import-integration.shopify_webhook_authentication
|
||||
Stand: 2026-08-12
|
||||
Status: Verbindliche Prozess-Spezifikation
|
||||
|
||||
## 1. Zweck
|
||||
|
||||
Shopify-Webhook-Request technisch authentifizieren und nur vertrauenswürdige Eingänge zur weiteren Verarbeitung freigeben.
|
||||
|
||||
## 2. Prozess-Einbettung
|
||||
|
||||
Synchroner Sub-Prozess von `erp.import-integration.shopify_order_sync`.
|
||||
|
||||
## 3. Input
|
||||
|
||||
- HTTP-Methode
|
||||
- Raw Request Body
|
||||
- `X-Shopify-Hmac-SHA256`
|
||||
- `X-Shopify-Topic`
|
||||
- `X-Shopify-Webhook-Id`
|
||||
- `X-Shopify-Shop-Domain`
|
||||
- konfigurierte Shopify-App-Secret-Referenz
|
||||
|
||||
Keine fachlichen Bestelldaten werden als vorbereitete Daten übergeben.
|
||||
|
||||
## 4. Exakter Prozessablauf
|
||||
|
||||
1. HTTP-Methode `POST` validieren.
|
||||
2. Pflichtheader auf Vorhandensein und nichtleere Werte prüfen.
|
||||
3. HMAC-SHA256 über den unveränderten Raw Body mit dem konfigurierten App-Secret berechnen.
|
||||
4. Berechnete Signatur timing-safe mit dem Shopify-Header vergleichen.
|
||||
5. Topic, Webhook-ID und Shop-Domain normalisieren.
|
||||
6. Nur bei erfolgreicher Prüfung an `shopify_event_persistence` weitergeben.
|
||||
|
||||
Read sources:
|
||||
|
||||
- HTTP-Request
|
||||
- Shopify-App-Konfiguration
|
||||
|
||||
Write targets:
|
||||
|
||||
- keine
|
||||
|
||||
## 5. Batch, Betriebsmodell und Einbettung
|
||||
|
||||
Ein Request, keine Parallelisierung, keine Wiederholung innerhalb des Sub-Prozesses.
|
||||
|
||||
## 6. Output
|
||||
|
||||
Normalisierte technische Metadaten: `topic`, `webhook_id`, `shop_domain`, `raw_body` und berechneter Payload-Hash.
|
||||
|
||||
## 7. Erfolgskriterien
|
||||
|
||||
- gültige Signatur wird akzeptiert
|
||||
- ungültige, fehlende oder manipulierte Signatur wird abgewiesen
|
||||
- kein ungeprüfter Body gelangt zur Persistenz
|
||||
|
||||
## 8. Fehlerschranke
|
||||
|
||||
Ungültige Requests führen zu einem kontrollierten technischen Reject mit HTTP 401 oder 400. Es erfolgt keine fachliche Verarbeitung.
|
||||
|
||||
## 9. Fachliche Betriebsregel
|
||||
|
||||
Die Authentifizierung hat keinen Zugriff auf Shopify-Daten und löst keine externen Aktionen aus.
|
||||
|
||||
## 10. Sub-Prozess-Referenzen
|
||||
|
||||
Keine.
|
||||
|
||||
## 11. End-to-End Sub-Prozess-Kette
|
||||
|
||||
HTTP-Request → Headerprüfung → HMAC-Berechnung → timing-sicherer Vergleich → normalisierte Metadaten.
|
||||
|
||||
## 12. Sub-Prozess-Wiederverwendung
|
||||
|
||||
Bestehende generische technische Header- und Hash-Helfer sind wiederzuverwenden. Shopify-spezifische Validierung bleibt im owning Import-Submodul.
|
||||
|
||||
## 13. Step-Liste
|
||||
|
||||
1. `validate_request_shape`
|
||||
2. `verify_shopify_hmac`
|
||||
3. `normalize_webhook_metadata`
|
||||
|
||||
## 14. Parallelisierung
|
||||
|
||||
Nicht anwendbar.
|
||||
|
||||
## 15. Output-Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"topic": "string",
|
||||
"webhook_id": "string",
|
||||
"shop_domain": "string",
|
||||
"raw_body": "string",
|
||||
"payload_sha256": "string"
|
||||
}
|
||||
```
|
||||
|
||||
## 16. Done-Kriterien
|
||||
|
||||
- HMAC-Prüfung ist timing-safe implementiert.
|
||||
- Raw Body wird vor JSON-Decoding signaturgeprüft.
|
||||
- Kein Reject führt zu fachlichen oder externen Nebenwirkungen.
|
||||
@@ -108,7 +108,10 @@ Fachliche Übergabe: `erp/bestellungen`
|
||||
- [ ] Prozess `shopify.orders.receive` 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.
|
||||
- [x] Verbindlichen Sub-Prozess-Vertrag für Shopify-Webhook-Authentifizierung dokumentieren.
|
||||
- [x] Verbindlichen Sub-Prozess-Vertrag für technische Shopify-Eventpersistenz dokumentieren.
|
||||
- [x] Verbindlichen Sub-Prozess-Vertrag für die identifier-only Bestellübergabe dokumentieren.
|
||||
- [ ] Technische Eingangstabelle und DB-Ownership für Shopify-Events festlegen.
|
||||
- [ ] Status- und Lagerübergaben zwischen den Modulen definieren.
|
||||
- [ ] Minimalen Identifier-Hand-off zwischen Import und Bestellungen definieren.
|
||||
- [ ] Fehler- und Teilfehlerverhalten pro Prozess definieren.
|
||||
|
||||
Reference in New Issue
Block a user