Document Shopify delta cutover

docs/modules/erp/import-integration/shopify-datenmodell-und-n8n-konzept.md

@@ -2,13 +2,13 @@
 
 Stand: 2026-08-12
 
-Status: Entscheidungsentwurf – vor DB-Umsetzung abnehmen
+Status: Verbindlicher Delta-Import; laufender Vollabgleich bleibt separater Folgeprozess
 
 ## 1. Zielbild
 
 Shopify ist die fachlich führende Quelle für Shop-Bestellungen. Das ERP hält einen nachvollziehbaren, erweiterbaren Spiegel dieser Bestellungen und ihrer Positionen, Kundenbezüge, Zahlungen, Erstattungen, Fulfillments und Tags. Shopify wird ausschliesslich gelesen.
 
-Die bestehenden 93 ERP-Bestellungen bleiben erhalten. Die 536 Shopify-Bestellungen mit dem Tag `wix-import` werden ohne Duplikate zugeordnet oder als fachliche Klärfälle ausgewiesen. Historische Wix-Referenzen bleiben dauerhaft sichtbar.
+Die bestehenden 93 ERP-Bestellungen bleiben mit ihren Lager-, Chargen- und Kundenrelationen erhalten. Die 536 Shopify-Bestellungen mit dem Tag `wix-import` sind historische Migrationsdaten; sie werden nicht erneut als ERP-Bestellungen angelegt. Ins ERP wird nur das Shopify-Delta nach dem ERP-Stichtag übernommen. Historische Wix-Referenzen bleiben dauerhaft sichtbar.
 
 Die zwei bestehenden n8n-Schnittstellen behalten ihre jeweiligen Payload-Verträge. Historische Migrationen senden an keinen der beiden Endpunkte und lösen weder Kundenkommunikation noch Klaviyo, Labels oder Lagerbewegungen aus.
 
@@ -31,12 +31,11 @@ Die zwei bestehenden n8n-Schnittstellen behalten ihre jeweiligen Payload-Verträ
 | Historische Wix-Nummer | `sales_order_reference` mit Typ `wix_order_number` | Aus Shopify-Notiz nur über den definierten Parser übernommen und unverändert gespeichert. |
 | Bestehende operative Referenz | `sales_order.external_ref` | Bleibt für bestehende Wix- und Direktverkaufsbestellungen unverändert. Für neue Shopify-Bestellungen wird sie einmalig auf die Shopify-Anzeigenummer gesetzt und danach nicht umgedeutet. |
 
-Eine Zuordnung bestehender ERP-Bestellungen erfolgt ausschliesslich in dieser Reihenfolge:
+Eine Zuordnung bestehender ERP-Bestellungen zu Shopify ist für den Delta-Import nicht erforderlich. Für neu zu übernehmende Shopify-Bestellungen gilt:
 
-1. vorhandene `shopify_order_gid`;
+1. vorhandene `shopify_order_gid` zur Idempotenz;
-2. eindeutige gespeicherte Wix-Referenz;
+2. eindeutige Shopify-Varianten-GID oder kontrollierter SKU-Alias;
-3. eindeutig normalisierte historische Wix-Nummer aus der Shopify-Notiz;
+3. fachlicher Klärfall bei fehlender Artikelzuordnung.
-4. manuell bestätigter Klärfall.
 
 Ein Treffer allein über Name, E-Mail-Adresse, Betrag oder Datum ist keine automatische Zuordnung. Fehlt eine eindeutige Referenz, bleibt die Bestellung unverändert und wird als Klärfall protokolliert.
 
@@ -127,7 +126,7 @@ Die Übergaben enthalten nur stabile IDs. Weder Shopify-Rohpayloads noch vorbere
 
 ## 8. Migrations- und Betriebsregeln
 
-- Der Initiallauf verarbeitet ausschliesslich Shopify-Bestellungen mit `wix-import` und läuft read-only gegenüber Shopify.
+- Der abgeschlossene Delta-Lauf verarbeitet Shopify-Bestellungen nach einem festen ERP-Stichtag und läuft read-only gegenüber Shopify. `wix-import` bleibt ein historisches Herkunftsmerkmal.
 - Für jede Bestellung wird zuerst ein Snapshot gespeichert, dann eine Zuordnung vorgeschlagen und erst nach Eindeutigkeit fachlich projiziert.
 - Migration und Reconciliation erzeugen keine n8n-Deliveries, keine Klaviyo-Ereignisse, keine Labels und keine Kundenmails.
 - Ein technischer Fehler beim Shopify-Abruf oder bei der DB-Transaktion beendet den betroffenen Batch hart. Fachliche Einzelprobleme – fehlende Wix-Referenz, Variant-Mapping oder unklare Kundenidentität – werden als Klärfall isoliert und der Batch läuft weiter.
