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):
- Kundenservice-Chat (Widget im Shop-Frontend, Wissen, Bestellstatus) — MVP, siehe unten.
- Shop-Assistent für Mitarbeiter (Chat in der eingebetteten Admin-Seite, ähnlich Shopify Sidekick) — MVP, Kern der FSR-Demo, siehe Modul-2-Abschnitt.
- 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_installspflegen, Uninstall/GDPR-Webhooks).src/Controller/ShopifyController.php+ShopifyWebhooksController.php— eigene Controller statt/api/v1/hooks(Begründung analogConnectInstagramController: Plattform-Endpunkte ohne Workspace, Format passt nicht ins generische Pro-Tenant-Hook-Modell — siehe Klassen- Doc-Kommentare).- Migration
CreateShopifyAppInstalls— Plattform-Tabelleshopify_app_installs(nurshop_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:
- Bridge nur für den Shop-User.
ShopifyAppService::mintBackendBridgeLinkminted ausschließlich fürshopify_app_installs.provisioned_user_id(MigrationAddProvisionedUserIdToShopifyAppInstalls), Fallback für alte Installationen: dershopify+<hash>@mail.taskmonkey.de-User des Workspace (wird dabei nachgetragen). Nie für einen anderenusers_tenants-Eintrag, nie fürPlatformAdmin::is()oder Rolleadmin. - Einmal-Links. Die Bridge-JWTs tragen
jti(Cache,App\Auth\BridgeTokenStore) undtid(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, nurUsersController::appBridgelöst sie ein, genau einmal. Zweiter Klick im selben Browser (schon eingeloggt): Weiterleitung ohne neuen Login. Die Flutter-WebView-Bridge (App-JWT ohnejti) läuft unverändert. - Shopify-Mitarbeiter in der Session.
ShopifyController::bootstrapnimmtsubaus dem Session-Token und holt per Online-Token-Exchangeassociated_user.account_owner(ShopifyOAuth::staffFromSessionToken, 10 Min. gecacht; Fehler →owner=false). Das wandert als Claimshopify_staffin den Bridge-Link und von dort in die Session (ShopifyStaff). Jeder andere Bridge-Login räumt den Eintrag weg. - Schreib-Tools nur für den Inhaber. Tool-Flag
'shop_owner_only' => true(an allen sechs Schreib-Tools, Hülle + Apply).ToolRunnerprüft es überShopifyStaffContext::check: in einer Shopify-App-Session nur mitowner === true, sonsterror_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 Poolapp_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 inshopify_app_installs(und Shop-Systemshopify), rendertShopSetupController::renderPagestatt des 7-Schritte-WizardsShopSetup/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" (bestehendertestOrder), 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_formundtest_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" perPOST /shopify/app/reimport(Session- Token, max. 1×/Minute), Testchat direkt offen in eigener Karte (chat.jsmitdata-previewim Container#tm-testchat-mount, eigenechat_idje Workspace; "Zum Testchat" springt perscrollIntoView, 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 beidebug).
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 inshopify-app/shopify.app.toml).
Was Marcus tun muss
- Client Secret eintragen:
SHOPIFY_APP_SECRETin die Prod-config/.env(gitignored, nie committen). Für lokale Tests: dieselbe Variable in der lokalenconfig/.envsetzen, oderSHOPIFY_APP_API_KEY/SHOPIFY_APP_SECRETals Shell-Env vorbin/dev-server.sh. - Tunnel für lokale Entwicklung: entweder
shopify app dev(startet einen eigenen Tunnel + aktualisiert die App-URLs temporär im Dashboard) odercloudflared tunnel --url http://localhost:8777und die App-URL im Dashboard manuell auf die Tunnel-URL setzen, solange lokal getestet wird — vor der FSR-Demo wieder aufhttps://app.taskmonkey.de/shopify/…zurückstellen. - 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 alsdev_store_urlinshopify-app/shopify.app.toml(Komfort-Default fürshopify app dev). - App installieren: im Partner-Dashboard "Test on development store"
an
taskmonkey-kundenservice.myshopify.com, oder direkthttps://taskmonkey-kundenservice.myshopify.com/admin/oauth/install?client_id=ddb2687fb2edee9e8892091c1d1fa397im Browser des Dev-Shop-Admins öffnen. - Theme App Extension ausrollen (braucht Shopify-CLI + Partner-Login,
macht Marcus):
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.cd shopify-app shopify app deploy - Produktions-DB-Migration vor dem ersten echten Deploy:
bin/cake migrations migrate(MigrationCreateShopifyAppInstalls) — gehört zum nächsten geplanten Deploy, nicht vorher einspielen. - Demo-Daten seeden (nach der Installation, einmalig):
Legt 10–15 Gartenwerk-Produkte (einige mit niedrigem Bestand, für "Welche Artikel laufen bald aus?"), 6 Kunden (bin/cake shopify_demo_seed --shop taskmonkey-kundenservice.myshopify.com@example.com) und 6 Bestellungen mit verschiedenen Status (bezahlt, versendet mit Tracking, offen, teilweise erstattet) an. Läuft NUR gegen Entwicklungsshops (prüftshop.plan.partnerDevelopmentper GraphQL, sonst Abbruch) und ist idempotent (Tagtaskmonkey-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, LinkOnboarding.shop.avv_url=SHOP_AVV_URL), Checkbox + „Vertrag abschließen“. Testchat wird erst danach geladen. - Zustimmung:
POST /shopify/app/avv(Bearer Session-Token wiereimport, 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, dazushopify_staff_id(sub des Session-Tokens),shopify_owner(Online-Token-Exchange,ShopifyStaffContext) undshop. 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, Codenot_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ücklichemstatus: 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_settingsavv(AvvService::recordFromShop); Version/Link heißen jetztOnboarding.avv_version/Onboarding.avv_url(Onboarding.shop.avv_*bleibt Alias). Eine Zustimmung unter Verwaltung → AVV (/manage/avv) schreibt umgekehrt inshop_setup.state.avvund 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) undSHOP_AVV_URList nicht gesetzt — dann zeigt die Karte den Text ohne Link. Marcus: Text final machen,SHOP_AVV_URLin die Prod-config/.env, bei inhaltlicher ÄnderungOnboarding.shop.avv_versionhochziehen.
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
auddes Session-Tokens (Admin-Seite, bootstrap/reimport/avv),- die Shop-Domain (
?shop=der Admin-Seite →shopify-api-keyfü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.
- Deploy dieses Branches (braucht der Code für die zweite App + die
AVV-Karte), vorher
SHOP_AVV_URLklären (siehe AVV-Abschnitt). - Dev Dashboard (dev.shopify.com, meco-Organisation) → Apps → Create app → Start from Dev Dashboard, Name „TaskMonkey Kundenservice (Literally Love)“ → Create.
- 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-URLhttps://app.taskmonkey.de/shopify/callback, Webhooks-Version2026-10. Nichts davon ist geheim. - Settings der App: Client ID und Secret kopieren →
Prod-
config/.env:
(Secret nie ins Repo/in Chats.) Die Client-ID außerdem inSHOPIFY_APP_LITERALLY_LOVE_API_KEY=<Client ID> SHOPIFY_APP_LITERALLY_LOVE_SECRET=<Secret>shopify-app/shopify.app.literally-love.tomlbeiclient_ideintragen und committen (öffentlich). - App-Konfig + Theme-Extension ausrollen (lokal, Shopify-CLI):
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.cd shopify-app shopify app deploy --config literally-love - Distribution (App-Home → Karte Distribution → Select distribution method) → Custom distribution wählen → bestätigen (endgültig, für DIESE zweite App gewollt).
- Shop-Domain
7tuthk-4k.myshopify.comeingeben (Multi-Store aus) → Generate link → Link kopieren. - 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“.
- Danach auf der Admin-Seite „Im Theme-Editor einschalten“ (App-Embed
„TaskMonkey Chat“) → Speichern. Kontrolle:
/manage/shop-setupdes 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.
- Vorher einmalig:
bin/cake shopify_demo_seed --shop taskmonkey-kundenservice.myshopify.comlaufen lassen (siehe oben) — sonst hat der Shop-Assistent nichts zu zeigen. - Installation —
https://taskmonkey-kundenservice.myshopify.com/admin→ Apps → "TaskMonkey" → Installieren. (Sprechen: "Ein Klick, kein Entwickler-Setup im Shop nötig.") - Eingebettete Admin-Seite öffnet automatisch (
/shopify/app?shop=…). - 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.
- 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).
- 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.
- SEO-Texte mündlich als nächsten Schritt nennen (keine Kachel mehr auf der App-Seite).
- "Im TaskMonkey-Backend öffnen" auf der Admin-Seite klicken → zeigt das volle Backend (Inbox, Wissensbasis, Builder) für diesen Workspace.
- 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
AddProvisionedUserIdToShopifyAppInstallsmitspielen. Bestehende Workspaces haben die Assistent-Vorlage als Kopie — dort intenants_untracked/<code>/assistants/shop_assistent_mitarbeiter.phpshopifyStaffLowStock/shopifyStaffOpenOrdersTodayauflistShopifyLowStock/listShopifyOpenOrdersTodayumstellen (sonst fehlen dem Assistenten die zwei Lese-Tools). Online-Token-Exchange muss für die App erlaubt sein (sonstowner=false→ Schreib-Tools gesperrt, im Logshopify-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_URLsetzen, 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 ausbootstrapnach 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:
shopifyAdjustInventorynimmt 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/redactplant ein,bin/cake shopify_privacylö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 Webhookapp_subscriptions/update(Payload wird nicht ausgewertet). -
Plan-Name in Shopify → Plan in
config/plans.phpüberShopifyApp.billing.plans(Start→start,Team→team), IntervallANNUAL→yearly, sonstmonthly. Unbekannter Name oder kein aktives Abo → Planshopify_pending(gesperrt, Besucher sehen den neutralen Hinweis). Die eingebettete Seite schickt dann sofort auf die Shopify-Planseiteadmin.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/billingzeigt "Ihr Abo läuft über Shopify" mit Link auf die Planseite, Checkout/Wechsel/Portal leiten zurück,/manage/shop-setupzeigt "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). Planshopify_review(Budget wiereview) 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 echtestruezählt;publicDisplayName(z. B.Development) landet nur in Log undtenant_settings.shopify_subscription(displayNameist deprecated). Wird ein Dev-Store an einen Händler übergeben, fälltpartnerDevelopmentweg 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, Logshopify-billing-test-subscription-ignoredmitshop_plan). Echte Abos (test: false) → gemappter Plan, unabhängig vom Shop-Typ.shopify_reviewist kein eigener Vertrag: ein echtes Abo überschreibt ihn, die Löschung nachshop/redactgreift. Tests:tests/TestCase/Service/Shopify/ShopifyBillingTest.php. - Entwicklungs-Shops automatisch (18.11.): derselbe GraphQL-Call liest
Einschalten (Reihenfolge):
- 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 exaktStartundTeam. - App-Handle prüfen (URL der App im Partner-Dashboard bzw.
admin.shopify.com/store/<shop>/apps/<handle>); weicht er vontaskmonkey-kundenserviceab:SHOPIFY_APP_HANDLEinconfig/.env. shopify app deploy(Webhookapp_subscriptions/updateaus der toml).- Deploy, dann
SHOPIFY_MANAGED_PRICING=1in 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, Mailerdefault, Vorlageblocks). Gesendet wird an die zustimmende Person; ist das der Platzhaltershopify+…@mail.taskmonkey.de, an die aktiven Admins/Manager des Workspace (nie an den Platzhalter, nie an Plattform-Admins).mail_sent_at/mail_toam Eintrag intenant_settingsavvverhindern 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.htmlbzw. Archivwebroot/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/mailmit 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, gesetztershopify_domainund aktiver App-Installation (shopify_app_installs.status = installed) - greift nur bei
foreign_origin/foreign_referer(nicht beiartifact_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::fetchShopInfoliestshop { name email contactEmail primaryDomain { host } }per Admin- GraphQL (vorher RESTshop.json). Shop-Sprache: Admin-Sprache (?locale) stattprimary_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.phpentfernt,widgetSnippetnicht 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 vonhttps://app.taskmonkey.de— greift erst nachshopify app deployder Extension. - Konsole:
chat-icon.jsloggt nur mitwindow.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)“.