bighadj22/codflow

CodFlow Storefront – Vercel-Deployment-Runbook

cod-astro/theme01 ist das kundenseitige Storefront-Theme für CodFlow (Astro 7). Während das CodFlow-Backend (cod-server) und das Händler-Dashboard (cod-client-astro) auf Cloudflare Workers (mit D1, R2 und KV) laufen, unterstützt die Storefront dynamische Deployment-Ziele (DEPLOY_TARGET=vercel oder DEPLOY_TARGET=cloudflare).

Die Bereitstellung der Storefront auf Vercel wird oft bevorzugt, weil:

1. Löst Cloudflare Error 1042 (Worker-to-Worker-Block): Wenn cod-server auf einer kostenlosen *.workers.dev-Subdomain ohne benutzerdefinierte Domain bereitgestellt wird, blockiert Cloudflare den Aufruf durch einen anderen Cloudflare Worker auf *.workers.dev. Vercel läuft außerhalb des internen Cloudflare-Netzwerks, sodass die Storefront cod-server auf *.workers.dev abrufen kann, ohne eine benutzerdefinierte Domain zu benötigen.
2. Großzügige globale Edge-Bandbreite: Vercel bietet großzügige Bandbreite und Edge-CDN-Caching für Storefront-Traffic.
3. Automatische Preview-Deployments: Jeder Git-Branch/PR kann eine eigene Preview-URL zum Testen von Theme-Änderungen erhalten.

---

Erforderliche Umgebungsvariablen

Sammeln Sie vor der Bereitstellung diese Werte:

Variable	Beschreibung	Beispiel
DEPLOY_TARGET	Erforderlich. Teilt astro.config.mjs mit, @astrojs/vercel zu verwenden	vercel
COD_SERVER_URL	Erforderlich. Basis-URL des bereitgestellten cod-server-API	https://api.yourdomain.com oder https://codflow-server.<account>.workers.dev
STORE_API_KEY	Erforderlich. Roh-Store-API-Schlüssel, der dem in D1 gesäten Schlüssel entspricht	Generiert in codflow-setup Schritt 4
MEDIA_DOMAIN	Optional. Benutzerdefinierte Domain für das R2-Bild-CDN	media.yourdomain.com

[!WICHTIG] STORE_API_KEY ist geheim. Er wird serverseitig in SSR-Routen und API-Proxys verwendet. Setzen Sie ihn niemals in clientseitigen Bundles ein.

---

Bereitstellungsmethoden

Wählen Sie Methode 1 (Vercel CLI) für automatisierte/Terminal-Bereitstellungen oder Methode 2 (Vercel Dashboard / Git) für kontinuierliches Deployment aus GitHub.

---

Methode 1: Bereitstellung über Vercel CLI (Empfohlen für KI-Agenten)

1. Voraussetzungen

• Stellen Sie sicher, dass die Vercel CLI über npx vercel verfügbar ist (oder global installiert).
• Überprüfen Sie die Authentifizierung:

  npx vercel whoami
  

  Wenn nicht eingeloggt:
  • Wenn ein Browser verfügbar ist: npx vercel login
  • Wenn headless/CI: Setzen Sie VERCEL_TOKEN in der Umgebung (export VERCEL_TOKEN="<token>").

2. Projekt konfigurieren und verknüpfen

Navigieren Sie zum Storefront-Verzeichnis:

cd cod-astro/theme01

Führen Sie die Ersteinrichtung aus:

npx vercel link

Folgen Sie den interaktiven Eingabeaufforderungen (oder geben Sie Flags in nicht-interaktiven Sitzungen an):

• Mit vorhandenem Projekt verknüpfen? Nein (oder Ja, falls vorhanden)
• Projektname: <projekt>-storefront (z. B. mystore-storefront)
• In welchem Verzeichnis befindet sich Ihr Code? ./

3. Umgebungsvariablen setzen

Fügen Sie die erforderlichen Produktions-Umgebungsvariablen mit der CLI hinzu:

# 1. Deployment-Ziel
printf "vercel" | npx vercel env add DEPLOY_TARGET production

# 2. Backend-API-URL (muss mit https:// beginnen)
printf "https://<your-cod-server-domain>" | npx vercel env add COD_SERVER_URL production

# 3. Store-API-Schlüssel
printf "<your-raw-store-api-key>" | npx vercel env add STORE_API_KEY production

# 4. Optional: Media-Domain (falls benutzerdefinierte R2-Domain konfiguriert)
printf "<media.yourdomain.com>" | npx vercel env add MEDIA_DOMAIN production

(Optional: Fügen Sie sie auch für die Umgebungen preview und development hinzu, wenn Sie Preview-Branches verwenden möchten).

4. Build und Deployment auf Produktion

Führen Sie das Produktionsdeployment mit dem Vercel-Adapter aus:

cd cod-astro/theme01
npx vercel --prod

