adriMarket

Motor de reservas para tours en el Caribe y renta de inmuebles. Dos inventarios que se compran igual y se operan distinto, con un solo checkout: se cobra un anticipo en línea y el saldo se paga en destino.

Estado: el producto está completo y verificado de extremo a extremo (Sprints 0 a 7): se reserva, se cobra el anticipo, se opera el día a día, se resuelven cancelaciones y cambios de fecha, se publica catálogo desde el panel, y los avisos salen por correo y WhatsApp con monitoreo.

Lo que impide vender no es código, son tres cuentas del cliente: Stripe, el dominio de correo autenticado y el número de WhatsApp con sus plantillas aprobadas por Meta. La lista del día del despliegue está en docs/puesta-en-produccion.md.

• Empieza aquí si vas a trabajar en el código: CLAUDE.md — cómo levantarlo, qué no se negocia y las trampas que ya costaron caro.
• Plan maestro (columna vertebral, una sola fuente de verdad): docs/plan-de-entrega.md
• Arquitectura y decisiones: docs/arquitectura.md · dónde vive el sistema
• Esquema: docs/esquema.md
• Para operar: docs/puesta-en-produccion.md · docs/operacion.md (qué hacer cuando algo falla) · docs/manual-del-panel.md (para el equipo del cliente)
• Cerrados: sprint-01.md · sprint-02.md · sprint-03.md · sprint-04.md · sprint-05.md · sprint-06.md · sprint-07.md

Cómo correrlo

Se necesita PostgreSQL 16 o superior, Node 22 y psql en el PATH.

cp .env.example .env          # y apuntar DATABASE_URL a tu base
npm install

npm run db:migrate            # aplica las migraciones pendientes
npm run db:seed               # datos de desarrollo
npm run dev                   # el sitio en http://localhost:3000

Verificación, que es lo mismo que corre el pipeline:

npm run db:test               # garantías del inventario (en transacción, sin dejar rastro)
npm run test:integration      # capa de acceso: traducción de errores del dominio
npm run typecheck
npm run lint
NEXT_PUBLIC_SITE_URL=http://127.0.0.1:3100 npm run build
npx next start -p 3100 &
BASE_URL=http://127.0.0.1:3100 ./scripts/smoke.sh   # criterios sobre el sitio construido
BASE_URL=http://127.0.0.1:3100 npm run test:e2e        # el checkout, en navegador real
BASE_URL=http://127.0.0.1:3100 npm run test:e2e:admin  # un día de operación en el panel
BASE_URL=http://127.0.0.1:3100 npm run test:e2e:sme    # el día que cierran el puerto
BASE_URL=http://127.0.0.1:3100 npm run test:e2e:publicar # publicar un tour sin ayuda
BASE_URL=http://127.0.0.1:3100 npm run audit           # accesibilidad (axe) y peso de las páginas
npm run db:bench              # prueba de carga: sobreventa bajo concurrencia

NEXT_PUBLIC_SITE_URL se fija al construir, no al arrancar: Next reemplaza esas variables durante la compilación. La pasarela recibe una URL de retorno absoluta, así que si no coincide con el puerto donde se sirve, el navegador vuelve de pagar a un servidor que no existe.

npm run db:reset recrea todo desde cero. Se niega a correr contra una URL que no sea local.

Estructura

db/
  migrations/       SQL escrito a mano, en orden. Fuente de verdad del esquema.
  seed/             datos de desarrollo
  tests/            pruebas de las garantías y de concurrencia
src/
  app/[locale]/     rutas públicas; el prefijo de idioma es parte de la URL
  app/admin/        panel de operación; sin prefijo de idioma y sin indexar
  app/media/        entrega de las fotos subidas (no van en public/, ver abajo)
  components/       componentes de la vitrina
  db/               cliente, tipos propios y esquema generado por introspección
  i18n/             idiomas, segmentos traducidos y etiquetas de interfaz
  modules/          módulos de dominio (frontera explícita entre ellos)
scripts/            ciclo de vida de la base, verificación y generación
docs/               arquitectura, esquema, plan de entrega y decisiones

Decisiones de la vitrina

