bighadj22/codflow

Escaparate CodFlow — Manual de Despliegue en Vercel

cod-astro/theme01 es el tema del escaparate orientado al cliente para CodFlow (Astro 7). Mientras que el backend de CodFlow (cod-server) y el panel de administración (cod-client-astro) ejecutan en Cloudflare Workers (usando D1, R2 y KV), el escaparate soporta destinos de despliegue dinámicos (DEPLOY_TARGET=vercel o DEPLOY_TARGET=cloudflare).

Desplegar el escaparate en Vercel suele ser preferido porque:

1. Soluciona el Error 1042 de Cloudflare (bloqueo Worker-a-Worker): Cuando cod-server está desplegado en un subdominio gratuito *.workers.dev sin un dominio personalizado, Cloudflare bloquea que otro Worker de Cloudflare en *.workers.dev realice solicitudes a él. Vercel opera fuera de la red interna de Cloudflare, permitiendo que el escaparate obtenga datos de cod-server en *.workers.dev sin necesidad de un dominio personalizado.
2. Amplio ancho de banda global en el Edge: Vercel incluye un ancho de banda generoso y almacenamiento en caché CDN en el Edge para el tráfico del escaparate.
3. Despliegues de vista previa automáticos: Cada rama/PR de Git puede tener su propia URL de vista previa para probar cambios en el tema.

---

Variables de Entorno Requeridas

Antes de desplegar, recoge estos valores:

Variable	Descripción	Ejemplo
DEPLOY_TARGET	Obligatorio. Indica a astro.config.mjs que use @astrojs/vercel	vercel
COD_SERVER_URL	Obligatorio. URL base de la API cod-server desplegada	https://api.yourdomain.com o https://codflow-server.<account>.workers.dev
STORE_API_KEY	Obligatorio. Clave API de la tienda sin procesar, que coincide con la clave inicializada en D1	Generada en codflow-setup Paso 4
MEDIA_DOMAIN	Opcional. Dominio personalizado para el CDN de imágenes R2	media.yourdomain.com

[!IMPORTANTE] STORE_API_KEY es secreta. Se usa en el lado del servidor en rutas SSR y proxies de API. Nunca la expongas en paquetes del lado del cliente.

---

Métodos de Despliegue

Elige el Método 1 (CLI de Vercel) para despliegues automatizados/en terminal, o el Método 2 (Panel de Vercel / Git) para despliegue continuo desde GitHub.

---

Método 1: Desplegar mediante CLI de Vercel (Recomendado para Agentes de IA)

1. Requisitos Previos

• Asegúrate de que la CLI de Vercel sea accesible mediante npx vercel (o instalada globalmente).
• Verifica la autenticación:

  npx vercel whoami
  

  Si no has iniciado sesión:
  • Si hay un navegador disponible: npx vercel login
  • Si es headless/CI: Establece VERCEL_TOKEN en el entorno (export VERCEL_TOKEN="<token>").

2. Configurar y Vincular el Proyecto

Navega al directorio del escaparate:

cd cod-astro/theme01

Ejecuta la configuración inicial:

npx vercel link

Sigue las indicaciones interactivas (o proporciona banderas en sesiones no interactivas):

• ¿Vincular a un proyecto existente? No (o Sí si estás vinculando uno existente)
• Nombre del proyecto: <project>-storefront (ej. mystore-storefront)
• ¿En qué directorio se encuentra tu código? ./

3. Establecer Variables de Entorno

Añade las variables de entorno de producción requeridas usando la CLI:

# 1. Destino de Despliegue
printf "vercel" | npx vercel env add DEPLOY_TARGET production

# 2. URL de la API del Backend (debe comenzar con https://)
printf "https://<tu-dominio-cod-server>" | npx vercel env add COD_SERVER_URL production

# 3. Clave API de la Tienda
printf "<tu-clave-api-tienda-sin-procesar>" | npx vercel env add STORE_API_KEY production

# 4. Opcional: Dominio de Medios (si el dominio personalizado de R2 está configurado)
printf "<media.yourdomain.com>" | npx vercel env add MEDIA_DOMAIN production

(Opcional: también añádelas a los entornos preview y development si planeas usar ramas de vista previa).

4. Construir y Desplegar a Producción

Ejecuta el despliegue a producción con el adaptador de Vercel:

cd cod-astro/theme01
npx vercel --prod

