From b9c57fb01b5400ba06e2c62f40ef3102babcd4cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mathias=20Gla=CC=88ser?= Date: Wed, 12 Aug 2026 14:06:17 +0200 Subject: [PATCH] Dokumentiere Shopify-Umstellungscheckliste --- .../shopify-umstellung-checkliste.md | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs/modules/erp/import-integration/shopify-umstellung-checkliste.md diff --git a/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md b/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md new file mode 100644 index 0000000..91e5178 --- /dev/null +++ b/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md @@ -0,0 +1,206 @@ +# Shopify-Umstellung ERP – Arbeitscheckliste + +Stand: 2026-08-12 +Status: In Arbeit +Owning Bereich: `erp/import-integration` +Fachliche Übergabe: `erp/bestellungen` + +## Arbeitsregeln + +- [x] Shopify ist die führende Quelle für Shop-Bestellungen als Zielbild bestätigt. +- [x] Bestehende Bestellungen in der App bleiben erhalten. +- [x] Initiale Analyse und Migration sind read-only gegenüber Shopify. +- [x] Keine Shopify-Schreiboperationen, Kundenmails, Klaviyo-Ereignisse oder n8n-Nebenwirkungen während der Migration. +- [ ] Vor jeder App- oder DB-Änderung Zielmodell und Prozessvertrag abnehmen. +- [ ] Nach jeder App- oder DB-Änderung ausführliche Tests auf DEV über `ssh synology-hz` durchführen. +- [ ] Keine lokalen Runtime-, Scheduler- oder DB-Prüfungen verwenden. + +## 1. Sicherheits- und Scope-Gate + +- [x] Shopify-Admin-Zugang im Chrome read-only geprüft. +- [x] Vorhandene Shopify-Tags read-only geprüft. +- [x] Tag `wix-import` bei importierten Bestellungen belegt. +- [x] Neue Bestellungen ohne `wix-import` im GUI festgestellt. +- [ ] 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. + +## 2. Historische Zuordnung + +- [x] Shopify Order-GID und Shopify-Bestellnummer im GUI belegt. +- [x] Bei einer importierten Bestellung ist die alte Wix-Bestellnummer in der Shopify-Notiz vorhanden. +- [x] Belegt: `wix-import` ist ein Herkunftsmerkmal, kein ausreichender eindeutiger Zuordnungsschlüssel. +- [ ] Bestand der App-Bestellungen ermitteln. +- [ ] Bestand der Shopify-Bestellungen read-only ermitteln. +- [ ] Zuordnungstabelle für App-ID, Wix-Bestellnummer, Shopify-GID und Shopify-Bestellnummer erstellen. +- [ ] Eindeutigkeit der Zuordnung für alle historischen Bestellungen prüfen. +- [ ] Nicht eindeutig zuordenbare Datensätze als Klärfälle ausweisen. +- [ ] Abweichungen bei Anzahl, Summen, Positionen und Status dokumentieren. + +## 3. Shopify-Datenmapping + +- [ ] Shopify Order-GID als stabile externe Identität festlegen. +- [ ] Shopify-Bestellnummer separat speichern. +- [ ] Wix-Bestellnummer als historische Referenz speichern. +- [ ] Kunden- und Shopify-Customer-ID abbilden. +- [ ] Liefer- und Rechnungsadresse abbilden. +- [ ] Produkt-, Varianten- und SKU-Referenzen abbilden. +- [ ] Positionen, Mengen, Einzelpreise und Positionssummen abbilden. +- [ ] Rabatte, Steuern, Versandkosten, Währung und Gesamtsummen abbilden. +- [ ] Zahlungsstatus und Transaktionen abbilden. +- [ ] Storno- und Refund-Daten abbilden. +- [ ] Fulfillment-, Versand- und Tracking-Daten abbilden. +- [ ] Shopify-Tags und relevante Metafelder abbilden. +- [ ] Rohpayload und Synchronisationszeitpunkt abbilden. +- [ ] Feldmapping fachlich abnehmen. + +## 4. Ziel-Datenmodell + +- [ ] `sales_order` um Shopify-Identitäten erweitern. +- [ ] `order_source` um `shopify` erweitern. +- [ ] `external_ref` von der bisher gemischten Wix-/Direktverkaufssemantik entkoppeln. +- [ ] Zahlungsstatus über den bisherigen ausschliesslichen Wert `paid` hinaus modellieren. +- [ ] Fulfillment-Status modellieren. +- [ ] Storno- und Refund-Status modellieren. +- [ ] Shopify-Kunden-, Produkt- und Variantenreferenzen ergänzen. +- [ ] Synchronisations- und Reconciliation-Status ergänzen. +- [ ] Shopify-Rohdaten versioniert oder nachvollziehbar speichern. +- [ ] Datenbank-Constraints und Indizes definieren. +- [ ] Bestehende Wix-Daten und Direktverkaufsdaten rückwärtskompatibel erhalten. +- [ ] DB-Ownership für alle neuen Artefakte dokumentieren. +- [ ] Zielmodell als verbindlich abnehmen. + +## 5. Prozess- und Modulgrenzen + +- [x] `erp/bestellungen` als Eigentümer der Bestellfachlichkeit bestätigt. +- [x] `erp/import-integration` als Eigentümer der technischen Eingangsschnittstellen bestätigt. +- [ ] Prozess `shopify.orders.migrate` definieren. +- [ ] Prozess `shopify.orders.receive` definieren. +- [ ] Prozess `shopify.orders.reconcile` definieren. +- [ ] Status- und Lagerübergaben zwischen den Modulen definieren. +- [ ] Minimalen Identifier-Hand-off zwischen Import und Bestellungen definieren. +- [ ] Fehler- und Teilfehlerverhalten pro Prozess definieren. +- [ ] Output-Payloads und Audit-Ergebnisse definieren. + +## 6. Shopify-API und Webhooks + +- [ ] Read-only-Admin-API konfigurieren. +- [ ] Verbindliche Shopify-API-Version festlegen. +- [ ] Zugangsdaten sicher in DEV-Konfiguration hinterlegen. +- [ ] GraphQL-Abfragen für Initialbestand definieren. +- [ ] Webhook für neue Bestellungen definieren. +- [ ] Webhooks für Änderungen, Stornos, Refunds und Fulfillments definieren. +- [ ] Shopify-HMAC-Signatur prüfen. +- [ ] Doppelte und verspätete Webhooks idempotent verarbeiten. +- [ ] Webhook-Empfang von fachlicher Verarbeitung trennen. +- [ ] Fehlerhafte Eingänge nachvollziehbar protokollieren. +- [ ] Regelmässigen read-only-Abgleich definieren. +- [ ] Testwebhook ohne externe Nebenwirkungen nachweisen. + +## 7. Historische Migration + +- [ ] Shopify-Bestand vollständig read-only abrufen. +- [ ] Bestellungen über definierte Referenzen zuordnen. +- [ ] Bestehende App-Bestellungen aktualisieren, nicht neu duplizieren. +- [ ] Historische Wix-Referenzen erhalten. +- [ ] Shopify-Felder normalisieren. +- [ ] Nicht gemappte Artikel als Mapping-Lücke protokollieren. +- [ ] Keine bestehenden Lagerbewegungen ungeprüft rückabwickeln. +- [ ] Keine Label-, Excel-, Klaviyo- oder Kundenmail-Trigger ausführen. +- [ ] Migration in kontrollierten Batches ausführen. +- [ ] Teilfehler pro Bestellung tolerant protokollieren. +- [ ] Technische Totalfehler hart abbrechen. +- [ ] Batch-Ergebnisse und Wiederanlauf dokumentieren. +- [ ] Historische Migration fachlich abnehmen. + +## 8. Laufender Synchronisationsprozess + +- [ ] Neue Shopify-Bestellungen synchronisieren. +- [ ] Bestehende Shopify-Bestellungen aktualisieren. +- [ ] Kunden- und Adressdaten synchronisieren. +- [ ] Positionen synchronisieren. +- [ ] Zahlungen synchronisieren. +- [ ] Stornos und Refunds synchronisieren. +- [ ] Fulfillments und Tracking synchronisieren. +- [ ] Tags und relevante Metafelder synchronisieren. +- [ ] Shopify-Status nicht blind auf ERP-Status abbilden. +- [ ] ERP-Daten nicht unkontrolliert nach Shopify zurückschreiben. +- [ ] Keine Kundenkommunikation aus dem Sync auslösen. +- [ ] Klaviyo nicht mit historischen Bestellungen erneut triggern. + +## 9. Lager- und Nebenwirkungsprüfung + +- [ ] Fachlich definieren, welche Shopify-Ereignisse Lagerbewegungen auslösen. +- [ ] Doppelabbuchungen bei historischen Wix-Bestellungen verhindern. +- [ ] 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. + +## 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. +- [ ] 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. +- [ ] Verpasste Webhooks über Reconciliation erkennen. +- [ ] Keine Shopify-Schreiboperationen nachweisen. +- [ ] Keine Kundenmails nachweisen. +- [ ] Keine Klaviyo-Doppelevents nachweisen. +- [ ] Keine unerwarteten n8n-Aufrufe nachweisen. + +## 11. Produktivsetzung + +- [ ] Read-only-Migration abgenommen. +- [ ] Datenmodell und Prozessverträge abgenommen. +- [ ] Webhooks produktiv registriert. +- [ ] Monitoring und Fehlerprotokoll aktiv. +- [ ] Reconciliation aktiviert. +- [ ] Kundenmail- und Klaviyo-Schutz erneut geprüft. +- [ ] Rollback- und Wiederanlaufverfahren dokumentiert. +- [ ] Produktivstart in kontrolliertem Zeitfenster durchgeführt. +- [ ] Erste Produktivläufe fachlich geprüft. + +## 12. Nachlauf und Bereinigung + +- [ ] Wix-spezifischen Eingangspfad als abgelöst dokumentieren. +- [ ] Nicht mehr benötigte n8n-Mailtrigger deaktivieren. +- [ ] Keine ungeprüften Legacy-Fallbacks einführen. +- [ ] Historische Wix-Referenzen dauerhaft erhalten. +- [ ] Modul- und Prozessdokumentation aktualisieren. +- [ ] API-Berechtigungen auf tatsächlich benötigte Rechte reduzieren. +- [ ] Offene Klärfälle abschliessen. + +## Aktueller Fortschritt + +Erledigte Grundlagen: + +- Shopify-Shop und Bestellliste im eingeloggten Chrome read-only geprüft. +- Tag `wix-import` und historische Wix-Bestellnummer in Shopify-Notiz belegt. +- Aktuelle Wix-Kopplung im Datenmodell und Importpfad identifiziert. +- Aktuelle n8n-Nebenwirkungen im Importpfad identifiziert. +- Verbindliche technische Architektur und Modulgrenzen geprüft. + +Aktueller Arbeitsstand: + +- Phase 1: teilweise erledigt +- Phase 2: strukturelle Prüfung begonnen +- Phase 3–12: offen + +Aktueller Blocker: + +- Der vorgeschriebene DEV-DB-Wrapper `/volume2/webssd/erpnaurua/dev/scripts/db/psql.sh` ist auf Synology nicht vorhanden. +- Ohne diesen freigegebenen Zugriff werden keine alternativen DB-Zugriffe verwendet. +- Die Bestandszählung und die vollständige historische Zuordnung bleiben bis zur Klärung offen. + +## Abnahmeregel + +Eine Checkbox wird nur abgehakt, wenn die Erledigung durch Code, Datenbankabfrage, Testlauf, GUI-Prüfung oder Dokumentation belegt ist. Bei App- oder DB-Änderungen werden zusätzlich die betroffenen Tests, DEV-Ausführung und Ergebnisse direkt bei der jeweiligen Phase dokumentiert.