Kostenlos testen
Handbuch

Shopify-App "TaskMonkey"

Eine App, drei Module: Kundenservice-Chat, Shop-Assistent für Mitarbeiter (ApprovalGate-gesichert), SEO-Texte (geplant, nicht auf der App-Seite). MVP für die Vorführung bei FSR.

MVP-Stand, Branch feature/shopify-app (nicht auf main, nicht deployed). Ziel: Vorführung in einem Shopify-Entwicklungsshop (kein App-Store-Review), danach eigene Verteilung an Pilot-Shops.

Eine App "TaskMonkey", drei Module (18.10. erweitert):

  1. Kundenservice-Chat (Widget im Shop-Frontend, Wissen, Bestellstatus) — MVP, siehe unten.
  2. Shop-Assistent für Mitarbeiter (Chat in der eingebetteten Admin-Seite, ähnlich Shopify Sidekick) — MVP, Kern der FSR-Demo, siehe Modul-2-Abschnitt.
  3. SEO-Texte mit Freigabe (Produktbeschreibung/Meta-Titel/Alt-Texte als Entwurf) — noch nicht gebaut; seit 17.11. keine Platzhalter-Kachel mehr auf der App-Seite (App Store 2.1.2).

Nicht verwechseln mit dem bestehenden manuellen Shopify-Connector (/manage/shop-setup, ShopSetupService::connectShopify, feste Zugangsdaten/Token, die ein Shop-Betreiber selbst in seinem Shopify-Admin anlegt). Diese App hier ist TaskMonkeys eigene, im Shopify-Dashboard registrierte App — ein Shop installiert sie mit einem Klick, kein manuelles App-Anlegen im Shopify-Admin nötig. Unter der Haube wiederverwendet die Installation aber genau diesen Connector (siehe Architektur).

Architektur

Shopify-Admin (Merchant)
  └─ installiert App (managed install flow, Shopify-Dashboard-Konfig)
       │
       ▼
GET /shopify/app?shop=…&host=…         ShopifyController::app()
  (eingebettete Seite, iframe im Shopify-Admin, App Bridge)
       │  App Bridge holt Session-Token (id_token), JS ruft:
       ▼
POST /shopify/app/bootstrap             ShopifyController::bootstrap()
  Authorization: Bearer <id_token>
       │
       ├─ ShopifySessionToken::verify()   (aud=client_id, dest=shop, exp)
       ├─ ShopifyOAuth::tokenExchange()   (Token Exchange, Offline-Token)
       └─ ShopifyAppService::provision()
            ├─ SignupService::createTenantForExistingUser()   (Workspace + Branchen-
            │    Vorlage "shop-service" — Bestellstatus/Retoure/FAQ-Tools
            │    sind darin schon enthalten)
            ├─ ShopSetupService::applySettings()/connectShopify()  (Token
            │    speichern wie beim bestehenden manuellen Connector)
            └─ ShopSetupService::importShopPages()   (Versand/Rückgabe/FAQ/
                 Impressum -> öffentliche Wissensbasis, ShopPageImporter)
       │
       ▼
  shopify_app_installs (shop_domain <-> Workspace-Code)

Fallback (kein App-Bridge-Kontext): GET /shopify/install -> klassischer
OAuth-Code-Flow -> GET /shopify/callback -> dieselbe provision()-Kette.

POST /shopify/webhooks   ShopifyWebhooksController::receive()
  app/uninstalled, customers/data_request, customers/redact, shop/redact
  (Inhalt: ShopifyPrivacy, siehe "Datenschutz-Webhooks"),
  app_subscriptions/update (ShopifyBilling, siehe "Managed Pricing")
  (HMAC: WebhookSigner::verifyShopify, bereits vorhanden; Fehler -> 500,
  Shopify wiederholt)
  uri in shopify.app.toml ABSOLUT: relative uri haengt Shopify an den Pfad
  der application_url an (-> /shopify/app/shopify/webhooks, dort Alias-Route)

POST /shopify/app/link   frischer Einmal-Link fuer "Shop-Assistent öffnen"
  bzw. "Einstellungen" beim Klick (Session-Token), neuer Tab

Modul 2 (Shop-Assistent, in derselben /shopify/app-Seite als iframe):
  status.staffChatUrl (ShopifyAppService::mintBackendBridgeLink)
    -> GET /users/app-bridge?token=<jwt>&next=/manage/tasks/chat/shop_assistent_mitarbeiter?embed=1
    -> derselbe interne Chat wie ueberall sonst (TasksController, chat-internal.js)

Bewusste Wiederverwendung (nicht doppelt gebaut):

