diff --git a/docs/modules/erp/import-integration/processes/main/erp.import-integration.shopify_order_sync.md b/docs/modules/erp/import-integration/processes/main/erp.import-integration.shopify_order_sync.md index d89de27..5c493dc 100644 --- a/docs/modules/erp/import-integration/processes/main/erp.import-integration.shopify_order_sync.md +++ b/docs/modules/erp/import-integration/processes/main/erp.import-integration.shopify_order_sync.md @@ -24,14 +24,15 @@ Es werden keine vorbereiteten Geschäftsdaten an nachgelagerte Prozesse übergeb ## 4. Exakter Prozessablauf 1. HTTP-Methode und erforderliche Shopify-Header validieren. -2. HMAC-Signatur mit dem konfigurierten Shopify-App-Secret prüfen. +2. HMAC-Signatur mit dem konfigurierten Shopify-Client-Secret prüfen. 3. JSON-Body als technisches Eingangsdokument validieren. 4. Webhook-ID idempotent gegen bereits verarbeitete Eingänge prüfen. 5. Technischen Eingang mit Topic, Shop-Domain, Shopify-Webhooks-ID und Payload-Hash speichern. -6. Shopify Order-GID aus dem Ereignis oder durch den definierten Shopify-Read-Schritt bestimmen. -7. Nur die stabile Ereignis-/Order-Identität an das owning Bestellmodul übergeben. -8. Keine Shopify-Mutation, keine Fulfillment-Aktion, keine Label-Aktion, kein n8n-Versand und kein Klaviyo-Event auslösen. -9. Technischen Lauf mit kompaktem Ergebnis abschliessen. +6. Für definierte Shopify-Read-Schritte einen kurzlebigen Admin-API-Token über den Client-Credentials-Flow beziehen; der Token wird ausschließlich serverseitig verwendet. +7. Shopify Order-GID aus dem Ereignis oder durch den definierten Shopify-Read-Schritt bestimmen. +8. Nur die stabile Ereignis-/Order-Identität an das owning Bestellmodul übergeben. +9. Keine Shopify-Mutation, keine Fulfillment-Aktion, keine Label-Aktion, kein n8n-Versand und kein Klaviyo-Event auslösen. +10. Technischen Lauf mit kompaktem Ergebnis abschliessen. Read sources: @@ -39,6 +40,13 @@ Read sources: - Shopify-API nur read-only, sofern für die Ereignisidentität erforderlich - eigene technische Importzustandsdaten +Authentifizierung: + +- Die interne Dev-Dashboard-App nutzt den Shopify-Client-Credentials-Flow. +- `SHOPIFY_CLIENT_ID`, `SHOPIFY_CLIENT_SECRET` und `SHOPIFY_SHOP` werden ausschließlich aus der serverseitigen DEV-Konfiguration gelesen. +- Admin-API-Tokens werden nicht im Repository, nicht im Frontend und nicht im Response gespeichert. +- Ein interaktiver OAuth-Callback ist für dieses API-only-Ziel nicht Teil des Zielprozesses. + Public endpoint: - `POST https://erpnaurua.imhochrain.ch/api/shopify/webhooks.php` @@ -120,6 +128,7 @@ Keine Rohpayloads, Kundendaten oder Geschäftsdatasets werden im Response-Payloa - Prozess und Sub-Prozesse sind dokumentiert. - Endpoint validiert Shopify-HMAC und Pflichtheader. +- Server kann für read-only Shopify-Abfragen einen Client-Credentials-Token beziehen. - Duplicate-Webhook ist idempotent. - technische Eingangsdaten und Prozesslauf sind nachvollziehbar. - die Bestellübergabe bleibt auf stabile Identitäten begrenzt. diff --git a/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md b/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md index 7b427fd..34abffc 100644 --- a/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md +++ b/docs/modules/erp/import-integration/shopify-umstellung-checkliste.md @@ -11,8 +11,8 @@ Fachliche Übergabe: `erp/bestellungen` - [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. +- [x] Zielmodell und Prozessvertrag vor der technischen Webhook-Annahme festgelegt. +- [x] Nach den bisherigen App- und DB-Änderungen ausführliche Tests auf DEV über `ssh synology-hz` durchgeführt. - [ ] Keine lokalen Runtime-, Scheduler- oder DB-Prüfungen verwenden. ## 1. Sicherheits- und Scope-Gate @@ -148,7 +148,8 @@ Fachliche Übergabe: `erp/bestellungen` - [x] Read-only-Bereiche im App-Entwurf hinterlegt: `read_orders`, `read_all_orders`, `read_customers`, `read_products`. - [ ] App-Version veröffentlichen, sobald Callback- und Webhook-Registrierung vollständig sind. - [x] App-URL festgelegt und im Entwurf hinterlegt: `https://erpnaurua.imhochrain.ch/`. -- [x] OAuth-Callback-URL im Entwurf auf `.php` korrigiert: `https://erpnaurua.imhochrain.ch/api/shopify/oauth/callback.php`. +- [x] Authentifizierungsweg festgelegt: serverseitiger Client-Credentials-Flow für die interne Dev-Dashboard-App. +- [x] Interaktiver OAuth-Callback als für das API-only-Ziel nicht erforderlich bewertet. - [x] Webhook-URL implementiert: `https://erpnaurua.imhochrain.ch/api/shopify/webhooks.php`. - [ ] Webhook-URL in Shopify registrieren. - [x] Belegt: Root-Domain ist erreichbar. @@ -158,7 +159,9 @@ Fachliche Übergabe: `erp/bestellungen` - [x] Test-Events und Test-Prozessläufe nach dem Test vollständig gelöscht. - [x] Test-Secret nach dem Test aus DEV entfernt. - [ ] Verbindliche Shopify-API-Version festlegen. -- [ ] Zugangsdaten sicher in DEV-Konfiguration hinterlegen. +- [ ] Client-ID, Client-Secret und Shop-Domain sicher in DEV-Konfiguration hinterlegen. +- [ ] Shopify-App installieren; erst danach Client-Credentials-Token beziehen. +- [ ] Client-Credentials-Token-Abruf read-only testen. - [ ] GraphQL-Abfragen für Initialbestand definieren. - [ ] Webhook für neue Bestellungen definieren. - [ ] Webhooks für Änderungen, Stornos, Refunds und Fulfillments definieren. @@ -266,16 +269,12 @@ Aktueller Arbeitsstand: - Phase 2: Bestandsprüfung begonnen; App-Bestand teilweise erhoben - Phase 3–12: offen -Aktueller Blocker: +Aktueller Arbeitsstand: -- Der vorgeschriebene DEV-DB-Wrapper `/volume2/webssd/erpnaurua/dev/scripts/db/psql.sh` ist auf Synology nicht vorhanden. -- Auf ausdrückliche Anweisung wurde ein read-only-Direktzugriff über `/usr/bin/psql` verwendet. -- Die vollständige Shopify-Bestandszählung und historische Zuordnung bleiben weiterhin offen. -- Der Cron-Aufruf erreicht das Skript und verwendet den PostgreSQL-17-Clientcontainer. -- Das Backupziel ist `/volume1/naurua_db_backups/dev`. -- Der Logpfad ist `/volume1/naurua_db_backups/dev/synology_db_backup.log`. -- Ein gültiger DEV-Dump wurde erzeugt und mit `pg_restore --list` verifiziert. -- Die DB-Migration wurde nach dem Backup noch nicht ausgeführt. +- Die technische Webhook-Annahme ist auf DEV implementiert und getestet. +- Die technische DB-Migration `0008_shopify_sync_technical.sql` ist auf DEV ausgeführt und verifiziert. +- DEV-Backups laufen über den PostgreSQL-17-Clientcontainer; ein Dump wurde erzeugt und mit `pg_restore --list` verifiziert. +- Der nächste externe Schritt ist die Installation der separaten Shopify-App und die anschließende read-only Token-/GraphQL-Prüfung. ## Abnahmeregel