diff --git a/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_event_persistence.md b/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_event_persistence.md new file mode 100644 index 0000000..cddc5e7 --- /dev/null +++ b/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_event_persistence.md @@ -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. diff --git a/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_order_sync_handoff.md b/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_order_sync_handoff.md new file mode 100644 index 0000000..6b65a99 --- /dev/null +++ b/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_order_sync_handoff.md @@ -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. diff --git a/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_webhook_authentication.md b/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_webhook_authentication.md new file mode 100644 index 0000000..0b78ee9 --- /dev/null +++ b/docs/modules/erp/import-integration/processes/sub_processes/erp.import-integration.shopify_webhook_authentication.md @@ -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. diff --git a/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md b/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md index f61e5a7..6448c50 100644 --- a/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md +++ b/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md @@ -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.