Definiere Shopify-Webhook-Subprozesse

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.

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.

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.

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.