hd-commerce/HANDOVER.md

HANDOVER — hd-commerce

Betriebs- und Übergabe-Runbook für hd-commerce. Zielgruppe: wer das Produkt deployt, einen echten Kundenshop daraus ausrollt und betreibt. Ergänzt README.md (Features) und CLAUDE.md (Arbeitsregeln am Code).

Stand: v2.4 · Repo till/hd-commerce (Gitea, GitHub-Mirror siehe MIRROR.md).

---

1. Was übergeben wird

Ein wiederverwechselbares E-Commerce-Backend-Produkt (eine Codebasis, viele Shops). Enthalten: Storefront + Premium-Admin, Katalog mit Varianten-Matrix, Warenkorb/Checkout, Zahlung (Mollie/Stripe/Demo), Rabatt-Engine, Versandzonen + MwSt/Grundpreis (DACH), Inhalte/Block-Builder, Medienbibliothek + WebP, Kundenkonten, Bewertungen, Merkliste, Volltextsuche, Abandoned-Cart, first-party Analytics, Bestellmails (Listmonk/SMTP/Log), KI-/MCP-API, Litestream-Backups (optional).

Demo-Instanz „Brittas Nähkiste" (Beispiel, kein echter Shop):

• App (Coolify): lbv524oul6b6mxvo95pgxgso · Server localhost (heidrich-infra-01)
• URL: https://lbv524oul6b6mxvo95pgxgso.46.224.49.66.sslip.io
• Admin-Pfad: /login (per ADMIN_PATH=login) · DB: /data/hdc2.db · RAM-Cap 640 MB
• Let's-Encrypt-Zertifikat, http→https erzwungen, PUBLIC_BASE_URL=https://… gesetzt
• Zugangsdaten: nicht hier — im 1Password/Chat. Niemals Credentials ins Repo/in Doku.

2. „Selbst gebaut" — bewusste Entscheidung

