diff --git a/docs/modules/erp/import-integration/shopify-datenmodell-und-n8n-konzept.md b/docs/modules/erp/import-integration/shopify-datenmodell-und-n8n-konzept.md index 471259d..38c8620 100644 --- a/docs/modules/erp/import-integration/shopify-datenmodell-und-n8n-konzept.md +++ b/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`; -2. eindeutige gespeicherte Wix-Referenz; -3. eindeutig normalisierte historische Wix-Nummer aus der Shopify-Notiz; -4. manuell bestätigter Klärfall. +1. vorhandene `shopify_order_gid` zur Idempotenz; +2. eindeutige Shopify-Varianten-GID oder kontrollierter SKU-Alias; +3. fachlicher Klärfall bei fehlender Artikelzuordnung. 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. -4. Erst nach fachlicher Abnahme die Projektion in kontrollierten Batches ausführen. Dabei bleiben alle n8n-Deliveries gesperrt. +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. 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. diff --git a/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md b/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md index 3db2166..c8371c1 100644 --- a/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md +++ b/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. -- [ ] Test-, Lösch- und Dublettenmerkmale weiterhin im Dry-Run ausweisen. +- [x] Die eine neuere Shopify-Bestellung technisch gegen den ERP-Stichtag prüfen. +- [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. -- [ ] Wiederholter Import ohne doppelte Lagerbewegung nachweisen. +- [x] Aktuelle Nebenwirkungen für den Shopify-Import explizit sperren. +- [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. -- [ ] Zuordnung ohne Dubletten prüfen. -- [ ] Summen und Währungen vergleichen. -- [ ] Positionen und Mengen vergleichen. -- [ ] Kunden und Adressen vergleichen. +- [x] Anzahl Shopify-Bestellungen gegen App-Bestellungen vergleichen. +- [x] Zuordnung ohne Dubletten prüfen. +- [x] Summen und Währungen vergleichen. +- [x] Positionen und Mengen 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