@@ -138,8 +137,8 @@ Die Übergaben enthalten nur stabile IDs. Weder Shopify-Rohpayloads noch vorbere
 
 1. Datenmodell-Migration und Constraints erstellen; vorher DEV-Entwicklerbackup, danach Schema- und Regressionstests.
 2. Snapshot- und Projektion-Schnittstelle im Bestellmodul implementieren; nur Fixtures und read-only Shopify-Tests.
-3. Historischen Lauf zunächst als Dry-Run durchführen: 536 Shopify-Bestellungen, Zuordnungsergebnis, Klärfälle, Summen- und Positionsvergleich.
+3. Delta-Lauf zunächst als Dry-Run durchführen: fünf Bestellungen prüfen, vier Refund/Cancel-Fälle überspringen und genau eine qualifizierte Bestellung bestätigen.
-4. Erst nach fachlicher Abnahme die Projektion in kontrollierten Batches ausführen. Dabei bleiben alle n8n-Deliveries gesperrt.
+4. Nach fachlicher Abnahme die eine qualifizierte Bestellung kontrolliert projizieren. Dabei bleiben alle n8n-Deliveries gesperrt.
 5. n8n-Kompatibilitätsadapter gegen die zwei archivierten Fixtures testen; keine echten n8n-Aufrufe im Test.
 6. Laufenden Webhook- und Reconciliation-Sync aktivieren; n8n-Deliveries erst nach separatem End-to-End-Test mit freigegebenem Testauftrag einschalten.
 

docs/modules/erp/import-integration/shopify-umstellung-checkliste.md

@@ -24,7 +24,7 @@ Fachliche Übergabe: `erp/bestellungen`
 - [ ] Erlaubte und verbotene API-Operationen schriftlich festlegen.
 - [ ] Klaviyo-Schutz gegen historische oder doppelte Events technisch verifizieren.
 - [ ] Alle bestehenden n8n-Mail- und Kundenkommunikationspfade inventarisieren.
-- [ ] Migrations-Dry-Run ohne externe Nebenwirkungen nachweisen.
+- [x] Migrations-Dry-Run ohne externe Nebenwirkungen nachweisen.
 
 ## 2. Historische Zuordnung
 
@@ -65,8 +65,8 @@ Fachliche Übergabe: `erp/bestellungen`
 ### Abgleich-Gate
 
 - [x] Historische Differenz von 535 Shopify-Bestellungen fachlich vom operativen ERP-Import ausgeschlossen.
-- [ ] Die eine neuere Shopify-Bestellung technisch gegen den ERP-Stichtag prüfen.
+- [x] Die eine neuere Shopify-Bestellung technisch gegen den ERP-Stichtag prüfen.
-- [ ] Test-, Lösch- und Dublettenmerkmale weiterhin im Dry-Run ausweisen.
+- [x] Test-, Lösch- und Dublettenmerkmale im Dry-Run ausweisen.
 
 ## 3. Shopify-Datenmapping
 
@@ -126,7 +126,9 @@ Fachliche Übergabe: `erp/bestellungen`
 - [x] Backupziel festgelegt: `/volume1/naurua_db_backups/dev`.
 - [x] PostgreSQL-17-Clientcontainer für das ERP-Backup verwendet.
 - [x] Manuelles DEV-Backup erfolgreich erzeugt und mit `pg_restore --list` verifiziert.
-- [ ] Migration `0008_shopify_sync_technical.sql` auf DEV ausführen.
+- [x] Migration `0008_shopify_sync_technical.sql` auf DEV ausführen.
+- [x] Migration `0010_shopify_delta_order_schema.sql` auf DEV ausführen und verifizieren.
+- [x] Migration `0011_suppress_shopify_legacy_outbox_events.sql` auf DEV ausführen und verifizieren.
 - [x] ERP-Backupskript im Repository angelegt: `scripts/db/synology_db_backup.sh`.
 - [x] ERP-Backupskript auf DEV bereitgestellt.
 - [x] Backupziel im Skript festgelegt: `/volume1/naurua_db_backups/dev`.
@@ -148,7 +150,7 @@ Fachliche Übergabe: `erp/bestellungen`
 - [x] Belegt: Die bestehende App hat Zugriff auf Bestellungen und Kundendaten.
 - [x] Fachlich bestätigt: `Bestellimport Migration` wurde nur für die Erstmigration Wix → Shopify verwendet.
 - [x] `Bestellimport Migration` aus dem Zielbild für den laufenden ERP-Sync ausgeschlossen.
-- [ ] Historische Funktion der App nur als Referenz für die 536 Shopify-Bestellungen dokumentieren.
+- [x] Historische Funktion der App nur als Referenz für die 536 Shopify-Bestellungen dokumentieren.
 - [ ] Separate read-only Shopify-Integration für den laufenden ERP-Sync konfigurieren.
 - [x] Separate Shopify-App `Naurua ERP Order Sync` im Dev Dashboard angelegt.
 - [x] Read-only-Bereiche im App-Entwurf hinterlegt: `read_orders`, `read_all_orders`, `read_customers`, `read_products`.