Der Eigenbau ist gerechtfertigt, weil hd-commerce ein über die Care-Abo-Basis mehrfach ausrollbares HD-Produkt ist: Datenhoheit, Tempo, Marge (keine Shopify-Gebühren), DSGVO-nativ, KI-/MCP-automatisiert. Der Preis ist dauerhafte Eigen-Wartung. Faustregeln (belegt im Portal-Research „SQLite-Eigenbau-Commerce — realistisch oder Overkill?"):

• SQLite + Litestream ist für DACH-KMU-Shops (read-heavy Katalog, überschaubare Bestell-Schreiblast) technisch tragfähig.
• Harte Grenze: eine Server-Maschine, ein Writer — gut bis Größenordnung ~500 aktive Nutzer/Tag; darüber Postgres auf derselben Box.
• Für einen einzelnen 08/15-Shop ist Shopware 6 / Medusa / Snipcart+Stripe pragmatischer.
• Postgres-Exit absichern: Datenzugriff bleibt hinter store-sqlite.js (siehe CLAUDE.md, Regel 3).

3. Neuen Kundenshop ausrollen (eine Codebasis, neue Instanz)

1. Coolify-App anlegen (Build-Pack: Dockerfile, Branch main, Repo till/hd-commerce).
   • application create_public verwirft den Git-Host → danach application update mit voller https://till:TOKEN@git.heidrich-digital.de/till/hd-commerce.git-URL.
2. Persistentes Volume auf /data mounten (eigener DB-Pfad je Shop, z. B. DB_PATH=/data/<kunde>.db).
3. ENV setzen (Minimal-Set, siehe §4). SESSION_SECRET, HDC_API_TOKEN, CRON_TOKEN je Shop eindeutig und zufällig.
4. Domain eintragen (echte Kundendomain statt sslip), Coolify zieht das Let's-Encrypt-Zertifikat; redirect: both (http→https). PUBLIC_BASE_URL=https://<domain> setzen.
5. Deploy → danach App control restart (Altcontainer räumen) → verifizieren (§6).
6. Branding im Admin → Einstellungen: Shop-Name, Akzentfarbe, Währung, Logo-Wortmarke, Module (Feature-Flags). Kein Code-Eingriff.
7. Inhalte: Startseite/Seiten über den Block-Builder, Produkte + Varianten, Versandzonen, Rabatte, Popups anlegen — alles im Admin oder per KI/MCP-API.

Pro Shop unterscheidet sich nur ENV + settings + DB-Inhalt. Der Code bleibt identisch und generisch (CLAUDE.md, Leitsatz).

4. ENV — Go-Live-Checkliste

Pflicht (Minimal-Betrieb):

• DB_PATH=/data/<kunde>.db (auf gemountetem Volume)
• ADMIN_EMAIL + ADMIN_PASS (Initial-Owner, nur erster Boot; danach im Admin verwaltbar)
• ADMIN_PATH (z. B. login oder intern — nicht das offensichtliche admin)
• SESSION_SECRET (langes Zufallsgeheimnis — in Prod zwingend, sonst nur persistenter Fallback)
• PUBLIC_BASE_URL=https://<domain> (korrigiert Proxy-Origin für Zahlungs-Return/Webhook)

Zahlung (für echten Verkauf):

• MOLLIE_API_KEY=test_… zum Testen, dann live_… → Provider wählt automatisch Mollie. Webhook automatisch {PUBLIC_BASE_URL}/api/payments/webhook.
• (Alternativ Stripe: STRIPE_SECRET_KEY + STRIPE_PUBLIC_KEY.) Ohne gültigen Key läuft der Demo-Checkout (kein echtes Geld).

Bestellmails (sonst nur Log-Fallback in email_log):

• MAIL_PROVIDER=listmonk + LISTMONK_URL/USER/PASS/TX_TEMPLATE_ID + MAIL_FROM — eine Listmonk-Instanz reicht für alle Shops (pro Shop Liste+Template+Absender).
• oder MAIL_PROVIDER=smtp + SMTP_HOST/PORT/USER/PASS/SECURE.

Backup (dringend für echten Shop):

• LITESTREAM_REPLICA_URL=s3://<bucket>/<pfad> + LITESTREAM_ACCESS_KEY_ID + LITESTREAM_SECRET_ACCESS_KEY + LITESTREAM_ENDPOINT (B2-EU). Siehe §7.

Optional:

• HDC_API_TOKEN (KI/MCP-API; leer ⇒ API gesperrt)
• CRON_TOKEN + Coolify-Scheduled-Task für Abandoned-Cart (§5)
• WEBP_QUALITY / WEBP_MAX_WIDTH, ABANDONED_AFTER_MINUTES

Vollständige Referenz: .env.example + README-Tabelle.

5. Wiederkehrende Jobs

Abandoned-Cart-Erinnerung — Coolify-Scheduled-Task (z. B. alle 30 Min):

curl -fsS -X POST -H "Authorization: Bearer $CRON_TOKEN" https://<domain>/api/cron/abandoned

Schickt fälligen, nicht erinnerten Warenkörben eine Mail (Mailer/Log-Fallback) und setzt reminded=1.

6. Verifizieren nach jedem Deploy

Immer cache-bustend per curl (nicht WebFetch — cacht):

curl -fsS -o /dev/null -w "%{http_code}\n" https://<domain>/                  # Storefront 200
curl -fsS -o /dev/null -w "%{http_code}\n" https://<domain>/<ADMIN_PATH>       # Login 200
curl -fsS -o /dev/null -w "%{http_code}\n" https://<domain>/api/admin -H "Authorization: Bearer $HDC_API_TOKEN"
curl -fsS -o /dev/null -w "%{http_code}\n" -I https://<domain>/                # http→https-Redirect prüfen

Erwartung: Storefront/Login 200, gebrandete 404 auf Unsinns-Pfad, ein Test-Checkout (Mollie-Test) bis „bezahlt".

7. Backup & Restore (Litestream)

• Aktiv, sobald LITESTREAM_REPLICA_URL gesetzt ist: der Container streamt DB_PATH live nach S3/B2 und stellt beim Start bei Bedarf wieder her. Ohne die Variable: normaler Node-Start ohne Backup.
• Status sichtbar unter Admin → Einstellungen → Backup (Litestream).
• Disaster-Recovery / Restore (neue Instanz, leeres Volume): erfolgt beim Start automatisch. Manuell:

  litestream restore -config /app/litestream.yml -if-replica-exists /data/<kunde>.db
  

• B2-Empfehlung: Bucket in EU (s3.eu-central-003.backblazeb2.com), Application-Key mit Schreibrechten, pro Shop eigener Pfad/Bucket.

8. Wartung / Care-Abo

• Updates: Änderungen am Produkt-Repo main; pro Kundenshop neu deployen + restart + verifizieren (§6). Migrationen laufen idempotent beim Boot — kein manueller DB-Schritt.
• Monitoring: Coolify-Healthcheck (/), App-Logs (application_logs). RAM-Cap je Shop setzen (Demo: 640 MB) — heidrich-infra-01 hat 8 GB ohne Swap, also nicht überbuchen.
• npm test muss grün sein, bevor neuer Code nach main geht (Geld/Versand/Rabatt/Sanitizer).
• Logs/Audit: Admin → Aktivität (Audit) protokolliert Create/Update/Delete; E-Mail-Log unter Einstellungen.

9. Sicherheit (Betreiber-Pflichten)

• SESSION_SECRET, HDC_API_TOKEN, CRON_TOKEN je Shop eindeutig und geheim (nur ENV).
• ADMIN_PATH nicht auf admin lassen. Rollen sparsam vergeben (owner/redaktion/versand).
• Roh-HTML in Inhalten läuft durch sanitizeHtml() — trotzdem nur vertrauenswürdigen Redakteuren html-Blöcke erlauben.
• Vor produktivem Verkauf: /engineering:security-review-Pass einplanen.

10. Reife-Status & offene Punkte (vor echtem, zahlendem Shop)

Funktional auf dem Niveau eines kleinen Shopify/Woo-Shops. Noch betrieblich zu erledigen (keine Features):

• Mollie live-Key getestet (Test-Checkout bis „bezahlt", Webhook setzt Bestellung auf bezahlt + Mail).
• Litestream mit echten Backblaze-B2-Zugangsdaten scharf geschaltet + ein Restore geprobt.
• Echte Rechtstexte: Impressum, Datenschutz, AGB, Widerruf + Cookie/Consent (DSGVO/BFSG).
• Listmonk/SMTP angebunden, damit Bestellmails real rausgehen (statt Log-Fallback).
• Security-Review-Pass vor Verkaufsstart.

11. Schnellreferenz

Sache	Wert
Repo	https://git.heidrich-digital.de/till/hd-commerce (Branch main)
Demo-App (Coolify)	lbv524oul6b6mxvo95pgxgso
Demo-URL	https://lbv524oul6b6mxvo95pgxgso.46.224.49.66.sslip.io
Demo-Admin	/login (ADMIN_PATH=login)
Demo-DB	/data/hdc2.db (Volume), RAM 640 MB
Port / Volume	4321 / /data
Tests	npm test
Nach Deploy	App restart → §6 verifizieren