Doku: CLAUDE.md (Arbeitsvereinbarung) + HANDOVER.md (Betriebs-/Go-Live-Runbook)

2026-06-21 06:02:37 +00:00
parent 50dfca59e1
commit 5b54f4aff7
2 changed files with 238 additions and 0 deletions
@@ -0,0 +1,139 @@
+# 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 |