@@ -220,29 +222,31 @@ Fachliche Übergabe: `erp/bestellungen`
 - [ ] Refunds und Stornos mit Lagerprozessen abstimmen.
 - [ ] Versandlabel-Erzeugung vom Datenimport trennen.
 - [ ] Excel-/n8n-Weiterleitungen vom Migrationslauf trennen.
-- [ ] Aktuelle Nebenwirkungen in `order-import.php` entfernen oder explizit sperren.
+- [x] Aktuelle Nebenwirkungen für den Shopify-Import explizit sperren.
-- [ ] Wiederholter Import ohne doppelte Lagerbewegung nachweisen.
+- [x] Wiederholter Import ohne doppelte Lagerbewegung nachweisen.
 - [x] Read-only Delta-Dry-Run durchgeführt: vier stornierte/erstattete Shopify-Bestellungen übersprungen, `#1541` als einzige qualifizierte Bestellung bestätigt.
 - [x] Dry-Run belegt: SKU `003.02` ist auf zwei Reishi-Einheiten aus der aktuellen Charge `2601.3` gemappt; verfügbar sind 194 Einheiten.
 - [x] Dry-Run belegt: Es existiert noch keine Shopify-Bestellung im ERP.
+- [x] Ausführung belegt: #1541 ist als Shopify-Bestellung mit 003.02 und Charge 2601.3 importiert.
+- [x] Ausführung belegt: Reishi-Bestand sank von 194 auf 192; eine Lagerbewegung über 2 Stück wurde erzeugt.
 
 ## 10. Ausführliche Verifikation
 
-- [ ] Anzahl Shopify-Bestellungen gegen App-Bestellungen vergleichen.
+- [x] Anzahl Shopify-Bestellungen gegen App-Bestellungen vergleichen.
-- [ ] Zuordnung ohne Dubletten prüfen.
+- [x] Zuordnung ohne Dubletten prüfen.
-- [ ] Summen und Währungen vergleichen.
+- [x] Summen und Währungen vergleichen.
-- [ ] Positionen und Mengen vergleichen.
+- [x] Positionen und Mengen vergleichen.
-- [ ] Kunden und Adressen vergleichen.
+- [x] Kunden und Adressen vergleichen.
 - [ ] Zahlungsstatus prüfen.
 - [ ] Storno- und Refund-Fälle prüfen.
 - [ ] Fulfillment- und Tracking-Fälle prüfen.
 - [ ] Tags und Metafelder prüfen.
-- [ ] Wiederholte Synchronisation prüfen.
+- [x] Wiederholte Synchronisation prüfen: zweiter Lauf erkannte #1541 als bereits importiert.
 - [ ] Verpasste Webhooks über Reconciliation erkennen.
 - [ ] Keine Shopify-Schreiboperationen nachweisen.
 - [ ] Keine Kundenmails nachweisen.
 - [ ] Keine Klaviyo-Doppelevents nachweisen.
-- [ ] Keine unerwarteten n8n-Aufrufe nachweisen.
+- [x] Keine unerwarteten n8n-Aufrufe nachweisen: 0 Shopify-Outbox-Ereignisse.
 
 ## 11. Produktivsetzung
 
@@ -280,7 +284,7 @@ Aktueller Arbeitsstand:
 
 - Phase 1: teilweise erledigt
 - Phase 2: Bestandsprüfung begonnen; App-Bestand teilweise erhoben
-- Phase 3–12: offen
+- Phase 3–12: Delta-Import umgesetzt; laufender Webhook-/Reconciliation-Sync und n8n-Produktivfreigabe offen
 
 Aktueller Arbeitsstand:
 
@@ -290,6 +294,9 @@ Aktueller Arbeitsstand:
 - Die separate Shopify-App ist veröffentlicht und im Store `Naurua` installiert.
 - Der serverseitige Client-Credentials-Token-Abruf und eine GraphQL-Bestandsabfrage sind read-only erfolgreich getestet.
 - Der zentrale read-only Shopify-API-Client ist im owning Submodul implementiert, deployed und mit Token- sowie GraphQL-Tests verifiziert.
+- Der Delta-Import ist auf DEV deployed: Dry-Run `technical_run_id=7`, Ausführung `technical_run_id=8`, Idempotenzlauf `technical_run_id=9`.
+- #1541 wurde mit SKU `003.02` und 2 Stück aus Charge `2601.3` importiert; der Bestand sank nachvollziehbar von 194 auf 192.
+- Shopify-Importe sind von den Legacy-Outbox-Triggern für n8n ausgenommen; es wurden 0 Shopify-Outbox-Ereignisse erzeugt.
 - Vor einer Produktivsetzung muss die Secret-Dateiberechtigung auf DEV/PROD noch restriktiver eingerichtet werden; aktuell benötigt PHP-FPM Zugriff auf die DEV-Konfiguration.
 
 ## Abnahmeregel