Bereite Shopify Bestellprojektion vor

2026-08-12 17:42:10 +02:00
parent 0e4c9219bf
commit 6e4925cdb6
3 changed files with 164 additions and 4 deletions
@@ -0,0 +1,114 @@
+# erp.bestellungen.shopify_order_projection
+Stand: 2026-08-12
+Status: Verbindliche Prozess-Spezifikation
+
+## 1. Zweck
+
+Eine qualifizierte Shopify-Bestellung anhand ihrer stabilen Shopify Order-GID idempotent als ERP-Bestellung, Position und Chargenallokation projizieren.
+
+## 2. Prozess-Einbettung
+
+Synchroner Sub-Prozess von `erp.import-integration.shopify_delta_order_import`. Das owning Modul `erp/bestellungen` besitzt die gesamte Bestellprojektion und die Übergabe an `erp/lager`.
+
+## 3. Input
+
+- `shopify_order_gid`
+- optional `dry_run`
+
+Keine vorbereiteten Kunden-, Adress-, Positions- oder Shopify-Rohdaten werden übergeben.
+
+## 4. Exakter Prozessablauf
+
+1. Shopify Order-GID und `dry_run` validieren.
+2. Die Bestellung über die definierte read-only Shopify-Quellschnittstelle laden.
+3. Vorhandene `sales_order.shopify_order_gid` idempotent prüfen.
+4. Shopify-Customer-GID über `party_external_identity` auflösen oder einen Kontakt über die definierte Kontaktschnittstelle anlegen und die externe Identität speichern.
+5. Jede Position ausschliesslich über den Shopify-Varianten-/SKU-Alias des Artikel-Mappings auf ein `sellable_item` auflösen.
+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.
+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.
+
+Read sources:
+
+- definierte read-only Shopify-Quellschnittstelle
+- `party_external_identity`, `party`, `address`
+- `external_item_alias`, `sellable_item`, `sellable_item_component`
+- `product`, `stock_lot`, `v_stock_lot_balance`
+- `sales_order` und `sales_order_line`
+
+Write targets:
+
+- `party`, `address`, `party_external_identity`
+- `sales_order`, `sales_order_line`
+- `external_item_alias` nur für fehlende Shopify-GIDs eines bereits bestätigten SKU-Alias
+- `sales_order_line_lot_allocation`, `stock_move` ausschliesslich über die Lagerschnittstelle
+
+## 5. Batch, Betriebsmodell und Einbettung
+
+Eine Shopify Order-GID pro synchronem Lauf. Die umgebende Delta-Verarbeitung ist seriell.
+
+## 6. Output
+
+Kompaktes Projektionsergebnis mit Status, ERP-Bestell-ID, Positionen und Allokationsanzahl.
+
+## 7. Erfolgskriterien
+
+- eine Shopify Order-GID führt zu höchstens einer ERP-Bestellung
+- jede Position ist eindeutig gemappt
+- die Chargenallokation entspricht den `sellable_item_component`-Mengen
+- `dry_run` schreibt keine fachlichen Daten
+- bestehende ERP-Bestellungen und ihre Chargenrelationen bleiben unverändert
+
+## 8. Fehlerschranke
+
+Ein fehlender Alias, unzureichender Lagerbestand oder ungültige Shopify-Daten ist ein fachlicher Klärfall und erzeugt keine Teilbestellung. Technische DB- oder Shopify-Fehler schlagen hart fehl.
+
+## 9. Fachliche Betriebsregel
+
+Nur qualifizierte neue Shopify-Bestellungen nach dem ERP-Stichtag werden lagerwirksam. Stornierte oder vollständig erstattete Bestellungen werden nicht an diesen Sub-Prozess übergeben.
+
+## 10. Sub-Prozess-Referenzen
+
+- `erp.artikel-mapping.shopify_item_resolution`
+- `erp.lager.sales_order_line_allocation`
+
+## 11. End-to-End Sub-Prozess-Kette
+
+Order-GID → Shopify read-only laden → Kontakt und Artikel auflösen → Dry-Run oder atomare Projektion → Chargenallokation → Ergebnis.
+
+## 12. Sub-Prozess-Wiederverwendung
+
+Bestehende Kontakt-, Artikel-Mapping- und Lagerfunktionen werden verwendet. Neue Fachlogik im Import-Submodul ist ausgeschlossen.
+
+## 13. Step-Liste
+
+1. `load_shopify_order`
+2. `resolve_shopify_party`
+3. `resolve_shopify_line_items`
+4. `allocate_sales_order_lines`
+5. `finalize_shopify_projection`
+
+## 14. Parallelisierung
+
+Nicht anwendbar.
+
+## 15. Output-Payload
+
+```json
+{
+  "status": "done|already_imported|clarification_required|failed",
+  "shopify_order_gid": "string",
+  "sales_order_id": 0,
+  "line_count": 0,
+  "allocation_count": 0,
+  "clarification_reasons": []
+}
+```
+
+## 16. Done-Kriterien
+
+- Projektion ist Shopify-GID-idempotent.
+- SKU/Varianten-Mapping und Lagerbestand werden vor Echtlauf vollständig geprüft.
+- Allokationen verwenden die bestehende Chargenlogik mit Shopify-Herkunftsvermerk.
+- Keine externen Kommunikations- oder Shopify-Schreibwirkungen entstehen.