Webklar-Kundenbereich/docs/funktionen/shop-livegang.md

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)

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.