Dokumentiere Shopify-Umstellungscheckliste

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.