Vercel subirá el proyecto, ejecutará npm run build:vercel (o astro build con DEPLOY_TARGET=vercel), compilará las funciones serverless/edge SSR y proporcionará la URL de producción activa (ej. https://<project>-storefront.vercel.app).

---

Método 2: Desplegar mediante el Panel de Vercel (Integración con Git)

Usa este método cuando conectes un repositorio de GitHub / GitLab / Bitbucket:

1. Importar Repositorio en Vercel:

   • En el Panel de Vercel, haz clic en Añadir Nuevo... → Proyecto.
   • Selecciona el repositorio codflow-os.

2. Configurar Opciones del Proyecto:

   • Nombre del Proyecto: ej. codflow-storefront
   • Plantilla de Framework: Astro
   • Directorio Raíz: Haz clic en Editar y elige cod-astro/theme01. Marca la opción "Incluir archivos fuente fuera del Directorio Raíz en el Paso de Construcción" (necesario porque las dependencias del workspace se resuelven en node_modules raíz).
   • Comando de Construcción: Activa Anular y establece:

     npm run build:vercel
     

     (O deja el valor por defecto astro build si DEPLOY_TARGET=vercel está configurado en Variables de Entorno).
   • Directorio de Salida: Deja el valor por defecto (.vercel/output).
   • Comando de Instalación: Deja el valor por defecto (npm install / instalación del workspace raíz).

3. Configurar Variables de Entorno: Bajo Variables de Entorno, añade:

   • DEPLOY_TARGET = vercel
   • COD_SERVER_URL = https://<tu-dominio-cod-server>
   • STORE_API_KEY = <tu-clave-api-tienda-sin-procesar>
   • MEDIA_DOMAIN = <media.yourdomain.com> (opcional)

4. Desplegar:

   • Haz clic en Desplegar. Vercel construirá el workspace, empaquetará el sitio Astro con @astrojs/vercel y asignará una URL de producción.

---

Verificación y Pruebas de Humo

Una vez que el despliegue se complete, ejecuta estas comprobaciones contra la URL activa de Vercel:

Destino	Comando / Acción de Prueba	Resultado Esperado
Página de Inicio	curl -s -o /dev/null -w "%{http_code}" https://<url-escaparate>	200 (respuesta HTML)
Catálogo SSR	Abrir https://<url-escaparate>/ en el navegador	Los productos se cargan con imágenes, precios y título
Detalle de Producto	Abrir https://<url-escaparate>/product/<slug>	La página del producto se renderiza con formulario de pago / pedido
Flujo de Carrito / Pedido	Enviar un pedido de prueba (o modal de prueba)	El pedido se registra y se muestra la página de agradecimiento

Prueba mediante Terminal:

# Verificar que la página de inicio devuelve 200 OK
curl -s -I "https://<tu-escaparate>.vercel.app" | head -n 5

# Verificar la conectividad con la API a través del proxy del escaparate
curl -s "https://<tu-escaparate>.vercel.app/api/cart/validate" \
  -H "Content-Type: application/json" \
  -d '{"items":[]}'
# Se espera una respuesta JSON válida

---

Configuración de Dominio Personalizado

Para asociar un dominio personalizado al escaparate de Vercel:

1. En el Panel de Vercel: Proyecto → Configuración → Dominios.
2. Introduce tu dominio (ej. store.yourdomain.com o yourdomain.com).
3. Configura los registros DNS:
   • Para subdominios (store.yourdomain.com): Añade un registro CNAME que apunte a cname.vercel-dns.com.
   • Para dominio apex (yourdomain.com): Añade un registro A que apunte a 76.76.21.21.
4. Espera la emisión del certificado SSL (automática mediante Let's Encrypt).

---

Solución de Problemas

Problema	Causa	Solución
Error de construcción: Cannot find module '@astrojs/vercel'	Falta la dependencia en cod-astro/theme01	Ejecuta npm install @astrojs/vercel --workspace=cod-astro-theme01 en la raíz del repositorio.
La construcción produce salida de Cloudflare en lugar de salida de Vercel	DEPLOY_TARGET no está configurado como vercel	Asegúrate de que DEPLOY_TARGET=vercel esté presente en las variables de entorno de Vercel, o ejecuta npm run build:vercel.
El escaparate carga pero muestra productos vacíos / banner de error	COD_SERVER_URL incorrecto o inalcanzable	Confirma que COD_SERVER_URL tenga el prefijo https:// y coincida con el worker de API activo. Verifica que curl https://<url-api>/api/docs devuelva 200.
Los pedidos fallan con 401 No Autorizado	STORE_API_KEY no coincide	El valor en STORE_API_KEY de Vercel debe coincidir con la clave inicializada en la base de datos D1 en el codflow-setup Paso 5. Vuelve a verificar o actualiza el secreto en Vercel.
La construcción del monorepo falla al resolver paquetes compartidos	Configuración del directorio raíz en Vercel	Si usas integración con Git, asegúrate de que la opción "Incluir archivos fuente fuera del Directorio Raíz" esté habilitada en la configuración del proyecto de Vercel, o despliega mediante npx vercel dentro de cod-astro/theme01.
Advertencia de versión de Node.js: Node.js 26 no es compatible	Las funciones serverless de Vercel solo soportan hasta Node 24	Advertencia normal en máquinas de desarrollo con Node 26; Vercel ejecuta automáticamente Node 24 en sus funciones en la nube.
Las imágenes no se cargan desde R2	MEDIA_DOMAIN mal configurado o falta CORS	Verifica que MEDIA_DOMAIN esté configurado (solo el nombre de host, sin https://). Asegúrate de que la política CORS del bucket R2 permita solicitudes desde el dominio de Vercel.