• Cada idioma tiene su propia URL (/es, /en), con el segmento de colección traducido (/es/estancias/… ↔ /en/stays/…). Si las dos versiones compartieran dirección, solo una posicionaría en buscadores — y el tráfico orgánico en inglés es justo el que evita pagar comisión a un intermediario.
• Un producto sin traducción responde 404 en ese idioma, en lugar de mostrar contenido a medio traducir.
• Los filtros viven en la URL y el formulario funciona sin JavaScript: la búsqueda se puede compartir, recargar y renderizar en el servidor.
• El precio de la vitrina es un "desde". El total exacto depende de fechas y personas, y tiene una sola fuente autorizada en el servidor (Sprint 2). Mostrar un aproximado que después cambia es la forma más rápida de perder la confianza del huésped.
• canonical y hreflang se emiten absolutos: los buscadores ignoran hreflang relativo. Verificado en scripts/smoke.sh, no supuesto.

Por qué el SQL se escribe a mano

Las garantías del negocio están declaradas en la base, no verificadas en la aplicación, y eso necesita SQL que ningún generador expresa: restricciones de exclusión sobre rangos de fechas, bloqueos de fila, funciones transaccionales.

El flujo es al revés de lo habitual: el SQL manda y los tipos se generan. npm run db:pull introspecta la base y reescribe src/db/generated/, así el código no puede desviarse del esquema real. scripts/patch-generated.mjs corrige después las dos cosas que drizzle-kit no sabe leer (daterange y los DEFAULT que llaman funciones de Postgres); es idempotente y avisa si algún día deja de haber algo que parchar.

No se usan las migraciones de drizzle-kit: el script las descarta para que no compitan con las escritas a mano.

Las dos garantías del inventario

Son mecanismos distintos porque los dos inventarios se agotan distinto:

	Estancias	Tours
Se agota por	traslape de rangos de fechas	conteo de lugares
Garantía	EXCLUDE USING gist (unit_id =, stay &&)	CHECK (seats_taken <= capacity)
Orden entre peticiones	lo da la restricción de exclusión	SELECT … FOR UPDATE
Verificado en	db/tests/guarantees.sql 1–4	db/tests/guarantees.sql 5–7

Ninguna de las dos depende de que la aplicación se acuerde de revisar. Están probadas con clientes concurrentes de verdad (npm run db:bench), no solo en secuencia:

A) 200 intentos de 40 clientes sobre 20 lugares  →  20 apartados, 180 rechazados, drift 0
B) 80 intentos de 40 clientes, mismo rango       →  1 apartado
C) 40 clientes, rangos contiguos                 →  40 apartados, 0 falsos conflictos

Códigos de error del dominio

La base los emite como SQLSTATE propios y src/modules/availability/holds.ts los traduce a InventoryUnavailableError con un mensaje que se le puede mostrar al huésped.

Código	Significado
AM001	cupo agotado en la salida
AM002	fechas ya ocupadas en la unidad
AM003	transición de estado inválida

Cancelar, devolver y mover

Tres reglas que vienen del SME y no del esquema:

• Una cancelación del operador no es una cancelación del huésped. Cuando la capitanía cierra el puerto se devuelve todo lo pagado y la política de cancelación no aplica. Cobrarle una penalización a alguien por un huracán es el error que el diseño existe para impedir.
• El reembolso sale de la política congelada en la reserva, nunca de la vigente. El huésped aceptó un texto concreto en el checkout; que el cliente la edite después no cambia lo ya acordado.
• Mover una reserva conserva el anticipo cobrado. La diferencia de tarifa se ajusta en el saldo que se paga en destino, y todo ocurre en una transacción: si las fechas nuevas no están libres, el huésped no se queda sin las que tenía.

Los reembolsos se registran en la base a la espera de que la pasarela ejecute el movimiento, igual que los cobros.

Pagos y avisos: proveedores intercambiables

src/modules/payments y src/modules/notifications hablan con Stripe y Resend por HTTP, detrás de una interfaz. Sin llaves configuradas se usan proveedores locales que no son dobles de prueba: firman y verifican con el mismo mecanismo que los reales, y el aviso se guarda renderizado en la bandeja en lugar de enviarse. El camino que se ejercita —firma, idempotencia, confirmación transaccional, reintentos— es el de producción; lo único que no ocurre es el cobro y el envío.

Con STRIPE_SECRET_KEY y STRIPE_WEBHOOK_SECRET presentes se usa Stripe. La selección es por configuración y no por una bandera de "modo desarrollo": sin llaves no hay nada que cobrar, y con llaves siempre se usa la real.

WhatsApp