Braucht die App MVP-Punkt Code
Wissen automatisch (#3) ShopSetupService::importShopPages / ShopPageImporter — für Shopify-Workspaces seit 18.10. über die Admin API (siehe "Wissen aus Shopify"), sonst Crawl wie bisher
"Wo ist meine Bestellung?" (#5) config/tenants/_shared/tools/shop/getOrderStatus.php + getShopifyOrder.php, checkReturn.php, createReturnRequest.php, getShopFaq.php — bereits Teil der Branchen-Vorlage shop-service, keine neuen Tools nötig
Workspace anlegen SignupService::createTenantForExistingUser
Zugangsdaten speichern ShopSetupService::connectShopify (derselbe Weg wie beim manuellen Connector — Shopify-Access-Token beginnt in beiden Fällen mit shpat_…)
Webhook-HMAC WebhookSigner::verifyShopify
JWT (App-Bridge "im Backend öffnen") UsersController::appBridge — Einmal-Link mit eigenem abgeleiteten Schlüssel (App\Auth\BridgeTokenStore), siehe "Wer sitzt am Assistenten?"

Neu gebaut:

  • src/Service/Shopify/ShopifyOAuth.php — Domain-Validierung, signiertes State (Fallback-Install), Query-HMAC-Prüfung des OAuth-Callbacks, Code- Exchange und Token-Exchange.
  • src/Service/Shopify/ShopifySessionToken.php — prüft das eingebettete Session-Token (id_token) von App Bridge.
  • src/Service/Shopify/ShopifyAppService.php — Orchestrierung (Workspace sicherstellen, Connector + Wissens-Import anstoßen, shopify_app_installs pflegen, Uninstall/GDPR-Webhooks).
  • src/Controller/ShopifyController.php + ShopifyWebhooksController.php — eigene Controller statt /api/v1/hooks (Begründung analog ConnectInstagramController: Plattform-Endpunkte ohne Workspace, Format passt nicht ins generische Pro-Tenant-Hook-Modell — siehe Klassen- Doc-Kommentare).
  • Migration CreateShopifyAppInstalls — Plattform-Tabelle shopify_app_installs (nur shop_domain <-> Workspace-Code, kein Token darin — das Token liegt wie beim manuellen Connector verschlüsselt (seit 17.11.2026, TenantSecrets::ENCRYPTED_KEYS, Bestand: bin/cake oauth_reencrypt --apply) in der Tenant-.env).
  • shopify-app/ — Theme App Extension (Chat-Widget als App-Embed-Block)
    • shopify.app.toml.

Modul 2: Shop-Assistent für Mitarbeiter (Kern der FSR-Demo)

Chat in der eingebetteten Admin-Seite (iframe, siehe templates/Shopify/app.php, Karte "Shop-Assistent"). Kein neues Chat-UI — es ist derselbe interne TaskMonkey-Chat wie /manage/tasks/chat/<assistent> (bestehendes chat-internal.js/TasksController), nur per App-Bridge-JWT eingeloggt (ShopifyAppService::mintBackendBridgeLink($tenant, $next), gleicher Mechanismus wie "Im TaskMonkey-Backend öffnen", nur mit next=/manage/tasks/chat/shop_assistent_mitarbeiter?embed=1 — ?embed=1 ist der bestehende chromelose Layout-Schalter aus Manage\AppController).

Neuer Assistent config/tenants/_template/signup/shop_service/assistants/shop_assistent_mitarbeiter.php (rein deklarativ, keine Logik — Signup-Workspace-Regel). Tools dafür neu unter config/tenants/_shared/tools/shopify_staff/:

Tool Zweck Freigabe
shopifyStaffFindOrder Bestellung per Nummer nachschlagen liest nur
listShopifyLowStock Varianten mit niedrigem Bestand liest nur
listShopifyOpenOrdersToday Offene Bestellungen von heute liest nur
shopifyRefundOrder → shopifyApplyRefund (Teil-)Erstattung ApprovalGate/confirmChatAction, Mutation nur via only_via
shopifyAddOrderNote → shopifyApplyOrderNote Interne Bestellnotiz ApprovalGate/confirmChatAction, only_via
shopifyAdjustInventory → shopifyApplyInventoryAdjust Lagerbestand korrigieren ApprovalGate/confirmChatAction, only_via

Jedes Schreib-Tool zeigt beim ersten Aufruf nur eine Vorschau (needs_confirmation) und ruft intern confirmChatAction auf (derselbe Core-Mechanismus wie metaUpdateStatus/restoreDbBackup — nicht neu gebaut). Erst nach einem ausdrücklichen, NEUEN "Ja" des Nutzers (das LLM kann sich nicht selbst bestätigen) ruft das Tool den eigentlichen Mutations-Call auf — und zwar ein separates Tool, das per only_via NUR von genau diesem Vorschau-Tool aus erreichbar ist, nie direkt vom LLM, der Public API oder einem Scheduled Task.

Wer sitzt am Assistenten? (Code-Review 18.10.)

Alle Mitarbeiter eines Shops landen im selben TaskMonkey-Konto (dem bei der Installation angelegten Shop-User). Damit nicht jede Aushilfe erstatten oder Bestand ändern kann:

  1. Bridge nur für den Shop-User. ShopifyAppService::mintBackendBridgeLink minted ausschließlich für shopify_app_installs.provisioned_user_id (Migration AddProvisionedUserIdToShopifyAppInstalls), Fallback für alte Installationen: der shopify+<hash>@mail.taskmonkey.de-User des Workspace (wird dabei nachgetragen). Nie für einen anderen users_tenants-Eintrag, nie für PlatformAdmin::is() oder Rolle admin.
  2. Einmal-Links. Die Bridge-JWTs tragen jti (Cache, App\Auth\BridgeTokenStore) und tid (Workspace gepinnt) und sind mit einem abgeleiteten Schlüssel signiert (BridgeTokenStore::signingKey()), nicht mit dem Plattform-JWT- Secret — der allgemeine JWT-Authenticator (?token=/Bearer) kann sie nicht verifizieren, nur UsersController::appBridge löst sie ein, genau einmal. Zweiter Klick im selben Browser (schon eingeloggt): Weiterleitung ohne neuen Login. Die Flutter-WebView-Bridge (App-JWT ohne jti) läuft unverändert.
  3. Shopify-Mitarbeiter in der Session. ShopifyController::bootstrap nimmt sub aus dem Session-Token und holt per Online-Token-Exchange associated_user.account_owner (ShopifyOAuth::staffFromSessionToken, 10 Min. gecacht; Fehler → owner=false). Das wandert als Claim shopify_staff in den Bridge-Link und von dort in die Session (ShopifyStaff). Jeder andere Bridge-Login räumt den Eintrag weg.
  4. Schreib-Tools nur für den Inhaber. Tool-Flag 'shop_owner_only' => true (an allen sechs Schreib-Tools, Hülle + Apply). ToolRunner prüft es über ShopifyStaffContext::check: in einer Shopify-App-Session nur mit owner === true, sonst error_code: shop_owner_only. Jeder Aufruf — erlaubt oder abgelehnt — steht im Log (shopify-staff-write, mit Shopify-Mitarbeiter-ID). Lesen geht für alle. Fail-closed pro User: ist das Konto der Shop-User einer Installation (provisioned_user_id, alt: shopify+…-Adresse), wird ohne Mitarbeiter-Kontext immer abgelehnt — neue Session, anderer Login-Weg, gelöschter Schlüssel. Andere TaskMonkey-Konten ohne Shopify-Kontext sind nicht betroffen. Einmal-Token-Cache: eigener Pool app_bridge (config/app.php, 15 Min.).

Noch nicht gebaut: Freigabe einzelner Mitarbeiter durch den Inhaber (z. B. Liste erlaubter Shopify-User-IDs in den Workspace-Einstellungen). Bis dahin: nur der Inhaber schreibt.

Bekannte Einschränkung (Chrome funktioniert, Safari ggf. nicht): das iframe nutzt denselben Cookie-Session-Login wie der App-Bridge-Link für "im Backend öffnen". Browser mit strikter Drittanbieter-Cookie-Sperre (Safari ITP) können die Session innerhalb des verschachtelten iframes unter myshopify.com/admin.shopify.com blockieren. Für die FSR-Demo (Chrome) unkritisch; ein robuster Fix wäre, den Shop-Assistent-Chat auf Bearer-Session-Token statt Cookie umzustellen — siehe "Offene Punkte".

Einrichtung im Shopify-App-Modus (Vorschau, Branch feature/shopify-app-onboarding)

Nicht live — neue Optik, wartet auf Marcus' OK. Screenshots hell/dunkel: docs/previews/shopify-app-onboarding/*.png.

  • /manage/shop-setup: Hat der Workspace eine aktive Zeile in shopify_app_installs (und Shop-System shopify), rendert ShopSetupController::renderPage statt des 7-Schritte-Wizards ShopSetup/shopify_app.php: Kopf "Ihr Shop ist verbunden", drei Punkte (Shop verbunden · Wissen aus Shop-Seiten mit Anzahl + "Neu einlesen" · Chat im Shop mit "Im Theme-Editor einschalten", kein Code mehr), Karte "Mit eigener Bestellung testen" (bestehender testOrder), dezente nächste Schritte (Shop-Assistent, Postfach, Tarif). Alles andere unter "Erweitert": Angaben für den Chat (Rückgabe/Versand/Kontakt, Shop-System und Adresse nur als versteckte Felder, AVV nur als Hinweis wenn abgeschlossen), Code- Zeile für Themes ohne App-Embeds, Verbindung/Rechte. Der volle Wizard bleibt unter ?full=1. Gemeinsame Formulare: element/shop_setup/settings_form und test_forms (auch im Wizard benutzt).
  • Theme-Editor-Deep-Link (ShopifyAppService::themeEditorUrl), Format laut Shopify-Doku "Theme app extensions → Configuration": https://{shop}/admin/themes/current/editor?context=apps&activateAppId={client_id}/{handle}, handle = Dateiname des Blocks ohne .liquid → chat-embed (shopify-app/extensions/taskmonkey-chat-embed/blocks/chat-embed.liquid), NICHT der Ordnername der Extension.
  • Eingebettete Admin-Seite (templates/Shopify/app.php): Backend- Stylesheet + dieselben Zeilen; oben "Shop-Assistent öffnen", darunter der Status, "Neu einlesen" per POST /shopify/app/reimport (Session- Token, max. 1×/Minute), Testchat direkt offen in eigener Karte (chat.js mit data-preview im Container #tm-testchat-mount, eigene chat_id je Workspace; "Zum Testchat" springt per scrollIntoView, kein Hash-Link im Admin-iframe). Seit 17.11. kein manuelles Theme- Code-Snippet mehr auf der eingebetteten Seite (App Store 5.1.1, nur App-Embed); die Code-Zeile gibt es nur noch im TaskMonkey-Backend (/manage/shop-setup → Erweitert). Lokal ohne Shopify: /shopify/app?shop=…&preview=1[&tenant=<code>] (nur bei debug).

Workspace-Code per App-Data-Metafeld (18.10.)

ShopifyAppService::syncWorkspaceMetafield setzt bei provision() per Admin GraphQL (currentAppInstallation { id } → metafieldsSet) ein App-Data-Metafeld auf der AppInstallation: namespace taskmonkey, key workspace_code, type single_line_text_field, Wert = Workspace-Code. bootstrap() ruft bei bekannten Shops ensureWorkspaceMetafield (no-op, wenn im Shop-Einrichtungs-Zustand shopify_app_metafield.code schon stimmt; Token aus der Workspace-.env). Uninstall setzt den Merker zurück (Shopify löscht App-Data-Metafelder mit der Installation). chat-embed.liquid nimmt block.settings.workspace_code, falls gesetzt, sonst app.metafields.taskmonkey.workspace_code.value (Liquid-Objekt app, nur in Theme App Extensions). Das Feld im Block heißt jetzt "Workspace-Code (nur ändern, wenn nötig)". Braucht shopify app deploy (neue Extension-Version), sonst zeigt der Theme-Editor noch den alten Block.

Wissen aus Shopify (18.10.)

Für Workspaces mit Shop-System shopify und apis.shop_shopify (App oder eigene App) liest ShopSetupService::importShopPages nicht mehr die Storefront (passwortgeschützte Shops liefern nur die Passwortseite), sondern über das deklarative Tool shopShopifyContent (je Teil ein GraphQL-Call): part=pages (veröffentlichte Seiten, read_content, dazu Shop-Name/-Beschreibung) und part=policies (shop.shopPolicies, read_legal_policies: Rückgabe, Versand, AGB, Datenschutz, Impressum, Kontakt). ShopPageImporter::importDocs zerlegt mit derselben Abschnittslogik (extractSections) und speichert wie der Crawl (knowledge_entries, model shop_pages, öffentliche Wissensbasis "Shop-Seiten"). Nichts gepflegt → Hinweis "In Shopify sind noch keine Seiten oder Richtlinien gepflegt …" (Admin-Seite + Backend), alter Bestand wird geleert. Beide Teile nicht lesbar (Netz/Token) → Rückfall auf den Crawl. Der Crawl erkennt die Shopify-Passwortseite (/password, template-password, Formular action="/password") und meldet sie, statt sie einzulesen.

Modul 3: SEO-Texte (geplant)

Produktbeschreibung, Meta-Titel und Alt-Texte als Entwurf; nach Freigabe in den Shop schreiben (analog Modul 2: Vorschau + confirmChatAction). Keine Tools, kein Assistent; die frühere ausgegraute Kachel ("bald verfügbar") ist seit 17.11. entfernt (App Store 2.1.2: keine unfertigen Funktionen in der App). Nächster Schritt, nicht Teil dieses MVP.

Konfiguration

config/shopify_app.php (Configure-Key ShopifyApp), geladen in config/bootstrap.php:

'ShopifyApp' => [
    'api_key' => env('SHOPIFY_APP_API_KEY', 'ddb2687fb2edee9e8892091c1d1fa397'), // öffentlich, Default ok
    'api_secret' => env('SHOPIFY_APP_SECRET', ''),   // NIE committen
    'app_url' => env('SHOPIFY_APP_URL', 'https://app.taskmonkey.de'),
    'scopes' => 'read_orders,write_orders,write_draft_orders,read_products,write_products,read_content,read_customers,read_legal_policies,read_inventory,write_inventory',
    'admin_api_version' => '2026-10',
],

Shopify-Dashboard-Konfig (von Marcus angelegt/aktualisiert, 18.10. — Marcus hat im Dashboard bereits eine neue App-Version mit den erweiterten Scopes veröffentlicht; shopify.app.toml enthält exakt dieselben Scopes, damit ein künftiges shopify app deploy sie nicht zurücksetzt):

  • App URL: https://app.taskmonkey.de/shopify/app, embedded, kein Legacy-Install-Flow.
  • Redirect-URL (Fallback-Flow): https://app.taskmonkey.de/shopify/callback.
  • Scopes: read_orders,write_orders,write_draft_orders,read_products,write_products,read_content,read_customers,read_legal_policies,read_inventory,write_inventory (erweitert für Modul 2 — Schreib-Scopes werden nur über das ApprovalGate/confirmChatAction-gesicherte Tool-Paar genutzt, siehe Modul-2-Abschnitt).
  • Webhooks API-Version: 2026-10.
  • Client-ID: ddb2687fb2edee9e8892091c1d1fa397 (steht auch in shopify-app/shopify.app.toml).

Was Marcus tun muss

  1. Client Secret eintragen: SHOPIFY_APP_SECRET in die Prod-config/.env (gitignored, nie committen). Für lokale Tests: dieselbe Variable in der lokalen config/.env setzen, oder SHOPIFY_APP_API_KEY/SHOPIFY_APP_SECRET als Shell-Env vor bin/dev-server.sh.
  2. Tunnel für lokale Entwicklung: entweder shopify app dev (startet einen eigenen Tunnel + aktualisiert die App-URLs temporär im Dashboard) oder cloudflared tunnel --url http://localhost:8777 und die App-URL im Dashboard manuell auf die Tunnel-URL setzen, solange lokal getestet wird — vor der FSR-Demo wieder auf https://app.taskmonkey.de/shopify/… zurückstellen.
  3. Entwicklungsshop: taskmonkey-kundenservice.myshopify.com (bereits angelegt). Ein paar Testprodukte, 1–2 Testbestellungen anlegen (für die "Wo ist meine Bestellung?"-Demo — Bestellnummer + die beim Test-Checkout verwendete E-Mail-Adresse merken). Hinterlegt als dev_store_url in shopify-app/shopify.app.toml (Komfort-Default für shopify app dev).
  4. App installieren: im Partner-Dashboard "Test on development store" an taskmonkey-kundenservice.myshopify.com, oder direkt https://taskmonkey-kundenservice.myshopify.com/admin/oauth/install?client_id=ddb2687fb2edee9e8892091c1d1fa397 im Browser des Dev-Shop-Admins öffnen.
  5. Theme App Extension ausrollen (braucht Shopify-CLI + Partner-Login, macht Marcus):
    cd shopify-app
    shopify app deploy
    
    Danach im Theme-Editor des Dev-Shops: App-Embeds → "TaskMonkey Chat" einschalten und speichern. Den Workspace-Code setzt die App selbst (App-Data-Metafeld, siehe oben); das Feld im Block bleibt leer.
  6. Produktions-DB-Migration vor dem ersten echten Deploy: bin/cake migrations migrate (Migration CreateShopifyAppInstalls) — gehört zum nächsten geplanten Deploy, nicht vorher einspielen.
  7. Demo-Daten seeden (nach der Installation, einmalig):
    bin/cake shopify_demo_seed --shop taskmonkey-kundenservice.myshopify.com
    
    Legt 10–15 Gartenwerk-Produkte (einige mit niedrigem Bestand, für "Welche Artikel laufen bald aus?"), 6 Kunden (@example.com) und 6 Bestellungen mit verschiedenen Status (bezahlt, versendet mit Tracking, offen, teilweise erstattet) an. Läuft NUR gegen Entwicklungsshops (prüft shop.plan.partnerDevelopment per GraphQL, sonst Abbruch) und ist idempotent (Tag taskmonkey-demo — zweiter Lauf tut nichts). Die GraphQL-Mutationen (productCreate, draftOrderComplete, fulfillmentCreate, refundCreate, inventorySetQuantities) konnten in dieser Sandbox nicht gegen eine echte Shopify-API getestet werden — bitte einmal vor der Demo laufen lassen und bei Feldnamen-Abweichungen (Shopify ändert das GraphQL-Schema zwischen API-Versionen) kurz nachbessern.

AV-Vertrag bei der Installation (19.10.)

Code-Review-Fund: provision() hatte avv => true automatisch gesetzt. Jetzt:

  • Installation (ShopifyAppService::provision → ShopSetupService::applySettings(..., ['pending' => true])): AVV bleibt offen, shop_setup.state.avv = {status: pending, since, via: shopify_app_install} (markAvvPending). Ein schon abgeschlossener Vertrag (Neuinstallation) bleibt bestehen.
  • Admin-Seite (templates/Shopify/app.php): solange offen, ganz oben die Karte „Auftragsverarbeitungsvertrag (AVV) mit meco GmbH“ mit demselben Zustimmungstext wie die Einrichtungs-Seite (element/shop_setup/avv_label, Link Onboarding.shop.avv_url = SHOP_AVV_URL), Checkbox + „Vertrag abschließen“. Testchat wird erst danach geladen.
  • Zustimmung: POST /shopify/app/avv (Bearer Session-Token wie reimport, Body {"accept": true}) → ShopifyAppService::acceptAvv → ShopSetupService::acceptAvv. Gespeichert an derselben Stelle wie bei der Einrichtungs-Seite (shop_setup.state.avv): accepted_at, version (Onboarding.shop.avv_version), user_id (Shop-User des Workspace), ip_prefix, via: shopify_app, dazu shopify_staff_id (sub des Session-Tokens), shopify_owner (Online-Token-Exchange, ShopifyStaffContext) und shop. Zweite Zustimmung überschreibt nichts.
  • Bis zur Zustimmung: der anonyme Kunden-Chat des Workspace antwortet nur „Der Kundenservice-Chat dieses Shops ist noch nicht aktiviert …“ (ChatController::publicAvvBlock, Code not_activated, nichts geht ans LLM). Interne Chats (Shop-Assistent fürs Team) laufen. Workspaces ohne AVV-Eintrag (andere Branchen) sind nicht betroffen — gesperrt wird nur bei ausdrücklichem status: pending.
  • Backend /manage/shop-setup (Shopify-App-Modus): Kopf-Pille „AVV abgeschlossen am …“ bzw. „AVV offen“ + Hinweis mit „In Shopify zustimmen“; unter Erweitert → Verbindung Datum, Fassung, Inhaber/ Mitarbeiter. Zustimmen geht dort auch über das Formular „Angaben für den Chat“ (via: page).
  • Plattformweit (seit AVV 1.1, 19.10.): jede Shop-Zustimmung landet zusätzlich als Zustimmung des Workspace in tenant_settings avv (AvvService::recordFromShop); Version/Link heißen jetzt Onboarding.avv_version / Onboarding.avv_url (Onboarding.shop.avv_* bleibt Alias). Eine Zustimmung unter Verwaltung → AVV (/manage/avv) schreibt umgekehrt in shop_setup.state.avv und hebt damit auch die Public-Chat-Sperre auf. Bestands-Zustimmungen (1.0) gelten weiter, die Verwaltung bietet „Version 1.1 ansehen und bestätigen“ an.
  • Bestand: der Dev-Store-Workspace bleibt wie er ist (AVV war dort schon „abgeschlossen“), nur neue Installationen müssen zustimmen.
  • Vor dem ersten echten Shop: /avv/ ist noch als Entwurf markiert (noindex, TODOs) und SHOP_AVV_URL ist nicht gesetzt — dann zeigt die Karte den Text ohne Link. Marcus: Text final machen, SHOP_AVV_URL in die Prod-config/.env, bei inhaltlicher Änderung Onboarding.shop.avv_version hochziehen.

Custom distribution für einzelne Shops (Pilot-Shops vor dem App Store)

Ausgangslage: Die öffentliche App (ddb2687f…) ist nicht reviewt. Eine App mit Public distribution lässt sich in echten (Nicht-Dev-)Shops erst nach bestandenem App-Review installieren (Tabelle „Approval: Yes“ für Public, „No“ für Custom), und die Distribution-Wahl ist endgültig („you can't change the method after you select it“). Custom distribution auf der öffentlichen App würde sie also für den App Store sperren.

Weg: pro Pilot-Shop eine zweite App im Dev Dashboard mit Custom distribution (Install-Link für genau diesen Shop, kein Review, Protected Customer Data Level 1+2 „always available“). Gleicher Code, gleiche Endpunkte; die App wird gewählt über

  • aud des Session-Tokens (Admin-Seite, bootstrap/reimport/avv),
  • die Shop-Domain (?shop= der Admin-Seite → shopify-api-key für App Bridge, Webhooks-HMAC, OAuth-Fallback, Theme-Editor-Deep-Link, „Zurück zu Shopify“).

Code: src/Service/Shopify/ShopifyApps.php, Config ShopifyApp.apps.<name> in config/shopify_app.php (api_key, api_secret aus .env, shops), CLI-Konfig shopify-app/shopify.app.<name>.toml. Leere .env-Werte = App inaktiv.

Quellen (Stand 19.10.2026): Distribution, Select a distribution method, Protected customer data, App-Konfigurationsdateien, Changelog: keine neuen Custom Apps im Admin ab 01.01.2026.

Einschränkungen Custom distribution: keine Shopify-Billing-API (Abrechnung über TaskMonkey/Stripe), App gilt nur für diesen Shop (bzw. dessen Plus-Organisation). Die öffentliche App bleibt unberührt und kann parallel in den Review.

Klick-Anleitung (Pilot „Literally Love“, 7tuthk-4k.myshopify.com)

Vorbereitet: Config-Slot literally-love (SHOPIFY_APP_LITERALLY_LOVE_API_KEY, SHOPIFY_APP_LITERALLY_LOVE_SECRET, Shop 7tuthk-4k.myshopify.com) und shopify-app/shopify.app.literally-love.toml.

  1. Deploy dieses Branches (braucht der Code für die zweite App + die AVV-Karte), vorher SHOP_AVV_URL klären (siehe AVV-Abschnitt).
  2. Dev Dashboard (dev.shopify.com, meco-Organisation) → Apps → Create app → Start from Dev Dashboard, Name „TaskMonkey Kundenservice (Literally Love)“ → Create.
  3. In der neuen App: Versions → Create a version (bzw. die Konfiguration übernimmt Schritt 5 per CLI): App URL https://app.taskmonkey.de/shopify/app, Embed app in Shopify admin an, Scopes wie in der toml, Redirect-URL https://app.taskmonkey.de/shopify/callback, Webhooks-Version 2026-10. Nichts davon ist geheim.
  4. Settings der App: Client ID und Secret kopieren → Prod-config/.env:
    SHOPIFY_APP_LITERALLY_LOVE_API_KEY=<Client ID>
    SHOPIFY_APP_LITERALLY_LOVE_SECRET=<Secret>
    
    (Secret nie ins Repo/in Chats.) Die Client-ID außerdem in shopify-app/shopify.app.literally-love.toml bei client_id eintragen und committen (öffentlich).
  5. App-Konfig + Theme-Extension ausrollen (lokal, Shopify-CLI):
    cd shopify-app
    shopify app deploy --config literally-love
    
    Die CLI legt die Theme App Extension „TaskMonkey Chat“ für die neue App an (fragt sie nach Anlegen/Zuordnen: neu anlegen) und veröffentlicht eine Version mit Scopes, URLs und Webhooks aus der toml.
  6. Distribution (App-Home → Karte Distribution → Select distribution method) → Custom distribution wählen → bestätigen (endgültig, für DIESE zweite App gewollt).
  7. Shop-Domain 7tuthk-4k.myshopify.com eingeben (Multi-Store aus) → Generate link → Link kopieren.
  8. Link an Marco schicken. Er öffnet ihn eingeloggt als Inhaber, bestätigt die Rechte → die App öffnet sich im Shopify-Admin, richtet den Workspace ein und zeigt die AVV-Karte: Häkchen + „Vertrag abschließen“.
  9. Danach auf der Admin-Seite „Im Theme-Editor einschalten“ (App-Embed „TaskMonkey Chat“) → Speichern. Kontrolle: /manage/shop-setup des neuen Workspace zeigt „AVV abgeschlossen am …“.

Weitere Pilot-Shops: neuen Slot in ShopifyApp.apps + eigene toml, gleiche Schritte. Mit freigegebener öffentlicher App: Shop installiert die öffentliche App; der Slot kann dann bleiben (bestehende Installation) oder nach Deinstallation der Custom-App entfernt werden.

Offen/nicht verifiziert: Theme App Extensions in Custom-distribution- Apps sind laut Sekundärquellen erlaubt (kein offizieller Ausschluss gefunden) — beim ersten Deploy prüfen. Falls nicht: Widget-Zeile aus /manage/shop-setup → „Erweitert“ in theme.liquid.

Demo-Drehbuch (FSR-Termin)

Jeder Schritt mit URL und wörtlichen Testfragen zum Nachsprechen.

  1. Vorher einmalig: bin/cake shopify_demo_seed --shop taskmonkey-kundenservice.myshopify.com laufen lassen (siehe oben) — sonst hat der Shop-Assistent nichts zu zeigen.
  2. Installation — https://taskmonkey-kundenservice.myshopify.com/admin → Apps → "TaskMonkey" → Installieren. (Sprechen: "Ein Klick, kein Entwickler-Setup im Shop nötig.")
  3. Eingebettete Admin-Seite öffnet automatisch (/shopify/app?shop=…).
  4. Shop-Assistent (Modul 2, Kern der Demo) — im Chat oben auf der Admin-Seite eintippen:
    • "Welche Artikel laufen bald aus?" → Liste mit niedrigem Bestand (aus den Seed-Daten).
    • "Zeig mir offene Bestellungen von heute" → Liste offener Bestellungen.
    • "Erstatte Bestellung #1004 teilweise 10 €" (Nummer aus den Seed-Daten nehmen) → Assistent zeigt eine Vorschau, fragt ausdrücklich nach. (Sprechen: "Nichts passiert, bevor ich Ja sage.") Mit "Ja" bestätigen → Assistent führt die Erstattung aus und bestätigt.
    • Optional: "Füge der Bestellung die Notiz 'Kunde telefonisch informiert' hinzu" — gleiches Vorschau-Prinzip.
  5. Kundenservice-Chat (Modul 1) weiter unten auf der Admin-Seite: zeigt "Wissen angelegt: N Abschnitte" (Seiten und Richtlinien direkt aus Shopify eingelesen) und darunter den offenen Testchat.
    • "Wo ist meine Bestellung?" → Assistent fragt nach Bestellnummer + E-Mail.
    • Bestellnummer + die Test-Checkout-E-Mail eingeben → Assistent nennt Status/Bestelldatum (ohne Preise/Adressen).
  6. Theme App Extension — Theme-Editor des Dev-Shops → App-Embeds → "TaskMonkey Chat" (zeigen: nur einschalten, kein Code nötig) → Vorschau des Shop-Frontends → Chat-Bubble unten rechts, dieselbe Frage "Wo ist meine Bestellung?" im echten Shop-Frontend stellen.
  7. SEO-Texte mündlich als nächsten Schritt nennen (keine Kachel mehr auf der App-Seite).
  8. "Im TaskMonkey-Backend öffnen" auf der Admin-Seite klicken → zeigt das volle Backend (Inbox, Wissensbasis, Builder) für diesen Workspace.
  9. Deinstallation (optional, zeigt DSGVO-Sauberkeit) — App im Shopify-Admin entfernen → app/uninstalled-Webhook läuft, Zugangsdaten werden sofort entfernt (ShopSetupService::disconnectShopify).

Tests

DATABASE_TEST_URL=mysql://root:root@127.0.0.1/<eigene_db> \
  /usr/local/opt/php@8.3/bin/php -d memory_limit=-1 vendor/bin/phpunit --testsuite app \
  --filter "Shopify"

Abgedeckt: ShopifyOAuthTest (Domain/State/Callback-HMAC), ShopifySessionTokenTest (aud/dest/exp), ShopifyControllerTest (install/callback/bootstrap-Guard-Rails), ShopifyWebhooksControllerTest (HMAC ok/falsch, app/uninstalled, GDPR-Webhooks), ShopifyAppServiceTest (Bridge-Link für "Backend öffnen" + Shop-Assistent-iframe mit unterschiedlichem next), PlatformTablesTest (neue Tabelle registriert). Das Order-Lookup-Tool (E-Mail passt/passt nicht) ist bereits durch ShopifyToolsTest/ShopOrderToolsTest abgedeckt (unverändertes, wiederverwendetes Tool) — keine Dopplung. Beim Schreiben des ShopifyAppServiceTest fiel auf, dass users_tenants keine Zeitstempel-Spalte hat (orderBy(['created']) crashte) — gefixt, wäre sonst erst beim ersten echten Shopify-Install aufgefallen.

Die 8 neuen Shopify-Staff-Tools (config/tenants/_shared/tools/shopify_staff/) laufen durch bin/check-tool-db-access.sh (12-Regel-Check) ohne Verstöße.

Bewusst nicht automatisiert: die volle Install-Kette (Token Exchange → Shop-Stammdaten per GraphQL → Workspace-Anlage → echte Shop-Seiten-Crawl) und die Shopify-GraphQL-Mutationen (Refund/Order-Note/Inventory/Seed-Kommando) gegen einen echten Shop — das deckt das Demo-Drehbuch oben manuell ab. Die Bausteine selbst (createTenantForExistingUser, connectShopify, importShopPages, confirmChatAction/ApprovalGate) haben eigene, bestehende Tests.

Offene Punkte bis zum App Store

  • Deploy der Fixes vom 18.10.: Migration AddProvisionedUserIdToShopifyAppInstalls mitspielen. Bestehende Workspaces haben die Assistent-Vorlage als Kopie — dort in tenants_untracked/<code>/assistants/shop_assistent_mitarbeiter.php shopifyStaffLowStock/shopifyStaffOpenOrdersToday auf listShopifyLowStock/listShopifyOpenOrdersToday umstellen (sonst fehlen dem Assistenten die zwei Lese-Tools). Online-Token-Exchange muss für die App erlaubt sein (sonst owner=false → Schreib-Tools gesperrt, im Log shopify-staff-write … abgelehnt).

  • Workspace-Code automatisch im App-Embed: gebaut 18.10. (Branch feature/shopify-app-knowledge, siehe "Workspace-Code per App-Data- Metafeld"); live erst nach Deploy + shopify app deploy.

  • Mitarbeiter-Freigabe durch den Inhaber (siehe "Wer sitzt am Assistenten?"): bisher nur Inhaber schreibt.

  • AVV-Zustimmung: erledigt 19.10. (Karte auf der Admin-Seite, siehe "AV-Vertrag bei der Installation"). Offen bleibt der finale AVV-Text: SHOP_AVV_URL setzen, sobald /avv/ kein Entwurf mehr ist.

  • Shop-Assistent im eigenen Tab: erledigt 07.11. Der Link entsteht erst beim Klick (POST /shopify/app/link), das Fenster öffnet die Seite synchron im Klick (kein Pop-up-Blocker), der neue Tab ist First-Party und braucht keine Drittanbieter-Cookies (Inkognito). Vorher war der Link aus bootstrap nach 5 Minuten bzw. dem ersten Klick verbraucht.

  • Billing: erledigt 07.11. per Managed Pricing (siehe "Managed Pricing"). Scharf erst mit SHOPIFY_MANAGED_PRICING=1, nachdem die Pläne im Partner-Dashboard stehen.

  • Schreibzugriffe: seit Modul 2 vorhanden (Refund/Order-Note/ Inventory), aber nur über das ApprovalGate-gesicherte Tool-Paar — für den App Store bräuchte jeder Schreib-Scope trotzdem eine Review-Begründung (Shopify prüft Scopes gegen den tatsächlichen Funktionsumfang).

  • Shop-Assistent-iframe + Cookies: siehe Modul-2-Abschnitt — für Safari/ITP müsste der interne Chat auf Bearer-Session-Token statt Cookie-Login umgestellt werden (robusterer, aber neuer Auth-Pfad für /manage/tasks/chat/*).

  • App-Store-Review: eigenes Datenschutz-/Supportdokument, Screenshots, Listing-Text, Review-Scopes-Begründung — bisher nicht vorbereitet.

  • Mehrsprachigkeit: eingebettete Admin-Seite seit 07.11. Deutsch/ Englisch (siehe "Sprache der eingebetteten Seite"). Weiter nur Deutsch: das TaskMonkey-Backend im neuen Tab (Shop-Assistent-Rahmen, Einstellungen); der Assistent antwortet in der Sprache der Frage.

  • Modul 3 (SEO-Texte): kein Code, keine Kachel.

  • Inventory-Tool, mehrere Lagerorte: shopifyAdjustInventory nimmt MVP-vereinfacht den ersten Lagerort des Shops — bei mehreren Lagerorten müsste der Assistent vorher fragen, welcher gemeint ist.

  • "Widget aktiv"-Status: die Admin-Seite kann aktuell nicht serverseitig prüfen, ob der App-Embed-Block im Theme wirklich eingeschaltet ist (Shopify liefert das nicht trivial über die Admin-API) — zeigt nur den Code zum Einfügen. Für eine echte Statusanzeige bräuchte es die Asset-/Theme-API mit zusätzlichem Scope.

  • Re-Installation / mehrere Shops pro Betreiber: aktuell ein Workspace pro shop_domain, kein Zusammenführen mehrerer Shops in einen Workspace.

  • Löschlauf nach Vertragsende: für die Shopify-App erledigt 07.11. (shop/redact plant ein, bin/cake shopify_privacy löscht, siehe "Datenschutz-Webhooks"). Für Stripe-Kündigungen weiter von Hand.

Datenschutz-Webhooks (07.11.)

ShopifyPrivacy (über ShopifyAppService::handleCompliance), Löschen und Export in App\Service\Privacy\WorkspaceDataEraser, ganzer Workspace in WorkspacePurge. Immer nur der Workspace aus shopify_app_installs des Shops aus dem (HMAC-geprüften, mit dem Payload abgeglichenen) Header. Protokolle ohne E-Mail/Telefon, nur Zähler und customer_ref (Hash).

Topic Was passiert
customers/redact Person über E-Mail, Telefon (E.164, führende 0 = +49, Ländervorwahl zählt), gid://shopify/Customer/<id> und gid://shopify/Order/<id> (orders_to_redact) finden, exakt (LIKE nur Vorfilter; anna@ trifft nie hanna@, anna@x.de.vu, anna@mail.x.de). Ganzer Thread nur, wenn sie das Gegenüber ist: chat_senders (E-Mail/Telefon), from_address exakt, chat_id email:<adresse>:…/whatsapp:<nummer> — dann Nachrichten, Anhänge mit Datei, E-Mail-Köpfe und Bodies, Meta, Thread samt Inbox-Nebentabellen, Absender, Tool-Protokolle, ToolState. Sonst (Text, Signatur, To/CC, Tool-Ergebnis, Widget-Chat) nur die Nachrichten mit Treffer. Tool-Protokolle und Roh-Webhooks mit exaktem Treffer weg; Freigabe-Anfragen werden redigiert ([geloescht]), offene (pending, approved ohne Ausführung) nicht angefasst; Auskunfts-Exporte mit Treffer weg. Hart gelöscht.
customers/data_request Export (JSON) der Gespräche mit der Person bzw. der Nachrichten mit Treffer, per Mail (Anhang) an die Shop-E-Mail aus der Admin-API (shop.email) und echte Admins des Workspace, Kopie unter files/privacy/datenauskunft-*.json (geschützt über ProtectedTenantFiles, kein readFile; nach 30 Tagen gelöscht vom Cron). Ohne Empfänger nur die Kopie (Log recipients: 0).
shop/redact Ist der Shop inzwischen wieder installiert (Status installed, nach der letzten Deinstallation): nichts tun (Log shop-redact-ignored-active). Sonst Token weg (wie app/uninstalled), Löschung des ganzen Workspace eingeplant (tenant_settings.shopify_shop_redact, fällig nach ShopifyApp.privacy.shop_redact_grace_days, Standard 14, max. 28). bin/cake shopify_privacy (Cron 04:00, nur Minute 00) löscht dann erst den Ordner, danach in einer Transaktion die App-DB-Zeilen (Einplanung zuletzt), Benutzer nur dieses Workspace (auch Workspace-Admins, nie Plattform-Admins), Workspace und tenants_untracked/<code>; shopify_app_installs.status = redacted bleibt als Nachweis.

Nicht gelöscht wird, wenn: der Shop neu installiert ist (Planung entfällt schon bei der Installation), am Workspace ein Stripe-Abo oder Plan Individuell/Pilot/Review hängt, ein weiterer Shop daran hängt, der Ordner ein Git-Workspace ist oder ein finAPI-Zugang besteht. Dann Log shopify-shop-redact-kept bzw. -purge-failed, von Hand klären. Bleibt immer: llm_usage (Kosten ohne Inhalte), audit_events bei customers/redact (Nachweis der Verarbeitung).

Doppelte Zustellung: gleiche X-Shopify-Webhook-Id wird nur einmal verarbeitet (Cache shopify_webhooks, 72 h). Neue Plattform-Tabelle mit tenant/tenant_id: in WorkspacePurge::TENANT_COLUMNS oder EXCLUDED eintragen (WorkspacePurgeTest).

Prüfen: bin/cake shopify_privacy --dry-run. Tests: WorkspaceDataEraserTest, ShopifyPrivacyTest, ShopifyWebhooksControllerTest.

Managed Pricing (07.11.)

Entscheidung Marcus 07.11.: Abrechnung der öffentlichen App über Shopify Managed Pricing. Code: App\Service\Shopify\ShopifyBilling.

  • Liest currentAppInstallation.activeSubscriptions (Admin-GraphQL) bei Installation, bei jedem Öffnen der eingebetteten Seite und beim Webhook app_subscriptions/update (Payload wird nicht ausgewertet).

  • Plan-Name in Shopify → Plan in config/plans.php über ShopifyApp.billing.plans (Start → start, Team → team), Intervall ANNUAL → yearly, sonst monthly. Unbekannter Name oder kein aktives Abo → Plan shopify_pending (gesperrt, Besucher sehen den neutralen Hinweis). Die eingebettete Seite schickt dann sofort auf die Shopify-Planseite admin.shopify.com/store/<shop>/charges/<app_handle>/pricing_plans (Karte "Bitte wählen Sie einen Plan" als Rückfall).

  • Stripe ist für diese Workspaces aus: /manage/billing zeigt "Ihr Abo läuft über Shopify" mit Link auf die Planseite, Checkout/Wechsel/Portal leiten zurück, /manage/shop-setup zeigt "Pläne in Shopify" statt "Tarif ansehen".

  • Nie überschrieben: Workspaces mit Stripe-Abo oder Plan Individuell/Pilot/Review, Shops einer Custom-distribution-App (Literally Love).

  • Testabos (test: true, kostenlos): echter Plan nur auf eigenen Testshops (ShopifyApp.billing.test_shops). Plan shopify_review (Budget wie review) bekommen

    • Entwicklungs-Shops automatisch (18.11.): derselbe GraphQL-Call liest shop { plan { partnerDevelopment publicDisplayName } } (Admin API 2026-10, kein extra Scope). partnerDevelopment: true = Partner-/ Dev-Store, kann keine echten Bestellungen abwickeln — so ist der Dev-Store des App-Store-Prüfers ohne Zutun freigeschaltet. Nur ein echtes true zählt; publicDisplayName (z. B. Development) landet nur in Log und tenant_settings.shopify_subscription (displayName ist deprecated). Wird ein Dev-Store an einen Händler übergeben, fällt partnerDevelopment weg und das Testabo sperrt beim nächsten Sync.
    • zusätzlich Shops in ShopifyApp.billing.review_shops (pflegt Marcus von Hand, für Prüf-Shops, die kein Dev-Store sind).

    Alle anderen (echte Shops mit Testabo) → shopify_pending (Missbrauchsschutz, Log shopify-billing-test-subscription-ignored mit shop_plan). Echte Abos (test: false) → gemappter Plan, unabhängig vom Shop-Typ. shopify_review ist kein eigener Vertrag: ein echtes Abo überschreibt ihn, die Löschung nach shop/redact greift. Tests: tests/TestCase/Service/Shopify/ShopifyBillingTest.php.

Einschalten (Reihenfolge):

  1. Partner-Dashboard → Apps → TaskMonkey Kundenservice → Distribution → Manage listing → Pricing → Managed pricing wählen und die Pläne anlegen (Liste siehe docs/plans/app-reviews-2026-10-30.md, Abschnitt 10). Plan-Namen exakt Start und Team.
  2. App-Handle prüfen (URL der App im Partner-Dashboard bzw. admin.shopify.com/store/<shop>/apps/<handle>); weicht er von taskmonkey-kundenservice ab: SHOPIFY_APP_HANDLE in config/.env.
  3. shopify app deploy (Webhook app_subscriptions/update aus der toml).
  4. Deploy, dann SHOPIFY_MANAGED_PRICING=1 in die Server-.env. Ab da landen bestehende Shops ohne Abo beim nächsten Öffnen der App auf der Planseite.

Sprache der eingebetteten Seite (07.11.)

Shopify hängt locale an die App-URL (Sprache des Admins). de* → Deutsch, alles andere → Englisch, ohne Parameter Deutsch (ShopifyController::uiLang). Texte über __(), englisch in resources/locales/en/default.po; die Script-Texte kommen als T-Objekt aus denselben __(). Die Aufrufe der Seite schicken locale mit, damit Antworttexte (AVV, Fehler) passen; nach der Aktion wird die Locale zurückgesetzt. Der Testchat bekommt data-lang (chat.js: Platzhalter, Senden, Neustart). ShopifyAppFinishTest::testEveryEmbeddedTextIsTranslated schlägt fehl, wenn ein neuer Text keine Übersetzung hat.

Begrüßung, Start-Vorschläge, KI-Hinweis des Chats (16.11.): chat.js und chat-icon.js schicken data-lang als ?lang= an /chat/widget, /chat/history und /chat/stream; App\Service\Chat\ChatLanguage (dieselbe Regel wie uiLang) setzt public.greeting/public.suggestions und den KI-Hinweis im Kopf auf Englisch. Testchat der App-Seite = Admin- Sprache, App-Embed im Shop = request.locale.iso_code des Besuchers (greift erst nach shopify app deploy der Extension). Ohne lang: Shopify- Workspaces nach shop_status.locale (seit 17.11. die Admin-Sprache des Installierenden, ?locale beim Bootstrap — die Shop-Standardsprache per GraphQL shopLocales bräuchte den Scope read_locales; sonst Zeitzone DE/AT/CH → Deutsch), sonst Englisch; alle anderen Workspaces Deutsch. Englische Texte in der Vorlage unter public.i18n.en; Bestands-Workspaces ohne public.i18n bekommen sie, solange ihre deutschen Texte noch der Vorlage entsprechen (eigene Texte bleiben). Die Antworten folgen weiter der Sprache der Frage.

Shop-Assistent auf Englisch (16.11., App-Store-Dreh): „Shop-Assistent öffnen“ bzw. POST /shopify/app/link?locale=… gibt die Admin-Sprache an mintBackendBridgeLink(…, $lang) weiter; das Einmal-Token trägt dann lang: "en". /users/app-bridge merkt das in der Session (ChatLanguage::SESSION_KEY, nur en; jeder andere Login, Logout und Bridge-Login ohne lang löscht es). In dieser Sitzung läuft jeder Request mit Locale en (AppControllerInitTrait → ChatLanguage::applySessionLocale): __() aus resources/locales/en/default.po, die Chat-Oberfläche über window.TM_I18N (element/ui_i18n.php, dieselbe .po; T() in chat-internal.js, t() in TaskChatApp/SplitPaneLayout). Der Rahmen zeigt dann nur „Assistants“, die Liste nur Assistenten mit englischen Texten (assistants.<slug>.i18n.en, Vorlage shop_assistent_mitarbeiter; Bestand mit unveränderten Vorlagentexten bekommt sie automatisch), kein Builder/ Hauptchat. Status-Meldungen, Tool-Labels, Fehler und die Knöpfe der Schreib-Tools („Ja, erstatten“ → „Yes, refund“) laufen über ChatLanguage::ui(); das Ja-Gate (UserApproval::isClearYes) erkennt „Yes, …“ ebenso. Fürs Modell steht vor der letzten Nutzernachricht ein Sprach-Hinweis (ChatLanguage::withReplyLanguageHint): Antworten, Vorschauen und Ablehnungen in der Sprache der Frage, im Zweifel Englisch — gilt auch im Kunden-Chat bei lang=en bzw. englischem Shop (dort zusätzlich Locale en für Status/Fehler und widget.html-Texte wie „Kundenservice“/„Nachricht schreiben...“, ChatLanguage::localizeWidgetHtml, eigene Fassung per widget.i18n.en.html). ChatLanguageUiTest::testEveryUiTextHasAnEnglishTranslation schlägt fehl, wenn ein neuer T('…')-Text keine Übersetzung hat. Bewusst deutsch: übrige Backend-Seiten (Einstellungen /manage/shop-setup, AVV, Builder), Tool-Ergebnisse an das Modell, Prompts.

AVV-Bestaetigung und PDF (19.10.)

  • Jede neue Zustimmung (Registrierung, Verwaltung → AVV, Shop-Einrichtung, Shopify-App) schickt einmal die Mail „Ihr Auftragsverarbeitungsvertrag mit der meco GmbH“ mit dem Vertrag als PDF (AvvService::sendConfirmation, Mailer default, Vorlage blocks). Gesendet wird an die zustimmende Person; ist das der Platzhalter shopify+…@mail.taskmonkey.de, an die aktiven Admins/Manager des Workspace (nie an den Platzhalter, nie an Plattform-Admins). mail_sent_at/mail_to am Eintrag in tenant_settings avv verhindern doppelten Versand. Bestands- Zustimmungen 1.0 bekommen keine automatische Mail.
  • PDF (AvvPdf, dompdf): Deckblatt mit Workspace, Person, Zeitpunkt, Version, Weg, gekürzter IP (+ Shopify-Mitarbeiter), danach der Text der zugestimmten Fassung (webroot/avv/index.html bzw. Archiv webroot/avv/v1.0/index.html), Fusszeile auf jeder Seite.
  • Abruf: /manage/avv/pdf, /manage/avv/send-copy (Kopie an sich selbst); Shopify-App nach Zustimmung Karte „Vertrag herunterladen“ (POST /shopify/app/avv/pdf) und „Kopie per Mail senden“ (POST /shopify/app/avv/mail mit Adresse, 5 je Stunde und Shop).

Chat in der Theme-Vorschau (16.11.)

Der öffentliche Chat prüft die Herkunft (Origin bzw. Referer) gegen die freigegebenen Hosts des Workspace. Die Theme-Vorschau bzw. Vorschau-Links von Shopify laufen auf https://<token>-<ziffern>.shopifypreview.com und wurden deshalb abgelehnt (public-chat-origin-rejected … foreign_origin). Shopify-Prüfer testen oft genau dort.

Freigabe Marcus 16.11.2026: PublicChatOrigins::shopifyPreviewAllowed() lässt diese Herkunft zu, eng gefasst:

  • nur https, ohne Port und Userinfo, Host exakt ^[a-z0-9]{4,64}-\d{4,20}\.shopifypreview\.com$
  • nur Workspaces mit shop_status.system = shopify, gesetzter shopify_domain und aktiver App-Installation (shopify_app_installs.status = installed)
  • greift nur bei foreign_origin/foreign_referer (nicht bei artifact_origin, opaque_origin, missing_origin)

Grenze: Ob die Vorschau zum Shop dieses Workspace gehört, lässt sich nicht prüfen (die Zahl im Host ist keine Shop-ID). Tests: tests/TestCase/Service/Chat/ShopifyPreviewOriginTest.php.

App-Store-Selbstprüfung (17.11.)

Funde einer Selbstprüfung gegen die App-Store-Anforderungen, behoben auf fix/shopify-review-findings:

  • 2.2.4 nur GraphQL: ShopifyAppService::fetchShopInfo liest shop { name email contactEmail primaryDomain { host } } per Admin- GraphQL (vorher REST shop.json). Shop-Sprache: Admin-Sprache (?locale) statt primary_locale, kein neuer Scope. Der App-Pfad (Service, Controller, _shared/tools/shop/shopShopify*) ruft keine REST-Admin-Endpunkte mehr auf.
  • 5.1.1 kein manueller Theme-Code: Snippet-Block („Erweitert: Code für Themes ohne App-Embeds“) von templates/Shopify/app.php entfernt, widgetSnippet nicht mehr im Status der App-Seite.
  • 2.1.2 keine Platzhalter: Karte „SEO-Texte · bald verfügbar“ entfernt.
  • App-Embed: Einstellung app_base_url („TaskMonkey-Domain“) entfernt, Script fest von https://app.taskmonkey.de — greift erst nach shopify app deploy der Extension.
  • Konsole: chat-icon.js loggt nur mit window.TM_DEBUG = true (vorher Nachrichtentexte, Verlauf und Vorschläge in der Shop-Konsole).

Protected customer data: Verschlüsselung (17.11., Branch feat/shopify-pcd-app-encryption)

Für die PCD-Fragen „encrypt data at rest“ und „encrypt backups“. Die Mittwald-MySQL-Instanz kann keine Tablespace-Verschlüsselung (kein Keyring), deshalb verschlüsselt die Anwendung die Kundendaten der Shopify-App-Workspaces selbst (AES-256-GCM, Schlüssel DATA_ENCRYPTION_KEY nur in shared/config/.env, nicht in der DB). Technik, Schalter und vollständige Liste: docs/handbook/internal/data-loss-prevention.md, Abschnitt „Verschlüsselung von Kundendaten in der Anwendung“.

An für: jeden Workspace mit Zeile in shopify_app_installs (automatisch, auch nach Deinstallation bis shop/redact). Andere Workspaces per Workspace-Config 'data_encryption' => true oder Platform.data_encryption.workspaces.

Verschlüsselt (Shopify-App-Workspaces): Chat-Inhalte im Shop-Widget und im Shop-Assistenten inkl. Tool-Ergebnissen (Bestellstatus, Positionen, Sendungsverfolgung) — chat_messages.content; Tool-Argumente, -Logs und Fehlertexte — task_executions; Mails (Betreff, Text, HTML, ausgelagerte Bodies); KI-Zusammenfassungen; Stream-Events; Datenauskünfte (customers/data_request-Kopie); Workspace-Logs. Der Inbox-Suchindex enthält für diese Workspaces keinen Klartext.

Nicht verschlüsselt: Kennungen, die für Zuordnung/Löschung per SQL verglichen werden (Absender-Adresse von Mails, chat_senders), Metadaten (Status, Kategorie, Zeiten, Token-Zahlen in llm_usage), Shop-Domain, und die globalen Server-Logs (shared/logs: Log::error/warning, error_log() — Fehlermeldungen, durch SecretRedactor/PiiMask gefiltert, Inhalte nicht systematisch entfernt; für die Shopify-Workspaces heute nur technische Zeilen). Für die drei Shopify-App-Workspaces auf prod (17.11.) existieren keine Zeilen in chat_senders/chat_message_emails; Name, Anschrift und Telefon der Bestellung fragen die Shop-Tools ohnehin nicht ab.

Bestand auf prod (17.11., nur gezählt): chat_messages 182 Zeilen (literally-love 42, taskmonkey-kundenservice 140, appstoretest9 0), task_executions ~9.600 (fast alle mit Argumenten, 609 mit Log, 703 mit Fehlertext — überwiegend Ping-/Health-Läufe), chat_thread_search 13 Dokumente mit Text, chat_threads 13 (keine Zusammenfassungen), Workspace-Logs: debug.log mit „SENDING TO GPT“ und „tool result:“-Zeilen (1,2 MB), tools.log (~580 KB). Keine Mails, keine Sender, keine Freigabe-Anfragen.

Kosten (bin/cake data_encrypt --bench; lokal, M-Serie): 2-KB-Wert 5 µs verschlüsseln / 5 µs entschlüsseln, 20 KB ~15 µs, 200 KB ~110–130 µs; prod-CPU reines AES-GCM 1 KB ~6 µs hin und zurück. ORM-Roundtrip lokal (300 Nachrichten): Schreiben 2–7 ms je Nachricht mit und ohne Verschlüsselung (DB dominiert, Unterschied im Rauschen), Lesen +4 µs je 2-KB-Nachricht. Nicht verschlüsselte Workspaces zahlen nur eine Präfix-Prüfung je Feld (<0,1 µs). Platz: +33–44 % je Wert (Base64). Hochrechnung Bloomify (688 Nachrichten, 16.300 Tool-Läufe pro Tag; ~1,1 GB Inhalte): CPU vernachlässigbar, +~400 MB Platz — der echte Preis sind die Grenzen der Suche (PHP-Suche nur über die jüngsten 3.000 Nachrichten, keine LIKE-Filter in getChatMessages), siehe data-loss-prevention.md.

Antworten für den PCD-Fragebogen (erst nach Deploy + Schlüssel + data_encrypt --apply ehrlich mit Ja):

  • Do you encrypt data at rest? — Yes. Protected customer data that the app stores (chat transcripts, order lookups returned by tools, tool inputs/logs, e-mails, conversation summaries, data-request exports and per-workspace application logs) is encrypted at the application layer with AES-256-GCM before it is written to the database or disk; each value is bound to its shop workspace and field. The key is kept outside the database in the server environment and can be rotated. Identifiers needed to match and delete records (e.g. a sender's e-mail address), non-content metadata (timestamps, status, token counts) and the server's technical error logs (filtered for credentials, IP addresses and URL parameters) are not encrypted.
  • Do you encrypt backups? — Yes, for protected customer data: because the fields are encrypted before they reach the database, every database backup contains them only as ciphertext; the encryption key is not part of the database. Backups are kept by our hosting provider (Mittwald, Germany, ISO 27001) for 30 days in a separate fire compartment. (Intern, nicht für Shopify: das Mittwald-Projekt-Backup enthält auch den Webspace mit config/.env; wer das komplette Projekt-Backup hat, hat auch den Schlüssel.)

Prod-Reihenfolge: docs/Hosting.md, Abschnitt „Verschlüsselte Kundendaten (DATA_ENCRYPTION_KEY)“.

Zuletzt aktualisiert: 2026-11-17