Vercel lädt das Projekt hoch, führt npm run build:vercel (oder astro build mit DEPLOY_TARGET=vercel) aus, kompiliert die SSR-Serverless/Edge-Funktionen und stellt die Live-Produktions-URL bereit (z. B. https://<projekt>-storefront.vercel.app).

---

Methode 2: Bereitstellung über Vercel Dashboard (Git-Integration)

Verwenden Sie diese Methode, wenn Sie ein GitHub / GitLab / Bitbucket-Repository verbinden:

1. Repository in Vercel importieren:

   • Klicken Sie im Vercel Dashboard auf Neues hinzufügen... → Projekt.
   • Wählen Sie das codflow-os-Repository aus.

2. Projekteinstellungen konfigurieren:

   • Projektname: z. B. codflow-storefront
   • Framework-Preset: Astro
   • Root-Verzeichnis: Klicken Sie auf Bearbeiten und wählen Sie cod-astro/theme01. Aktivieren Sie die Option „Quelldateien außerhalb des Root-Verzeichnisses in den Build-Schritt einbeziehen“ (erforderlich, da Workspace-Abhängigkeiten auf das Root-node_modules verweisen).
   • Build-Befehl: Schalten Sie Überschreiben um und setzen Sie:

     npm run build:vercel
     

     (Oder lassen Sie den Standard astro build, wenn DEPLOY_TARGET=vercel in den Umgebungsvariablen gesetzt ist).
   • Ausgabeverzeichnis: Standard lassen (.vercel/output).
   • Installationsbefehl: Standard lassen (npm install / Root-Workspace-Installation).

3. Umgebungsvariablen konfigurieren: Fügen Sie unter Umgebungsvariablen hinzu:

   • DEPLOY_TARGET = vercel
   • COD_SERVER_URL = https://<your-cod-server-domain>
   • STORE_API_KEY = <your-raw-store-api-key>
   • MEDIA_DOMAIN = <media.yourdomain.com> (optional)

4. Bereitstellen:

   • Klicken Sie auf Bereitstellen. Vercel baut den Workspace, bündelt die Astro-Site mit @astrojs/vercel und weist eine Produktions-URL zu.

---

Verifikation & Smoke-Tests

Nach Abschluss des Deployments führen Sie diese Überprüfungen gegen die Live-Vercel-URL durch:

Ziel	Testbefehl / Aktion	Erwartetes Ergebnis
Startseite	curl -s -o /dev/null -w "%{http_code}" https://<storefront-url>	200 (HTML-Antwort)
Katalog SSR	Öffnen Sie https://<storefront-url>/ im Browser	Produkte werden mit Bildern, Preisen und Titel angezeigt
Produktdetail	Öffnen Sie https://<storefront-url>/product/<slug>	Produktseite wird mit Checkout / Bestellformular gerendert
Warenkorb / Bestellablauf	Testbestellung abschicken (oder Testmodal)	Bestellung wird registriert und Danke-Seite wird angezeigt

Test über Terminal:

# Überprüfen, ob die Startseite 200 OK zurückgibt
curl -s -I "https://<your-storefront>.vercel.app" | head -n 5

# API-Konnektivität über den Storefront-Proxy überprüfen
curl -s "https://<your-storefront>.vercel.app/api/cart/validate" \
  -H "Content-Type: application/json" \
  -d '{"items":[]}'
# Erwarte gültige JSON-Antwort

---

Benutzerdefinierte Domain einrichten

So hängen Sie eine benutzerdefinierte Domain an die Vercel-Storefront an:

1. Im Vercel Dashboard: Projekt → Einstellungen → Domains.
2. Geben Sie Ihre Domain ein (z. B. store.yourdomain.com oder yourdomain.com).
3. DNS-Einträge konfigurieren:
   • Für Subdomains (store.yourdomain.com): CNAME-Eintrag, der auf cname.vercel-dns.com zeigt.
   • Für Apex-Domain (yourdomain.com): A-Eintrag, der auf 76.76.21.21 zeigt.
4. Warten Sie auf die Ausstellung des SSL-Zertifikats (automatisch über Let's Encrypt).

---

Fehlerbehebung

Problem	Ursache	Lösung
Build schlägt fehl: Cannot find module '@astrojs/vercel'	Fehlende Abhängigkeit in cod-astro/theme01	Führen Sie npm install @astrojs/vercel --workspace=cod-astro-theme01 im Repository-Root aus.
Build produziert Cloudflare-Ausgabe statt Vercel-Ausgabe	DEPLOY_TARGET ist nicht auf vercel gesetzt	Stellen Sie sicher, dass DEPLOY_TARGET=vercel in den Vercel-Umgebungsvariablen vorhanden ist, oder führen Sie npm run build:vercel aus.
Storefront lädt, zeigt aber leere Produkte / Fehlerbanner	COD_SERVER_URL ist falsch oder nicht erreichbar	Überprüfen Sie, ob COD_SERVER_URL das Präfix https:// hat und mit dem Live-API-Worker übereinstimmt. Verifizieren Sie, dass curl https://<api-url>/api/docs 200 zurückgibt.
Bestellungen schlagen mit 401 Unauthorized fehl	STORE_API_KEY stimmt nicht überein	Der Wert in STORE_API_KEY in Vercel muss mit dem in der D1-Datenbank in codflow-setup Schritt 5 gesäten Schlüssel übereinstimmen. Überprüfen oder aktualisieren Sie das Secret in Vercel.
Monorepo-Build schlägt fehl, gemeinsame Pakete aufzulösen	Vercel Root-Verzeichnis-Konfiguration	Stellen Sie bei Git-Integration sicher, dass „Quelldateien außerhalb des Root-Verzeichnisses einbeziehen“ in den Vercel-Projekteinstellungen aktiviert ist, oder deployen Sie über npx vercel innerhalb von cod-astro/theme01.
Node.js-Versionswarnung: Node.js 26 wird nicht unterstützt	Vercel Serverless-Funktionen unterstützen bis Node 24	Normale Warnung auf Node-26-Entwicklungsmaschinen; Vercel führt automatisch Node 24 in seinen Cloud-Funktionen aus.
Bilder werden nicht von R2 geladen	MEDIA_DOMAIN falsch konfiguriert oder CORS fehlt	Überprüfen Sie, ob MEDIA_DOMAIN gesetzt ist (nur Hostname, ohne https://). Stellen Sie sicher, dass die R2-Bucket-CORS-Richtlinie Anfragen von der Vercel-Domain erlaubt.