El huésped que reserva por WhatsApp espera la confirmación por WhatsApp; un correo se le pierde entre las promociones. Se manda además del correo, nunca en su lugar: el correo lleva el desglose, la política y el depósito de garantía; WhatsApp lleva lo que se lee en la pantalla de bloqueo. Si un canal falla, el otro sigue.

Dos cosas que condicionan el diseño:

• Las plantillas las aprueba Meta antes de poder enviarlas, y el texto enviado tiene que coincidir carácter por carácter con el aprobado. Por eso viven escritas en src/modules/notifications/whatsapp.ts en el formato exacto del trámite: ese archivo es lo que se copia a la consola de Meta.
• El número se normaliza en SQL (whatsapp_number), no en la aplicación. El encolado ocurre dentro de la misma transacción que confirma o cancela la reserva, igual que el correo desde el Sprint 3; tener la normalización en los dos lados garantiza que algún día difieran.

Salud y latido

POST /api/jobs/tick es el latido: expira apartados, encola recordatorios, vacía la bandeja de salida y genera las variantes de las fotos. Lo llama un cron cada minuto con la cabecera x-job-secret.

Falla en silencio, y ese es el problema: sin latido nada da error, simplemente los apartados no expiran y los avisos no salen. Por eso el tick deja constancia en la bitácora y GET /api/health responde 503 cuando el último latido tiene más de diez minutos. Las otras cuatro comprobaciones son la base, las migraciones aplicadas, los avisos muertos y los reembolsos pendientes.

La respuesta no lleva secretos y se sirve sin caché, para poder apuntarle un monitoreo externo. Sirve porque puede fallar: la primera vez que respondió 503 destapó tres defectos reales que ninguna prueba cubría (ver docs/sprint-07.md).

robots.txt y sitemap.xml se generan desde la base: el mapa lista un producto por idioma solo si tiene traducción, y robots bloquea /admin y /api.

El panel de operación

Vive en /admin, fuera del árbol de idioma: es una herramienta interna, en español, que no se indexa. El middleware de idioma lo excluye explícitamente —sin esa exclusión el panel responde 307 hacia /es/admin, que no existe, y la operación no puede entrar.

• Se entra con un enlace por correo, no con contraseña. No se guardan contraseñas: un operador chico no tiene cómo responder a una filtración, y la mejor forma de no tener ese problema es no tener el dato. De enlace y sesión solo se guarda el hash.
• La sesión vive en la base, no solo en una cookie firmada, porque una cookie firmada no se puede revocar y aquí hace falta cerrarle el acceso a alguien el mismo día que se va.
• Los permisos se resuelven en el servidor. Ocultar un botón no es un permiso: cada acción vuelve a preguntar quién la pide.
• Está diseñado móvil primero —tarjetas en vez de tablas, 44 px de alto en todo lo que se toca, teléfonos como enlaces tel:— por un supuesto declarado: recepción lo opera desde el celular. Un panel pensado para el celular funciona en un escritorio; al revés no.

Las fotos

Se generan al subir, no al leer: anchos de 400, 800, 1600 y 2400 px en AVIF con respaldo en WebP, y la vitrina emite <picture> con srcset. El porqué está en docs/decisiones/0001-entrega-de-imagenes.md: se paga almacenamiento, que crece con el catálogo, en lugar de cómputo, que crece con el tráfico justo cuando el negocio va bien.

Dos cosas que no son obvias:

• Viven fuera de public/ (en var/media por omisión, configurable con MEDIA_DIR) y se sirven por src/app/media/[...path]/route.ts. Next resuelve el contenido de public/ en tiempo de compilación, así que una foto escrita ahí después del build responde 404 hasta el siguiente despliegue. En producción esa ruta la reemplaza el CDN sobre el mismo almacén, sin cambiar las URL.
• Las variantes las genera el latido, no la petición del panel. Codificar AVIF tarda segundos por imagen; quince fotos serían ciento veinte codificaciones y una pantalla colgada. La foto se ve en cuanto se sube; los tamaños llegan después.

Convenciones

• Identificadores en inglés, comentarios en español.
• Todo monto es un entero en centavos (bigint) con su moneda explícita. Nunca decimales flotantes.
• Las noches son date (una noche no es un instante); las salidas de tours son timestamptz. La zona viene de locations.timezone, no del servidor: Quintana Roo es America/Cancun (UTC−5, sin horario de verano).
• Liberar inventario es un UPDATE de released_at, nunca un DELETE.