From 52543a99b13c93e27e55997a1e093c9ddb556363 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 5 Oct 2026 10:03:55 +0000 Subject: [PATCH] Webshop: Livegang-Anleitung (Stripe Connect, Webhook, Schalter, Schema, Pilot) Co-Authored-By: Claude Opus 5.5 --- docs/funktionen/shop-livegang.md | 91 ++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/funktionen/shop-livegang.md diff --git a/docs/funktionen/shop-livegang.md b/docs/funktionen/shop-livegang.md new file mode 100644 index 0000000..0304f83 --- /dev/null +++ b/docs/funktionen/shop-livegang.md @@ -0,0 +1,91 @@ +# Webshop – Livegang + +Reihenfolge für den Inhaber. Jeder Schritt braucht seine Freigabe; nichts davon hat Claude gegen Produktion oder das +Live-Stripe-Konto ausgeführt. Code: Portal `feature/webshop` (Worktree `dev-webshop`), WOMS `feature/webshop` +(Worktree `ticket.webklar.com/dev-webshop`). Beide Zweige bauen auf `feature/terminplaner-tp2` auf. + +## 0. Voraussetzung + +- **TP2 (Terminplaner-Verkauf) ist live.** Der Webshop nutzt das Funktionen-Register aus TP2. Erst TP2 nach `main` + (Portal) bzw. `test` (WOMS), dann diesen Zweig darauf mergen (`git merge origin/main` im Worktree, Tests laufen lassen). +- Der Zweig `feature/oeffnungszeiten` baut ebenfalls auf TP2 auf. Wer zuerst live geht, ist egal; der zweite merged den + ersten nach (Konflikte erwartbar in `server/config.js` features, `public/app.js`, `public/funktionen.js`, + `test/mailTemplates.test.js` (Vorlagen-IDs), `server/index.js`). + +## 1. Stripe-Dashboard (WEBklar-Konto, live) + +1. **Connect aktivieren**: Einstellungen → Connect → Plattformprofil ausfüllen: „Plattform/Software, deren Nutzer an + eigene Kunden verkaufen“, Geldfluss **Direct Charges**, **keine** Plattformgebühr, Konten mit eigenem vollen + Stripe-Dashboard (Standard-Konten). Danach unter Connect → Branding Name „WEBklar“, Icon und Farbe für das Onboarding. +2. **Connect-Webhook** anlegen: Entwickler → Webhooks → Endpunkt hinzufügen, **„Ereignisse in verbundenen Konten“**, + URL `https://project.webklar.com/api/shop/stripe-webhook`, Ereignisse: + `account.updated`, `checkout.session.completed`, `checkout.session.async_payment_succeeded`, + `checkout.session.async_payment_failed`, `checkout.session.expired`, `charge.refunded`. + Das Signatur-Geheimnis (`whsec_…`) kommt in Schritt 2 in die `.env`. +3. Nichts weiter: Händler-Konten legt das Portal selbst an, wenn ein Händler „Stripe-Konto einrichten“ klickt. + +## 2. Server-Konfiguration + +In `/home/webklar/apps/.env`: +``` +SHOP_ENABLED=pilot +SHOP_PILOT_EMAILS=kenso.gri@gmail.com +STRIPE_CONNECT_WEBHOOK_SECRET=whsec_… +``` +In `/home/webklar/apps/docker-compose.yml` beim Dienst `kundenbereich-server` die drei Variablen durchreichen +(`SHOP_ENABLED=${SHOP_ENABLED:-off}`, `SHOP_PILOT_EMAILS=${SHOP_PILOT_EMAILS:-}`, +`STRIPE_CONNECT_WEBHOOK_SECRET=${STRIPE_CONNECT_WEBHOOK_SECRET:-}`) und danach +`docker compose -f /home/webklar/apps/docker-compose.yml up -d --no-deps kundenbereich-server` +(ein `docker restart` liest die `.env` nicht neu). Artikelbilder liegen unter `build/upload-data/shop/` (gitignored, +überleben Deploys wie die News-Fotos). + +## 3. Datenbank und Stripe-Preis (vor dem Deploy) + +```bash +cd /home/webklar/apps/kundenbereich.webklar.com/build +docker exec -w /app webklar-kundenbereich-server node scripts/shop-setup.mjs --check +docker exec -w /app webklar-kundenbereich-server node scripts/shop-setup.mjs +docker exec -w /app webklar-kundenbereich-server node scripts/stripe-products.mjs --pruefen +docker exec -w /app webklar-kundenbereich-server node scripts/stripe-products.mjs --anlegen # legt shopSetup 299 € an +``` +`shop-setup.mjs` legt fünf Collections an (`shopConfig`, `shopProducts`, `shopOrders`, `shopWiderrufe`, +`shopRechtstexteArchiv`). Die Käufer-Mails laufen über `termineOutbox`; die Collection kommt aus dem TP2-Livegang +(`scripts/termine-setup.mjs`). Die Skripte müssen aus dem neuen Code laufen (nach Schritt 4 oder vorher aus dem Worktree +mit derselben Umgebung). + +## 4. Deploy + +- Portal: `feature/webshop` → `main` pushen (Webhook deployt). +- WOMS: `feature/webshop` → `test` pushen; danach im WOMS „Rechtliches“: `scripts/setup-legal.mjs` laufen lassen (neue + Karten „Leistungsbeschreibung Webshop“, „AVV Webshop“) und die Fassungen 2026-10-05 hochladen + (`public/rechtliches/leistungsbeschreibung-webshop-2026-10-05.pdf`, `avv-webshop-2026-10-05.pdf`). +- Prüfen: `https://project.webklar.com/rechtliches/leistungsbeschreibung-webshop.html` und + `…/avv-webshop.html` antworten 200; `https://project.webklar.com/embed/shop.js` antwortet 200. + +## 5. Pilot mit dem Testkonto + +1. Im Portal als Testkunde: Funktionen → Webshop → Anfrage stellen (Projekt `test-website`). +2. WOMS → Kunde → Funktionen → Webshop → „Anfrage annehmen“ (Mail K24 kommt an). +3. Einrichtung: entweder bestellen (299 €, danach in Stripe erstatten) oder im WOMS „Aktivieren (ohne Zahlung)“ + (Pilot-Adressen brauchen keine Textform). +4. Einbau nach `docs/funktionen/shop-einbau.md` auf der Test-Website, Ticket schließen → Freischaltung, Mail K16. +5. Portal → Webshop → Übersicht → „Stripe-Konto einrichten“ (echtes Onboarding mit den Daten von WEBklar oder einem + Testbetrieb; Stripe prüft Identität und Bankkonto). +6. Einstellungen ausfüllen (Steuerart wählen!), einen Artikel für 1,00 € anlegen, Rechtstexte: Muster einsetzen, + Platzhalter ersetzen, Impressum-/Datenschutz-URL, bestätigen, „Shop öffnen“. +7. Testkauf auf der Website mit echter Karte → Mails G09 (Käufer) und K25 (Händler) prüfen → im Portal „Versendet“ + (G10) → „Erstatten“ (G13) → im Stripe-Dashboard des Händlers sichtbar. +8. Widerruf über den Fußzeilen-Link testen (G12 mit Datum und Uhrzeit, K26 an den Händler). + +## 6. Freigabe für alle + +- Kanzlei-Paket `docs/rechtliches/webshop-kanzlei-paket.md` an die Kanzlei, Befund einarbeiten (neue Fassung, falls + sich Texte ändern; ausgelieferte Fassungen werden nie überschrieben). +- Checkliste in Abschnitt 7 des Kanzlei-Pakets abhaken. +- `SHOP_ENABLED=on`, Compose neu anwenden (wie Schritt 2). + +## Zurück + +`SHOP_ENABLED=off` blendet die Kachel aus und stoppt neue Bestellungen. Bestehende Shops (Zustand aktiv oder +abgeschaltet) behalten ihre Widerrufsfunktion, ihre Fristen und die Löschjobs laufen weiter. Einzelne Shops schaltet das +Team im WOMS ab (Funktionen → Webshop → „Abschalten“), die Daten werden 90 Tage danach gelöscht.