Globerce — tiendas de ropa con checkout por WhatsApp
Frontend de Globerce: el sitio que vende la plataforma, la tienda pública
de cada clienta (una por subdominio), su panel de administración y la consola
de la plataforma. Los cuatro salen del mismo despliegue y se reparten por host.
No hay pagos online en la tienda: la clienta arma su carrito, el pedido se
guarda en la API y se abre WhatsApp con el mensaje ya escrito para cerrar la
venta por chat.
Stack: SvelteKit 2 · Svelte 5 (runes) · TypeScript strict · Tailwind v4 ·
shadcn-svelte · API propia (ecommerce-api) · Cloudflare R2 · Vercel.
Los datos NO salen de Supabase: todo pasa por ecommerce-api, que es quien
habla con Postgres. Este repositorio no tiene acceso a la base. El porqué y
el cómo del aislamiento entre tiendas están en docs/ARCHITECTURE.md de ese
repositorio; lo que falta, en su docs/PENDIENTES.md.
Puesta en marcha
1. Dependencias
pnpm install
2. La API
Este frontend no arranca solo: necesita ecommerce-api corriendo (su README
explica cómo levantarla con Docker en un par de comandos). Por defecto escucha
en http://127.0.0.1:3000/v1.
3. Variables de entorno
cp .env.example .env
| Variable | Qué es |
|---|
API_URL | La API con su prefijo de versión. Solo se llama desde el servidor. |
API_SHARED_SECRET | El secreto que la API exige en producción (x-globerce-key). Vacío en desarrollo. |
SESSION_SECRET | Cifra la cookie del panel. Mínimo 32 caracteres; cambiarlo cierra todas las sesiones. |
PUBLIC_SITE_URL | URL pública, para los enlaces de WhatsApp y el sitemap. |
PUBLIC_STORE_ROOT_DOMAIN | Dominio de las tiendas: cada una es un subdominio suyo. |
PUBLIC_STORE_SLUG | Tienda que sirve el dominio raíz. Sin ella, el raíz muestra el sitio comercial. |
En local, boutique.localhost:5173 sirve la tienda boutique sin tocar
/etc/hosts.
4. Desarrollo
pnpm dev
Comandos
| Comando | Qué hace |
|---|
pnpm dev | Servidor de desarrollo |
pnpm build | Build de producción |
pnpm check | Tipos de TypeScript y Svelte |
pnpm lint | ESLint |
pnpm format | Prettier |
pnpm test | Tests unitarios (vitest) |
Los cinco deben pasar antes de mergear. Si un hook de pre-commit falla, arregla
la causa: nunca --no-verify.
Qué sirve cada host
El hook universal src/hooks.ts decide antes de enrutar:
| Host | Qué muestra |
|---|
globerce.store | El sitio que vende Globerce, y /registro |
boutique.globerce.store | La tienda de esa clienta |
cualquiera de los dos + /admin | El panel de la tienda del host |
.../plataforma | La consola de quien vende el software |
Los subdominios reservados (www, api, admin…) nunca son una tienda, y la
API tampoco deja registrarlos.
Cómo funciona la compra
- Carrito en el navegador.
localStorage guarda solo variantId y
cantidad — nunca precios. Vive en src/lib/stores/cart.svelte.ts.
- Revalidación.
/carrito manda el carrito a la form action ?/preparar,
que recalcula precios y stock reales, valida el cupón y suma el envío.
- Creación del pedido.
?/confirmar se lo pide a la API, que bloquea las
variantes, vuelve a verificar stock, recalcula todo desde la base, descuenta
inventario e inserta el pedido en una sola transacción.
- WhatsApp. Se redirige a
/pedido/[number]?t=<token>, que arma el mensaje
y ofrece el botón para abrir el chat. El token del enlace permite compartir
el pedido sin exponer los demás.
- Panel. La administradora confirma, envía o cancela. Cancelar devuelve el
stock y libera el uso del cupón.
Los precios se recalculan siempre en el servidor: un carrito viejo nunca compra
a precio viejo.
Estructura
src/
├── lib/
│ ├── actions/ Acciones de Svelte (reveal al hacer scroll)
│ ├── components/
│ │ ├── ui/ Primitivas shadcn-svelte (no editar a mano)
│ │ ├── atoms/ Wrappers de marca — los únicos que se importan
│ │ ├── molecules/ Composiciones sin lógica de negocio
│ │ └── organisms/ Composiciones con stores y form actions
│ ├── domain/ Tipos y reglas del dominio, en snake_case
│ ├── schemas/ Validación zod, la misma en el navegador y el servidor
│ ├── server/ Todo lo que habla con la API, la sesión y el contexto
│ ├── stores/ Carrito y favoritos (runes + localStorage)
│ └── utils/ Funciones puras (dinero, WhatsApp, slugs, formularios)
└── routes/
├── (marketing)/ El sitio que vende Globerce
├── (shop)/ La tienda pública
├── (admin)/admin/ El panel (login fuera del guard, resto dentro)
└── (platform)/ La consola de la plataforma
Notas de operación
- Sesión. Cookie cifrada (AES-256-GCM) con los tokens de la API dentro.
Se emite para todo el dominio raíz, porque el registro vive arriba y el panel
de cada tienda en su subdominio.
- Stock. Se descuenta al crear el pedido, no al pagar. Un pedido pendiente
retiene inventario hasta que se confirme o cancele; el panel destaca los que
llevan más de 24 horas.
- Imágenes. Las convierte la API al subirlas: tres tamaños en WebP
(400/800/1600 px) más un LQIP embebido. Este frontend solo reenvía el archivo
tal como llega del formulario.
- Plantillas. Cada tienda elige con cuál se viste; los tokens de cada una
están en
src/app.css, bajo [data-storefront-template], y el catálogo en
src/lib/domain/templates.ts.
- Adaptador. En Vercel se usa
adapter-vercel; en local, adapter-node,
porque el de Vercel crea symlinks y Windows los bloquea sin modo desarrollador.
- Registro npm. El
.npmrc del proyecto apunta al registro público, para no
heredar el CodeArtifact privado configurado a nivel de usuario.
