drinks-on-chain-marketplace
S2 · Marketplace del ecosistema Drinks on Chain (app.): sitio público B2C, móvil primero. Aquí se verifica una botella con el código de su etiqueta (visor /b/{código}), se recorre el catálogo y se conoce a las bodegas; la cuenta, la compra y la cava llegan en las olas siguientes. Nació de drinks-on-chain-app-template (remoto template). Planificación en docs/ROADMAP.md y en drinks-on-chain-docsfront (roadmap 03 §6, bloques 2A–2F).
Qué hay hoy (Ola 2 · O2-MK-1)
| Pieza | Dónde |
|---|
| Next.js 16 (App Router, Turbopack), React 19, TypeScript estricto, Tailwind 4 | — |
StoreShell de @drinks-on-chain/ui: pestañas inferiores en móvil (Inicio, Catálogo, Verificar, Bodegas), cabecera en escritorio, salto al contenido | src/components/store-frame.tsx, src/lib/navigation.tsx |
| Portada: marca, "Verifica una botella", destacados del catálogo y bodegas | src/app/(store)/page.tsx, src/components/home/ |
2E · Visor /b/[code]: pasaporte de botella o de lote contra GET /v1/public/passports/{code}, con sus estados | src/app/(store)/b/, src/components/passport/, src/lib/passport/ |
Códigos: parseCode() (botella, lote o "mal escrito" con motivo y sugerencia) sobre las reglas de @drinks-on-chain/mocks | src/lib/codes/ |
2A · Catálogo sin cuenta y ficha de colección, contra el borrador /v1/public/collections | src/app/(store)/catalogo/, src/components/catalog/, src/lib/catalog/ |
Bodegas: directorio y página de bodega (GET /v1/public/wineries y /{slug}) | src/app/(store)/bodegas/, src/components/wineries/, src/lib/wineries/ |
Componentes de tienda locales, pendientes de mover a @drinks-on-chain/ui: JourneyTimeline, BottleCard, BottleArt, PriceTag, CodeInput | src/components/store/ |
/trace/batch/{lote} (URL del QR antiguo) → 308 a /b/{lote} | next.config.ts |
PWA básica: manifest, theme-color, iconos provisionales | src/app/manifest.ts, public/icons/, scripts/generate-icons.mjs |
Cliente de API tipado contra /api/v1/* del propio origen, con el proxy que firma la IP del visitante | src/lib/api/, src/proxy.ts, src/lib/api-proxy.ts |
Datos de prueba @drinks-on-chain/mocks 0.5.0-rc.3 con MSW en el navegador y panel /__mocks | src/app/providers.tsx (MocksGate), src/app/%5F%5Fmocks |
Rutas propias y enlaces a los otros sitios (hosts solo por NEXT_PUBLIC_URL_*) | src/lib/links.ts |
| Textos en español | src/lib/i18n/es.ts |
| Vitest + Testing Library (unitarias y de integración contra los handlers de los mocks), Playwright (390 px y 1280 px) con axe, ESLint, Prettier, CI | vitest.config.mts, playwright.config.ts, .github/workflows/ci.yml |
No hay sesión: el Marketplace de esta ola no autentica a nadie (la cuenta por correo llega en la Ola 3, bloque 2B) ni vende nada (la compra, en las Olas 3–4). De la plantilla se retiraron el login con roles, la guardia por audiencia, el selector de organización y src/lib/auth.
Empezar
Requisitos: Node 22 (.nvmrc) y pnpm 10 (corepack enable).
pnpm install
cp .env.example .env.local
pnpm dev:mocks # http://localhost:3005 con MSW
Códigos para probar con los mocks: la botella 664T-WFDA (n.º 1 del «Singani Gran Reserva 2026», expediente cerrado), 7T6B-ZK39 (código anulado), el lote CVJ-2026-SINGANI-004 y el vino CVJ-2026-WINE-003 (sin laboratorio, expediente abierto). Los lotes de PASSPORT_CASES cubren cada aviso: CUR-2026-SINGANI-001 (bodega suspendida), CVJ-2025-SINGANI-001 (lote retirado), ALT-2025-SINGANI-002 (D.O. por excepción y registro tardío) y ALT-2025-WINE-001 (laboratorio no conforme); con ?mock=pasaporte-saturado el visor recibe el 429 del límite por minuto. Hay más en publicFixtures.bottleCodes de @drinks-on-chain/mocks/fixtures.
| Script | Qué hace |
|---|
pnpm dev / pnpm dev:mocks | Servidor de desarrollo sin / con MSW (puerto 3005) |
pnpm lint, pnpm typecheck, pnpm test | Calidad (el typecheck genera antes los tipos de rutas de Next) |
pnpm e2e | Playwright contra un build de producción con mocks, en el puerto 3105 (en local usa tu Chrome) |
pnpm format | Prettier |
node scripts/generate-icons.mjs | Regenera los iconos provisionales de la PWA |
Variables de entorno
| Variable | Uso |
|---|
API_ORIGIN | Solo servidor. Origen del backend: src/proxy.ts reescribe /api/v1/* a ${API_ORIGIN}/v1/*. Obligatoria sin mocks, también en el build. Desarrollo: https://136.243.223.39.sslip.io |
PROXY_SHARED_SECRET | Solo servidor, nunca NEXT_PUBLIC_. Firma la IP del visitante para el backend: el mismo valor que en el backend del entorno. Sin ella, el límite de peticiones del pasaporte público contaría por la IP de la plataforma |
NEXT_PUBLIC_MOCKS | 1 arranca MSW (intercepta /api/v1/* en el navegador) y habilita /__mocks; con 1 no hace falta API_ORIGIN y nada se indexa (son datos de demostración) |
NEXT_PUBLIC_URL_APP | Origen público de este sitio, sin barra final (URL canónicas y metadatos). Coincide con PASSPORT_BASE_URL del backend, que es la URL que llevan los QR |
NEXT_PUBLIC_URL_LANDING | Landing principal: enlace del pie y destino de "Avísame" ({landing}/lista-de-espera?src=marketplace). Vacía = "Avísame" no aparece |
NEXT_PUBLIC_URL_BODEGAS | Sitio de las bodegas (enlace del pie); vacía = no se muestra |
Con el backend real (NEXT_PUBLIC_MOCKS=0)
Las pantallas no cambian; lo que cambia es lo que el backend ya publica:
- Bodegas (
/v1/public/wineries): funciona hoy contra el backend de desarrollo.
- Pasaporte: funciona contra el backend de desarrollo, con los esquemas de
@drinks-on-chain/mocks 0.5.0-rc.2 sin tolerancias (comprobado el 02-10-2026 con los lotes CVJ-2026-SINGANI-002, -004 y -005: el pasaporte pasa PublicCodePassportSchema, el expediente canónico pasa CanonicalDossierSchema y su huella coincide). El lote se pide en el servidor (ver más abajo); la botella, en el navegador. Una respuesta que no cumple el contrato es un error ("No pudimos consultar el código"), no un pasaporte a medias. Recorrido contra el backend real: E2E_REAL_API=1 E2E_API_ORIGIN=… pnpm e2e (e2e/backend-real.spec.ts; con E2E_BOTTLE_CODE comprueba también una botella).
- Catálogo (
/v1/public/collections): no existe en el backend (404). La portada y /catalogo dicen "próximamente" y la página de bodega no enseña colecciones; no se muestra ningún error.
Visor /b/{código} (2E)
- Código de botella (contrato de la Ola 2 §7.1): 8 caracteres del alfabeto Crockford (sin I, L, O, U), 7 de carga + 1 de control Luhn mod 32. Se imprime
664T-WFDA y viaja en la URL sin guion. Al leerlo se pasa a mayúsculas, se quitan espacios y guiones y se resuelven las confusiones O → 0 e I/L → 1.
- Código de lote (§6.3):
{prefijo}-{año}-{WINE|SINGANI}-{NNN}, p. ej. CVJ-2026-SINGANI-004.
- Una sola fuente: el alfabeto, el control, la normalización, el formato y
LOT_CODE_PATTERN salen de @drinks-on-chain/mocks (que porta el cálculo del backend). Aquí solo vive lo propio del visor: parseCode(texto) (src/lib/codes/parse.ts), que devuelve { kind: "bottle" | "lot", code, formatted } o { kind: "malformed", reason, length, suggestion } (motivos empty, too-short, too-long, characters, check), acepta guiones tipográficos y la URL del QR pegada entera, y la sugerencia (suggest.ts), que solo aparece cuando hay una única corrección probable y se ofrece como pregunta.
/b/[code] valida en el servidor: un código bien escrito pero no canónico (/b/664t-wfda) redirige con 308 a /b/664TWFDA; uno mal escrito abre el formulario con el motivo.- Los datos llegan por
usePassport(code) (src/lib/passport/hooks.ts): { state, retry, retrying } con state.status en loading, found, not-found (404 PUB_CODE_NOT_FOUND), malformed (422 PUB_CODE_MALFORMED), rate-limited (429, con retryAfter), offline o error. Solo se reintenta sola una caída de red: cada consulta cuenta para el límite por IP.
- El pasaporte (
PassportDocument, contrato §12.5):
- Botella: "Botella n.º N de M" con su código; aviso si el código está anulado. Lote: "Esta etiqueta identifica el lote". De la botella se pasa al lote (
/b/{lote}?desde={código}) y del lote se vuelve a la botella.
- Avisos de lote retirado y de bodega no activa (la bodega deja de enlazarse).
- Cabecera con nombre, tipo, añada y bodega; (cerrado con su huella abreviada, o abierto), "Anclaje en la red: pendiente" y (JSON).
El lote se pinta en el servidor
Con backend (NEXT_PUBLIC_MOCKS ≠ 1), /b/{lotCode} pide el pasaporte en el servidor (src/lib/passport/server.ts, contrato §12.4):
- Qué va en el HTML inicial: el pasaporte entero (cabecera, expediente, origen, elaboración, registro, laboratorio, reglas), legible sin JavaScript. Al hidratar no se vuelve a pedir nada. Los metadatos salen del lote (
src/lib/passport/metadata.ts): título, descripción, URL canónica, Open Graph y robots: index, follow.
- IP de quien visita: el freno a la enumeración y el límite por minuto del backend son por IP real. Cada petición del servidor lleva las cabeceras
X-DOC-Client-IP, X-DOC-Proxy-Timestamp y X-DOC-Proxy-Signature con la IP del visitante firmada (signedClientHeaders de src/lib/api-proxy.ts, lo mismo que hace src/proxy.ts). Nunca cuentan todas las visitas contra la IP del servidor.
- Caché: la del
Cache-Control del backend, 60 s y 3600 s con el lote certificado, por código de lote. No es la caché de fetch (su clave incluye las cabeceras, y las de la firma cambian en cada visita) sino unstable_cache, cuya clave es solo el código; la identidad del visitante viaja aparte, en un AsyncLocalStorage, hasta la petición que de verdad sale. Solo se guardan respuestas correctas: un 404, un 429 o un fallo no se guardan, así que el freno de una persona no afecta a otra.
- Estados: un lote que no existe responde 404 de verdad con el aviso del visor (
not-found.tsx) y una sola etiqueta robots (noindex); un 429 o un fallo pintan su estado y "Reintentar" vuelve a pedir la página al servidor.
- Mejora pendiente (no implementada): 304 con
ETag. El backend responde el pasaporte con ETag y acepta If-None-Match (304 sin cuerpo). El visor no lo aprovecha: el servidor guarda la respuesta el tiempo del Cache-Control y, pasado ese tiempo, vuelve a pedirla entera. Guardar el ETag junto al pasaporte y revalidar con If-None-Match ahorraría el cuerpo cuando el lote no cambió (lo habitual en uno certificado).
- Botella: sigue en el navegador (
usePassport, por el proxy firmado) y nunca se indexa. Con NEXT_PUBLIC_MOCKS=1 no hay backend en el servidor (MSW vive en el navegador), así que todo va por el camino del navegador y nada se indexa.
Catálogo (2A) · la API es un BORRADOR
GET /v1/public/collections y /{slug} no están en el OpenAPI del backend: son el borrador del contrato de la Ola 2 §17.1, que fijará el OpenAPI de la Etapa 4 (O3-PK-1) y puede cambiar sin aviso. Hoy solo los sirven los mocks (cabecera X-Mock-Draft), con precios y disponibilidad de ejemplo. Todo lo que depende de esa forma está en src/lib/catalog/ y marcado [BORRADOR §17.1].
/catalogo: lista con filtros en la URL (?tipo=vino|singani&estado=preventa|a-la-venta|agotado&bodega={slug}&q=…&pagina=N), paginación y estados cargando, vacío, sin coincidencias y error./catalogo/[slug]: ficha con precio que puede faltar ("Precio por anunciar", A-32), disponibilidad, estado (PRESALE, ON_SALE, SOLD_OUT), estado y línea de tiempo del lote, y enlace a su pasaporte si ya está embotellado.- Sin compra ni cuenta: la llamada a la acción es "Avísame", un enlace a la lista de espera de la landing (
links.waitlist).
- La portada pide las destacadas (
?featured=true) y el catálogo ofrece el orden del borrador (?orden=recientes|precio-menor|precio-mayor|nombre; por defecto, destacadas primero): nada se ordena en el cliente.
- Imágenes y logotipos de los datos:
DataImage los pinta cuando existen y cae a la botella a tinta o al monograma si faltan o fallan. Las rutas /mocks/uploads/… solo existen con MSW activo (los handlers las sirven); sin mocks se tratan como "sin imagen" (usableImageUrl).
PWA
Manifest generado por src/app/manifest.ts (/manifest.webmanifest): standalone, colores de papel, iconos de 192 y 512 px, uno adaptable y el de iOS (src/app/apple-icon.png). Los iconos son provisionales (la marca en texto, "DoC"). No hay service worker propio: los navegadores ya no lo exigen para instalar y, con NEXT_PUBLIC_MOCKS=1, el ámbito raíz lo ocupa el de MSW. El modo sin conexión de la cava es de la Ola 4 (2F).
Proxy de la API
El navegador llama a /api/v1/* de su propio origen y src/proxy.ts (src/lib/api-proxy.ts) lo reescribe a ${API_ORIGIN}/v1/* sin tocar método, cuerpo, cookies ni respuesta (Retry-After incluido). Con PROXY_SHARED_SECRET añade X-DOC-Client-IP, X-DOC-Proxy-Timestamp y X-DOC-Proxy-Signature (HMAC-SHA256 de MÉTODO|RUTA_CON_QUERY|IP|TIMESTAMP): el backend limita las consultas del pasaporte por la IP real de quien visita (contrato §12.4). Todas las peticiones llevan X-Client-App: MARKETPLACE.
Convenciones
Trabajo en dev, PR dev → main al cerrar la ola, Conventional Commits en español. Detalle en CLAUDE.md.
Actualizar los paquetes compartidos
@drinks-on-chain/ui y @drinks-on-chain/mocks se instalan desde el tarball de su GitHub Release:
pnpm add https://github.com/drinks-on-chain/drinks-on-chain-design-system/releases/download/vX.Y.Z/drinks-on-chain-ui-X.Y.Z.tgz
pnpm add https://github.com/drinks-on-chain/drinks-on-chain-mocks/releases/download/vX.Y.Z/drinks-on-chain-mocks-X.Y.Z.tgz
pnpm exec msw init public --save # si cambió msw
Las mejoras de la plantilla llegan con git fetch template && git merge template/dev.
