Webshop: Livegang-Anleitung (Stripe Connect, Webhook, Schalter, Schema, Pilot)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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.