Eventos — libro de invitados

Aplicación para gestionar invitados, colaboradores, mesas y pagos de un evento (pensada originalmente para una boda, pero reutilizable para futuros eventos). Empezó como un boceto ("Artifact") en Claude.ai y ahora es una web real: Vite + React, con Supabase (Postgres + Auth) como base de datos compartida entre el anfitrión y sus colaboradores, desplegada en Vercel, con avisos automáticos por email vía Resend.

Este README cubre cómo poner en marcha el proyecto y cómo está organizado. El historial de decisiones, bugs ya resueltos y gotchas conocidos vive en CLAUDE.md — consúltalo antes de tocar nada que suene a "esto ya se intentó una vez".

Cómo está organizado src/

• App.jsx — cascarón: decide qué rol/vista mostrar y reparte lo que de verdad comparten dos o más ventanas (asignar colaborador, panel flotante activo, filtros, motor de invitaciones).
• useLedgerData.js — toda la carga y guardado de datos contra Supabase (RPCs), un persistX/acción por tabla o gesto.
• vistas/ — VistaLogin.jsx, VistaAnfitrion.jsx, VistaColaborador.jsx, y dentro de vistas/anfitrion/ cada ventana flotante del anfitrión en su propio fichero (Colaboradores, Mesas, Cuentas, Avisos, Invitaciones, Configuración, Versiones...).
• components/ — piezas de presentación reutilizadas por más de una vista (ColaboradorCard, MiCuenta, VentanaFlotante/ModalFlotante, Portada, etc.).
• lib/ — funciones puras (formato, validación, cálculos sobre invitados) con sus tests co-localizados (*.test.js).
• theme.js / constants.js — paleta de colores compartida y VERSION_APP.

Poner en marcha el proyecto en local

1. Instala las dependencias:

   npm install
   

2. Copia .env.example a .env y rellena los dos valores con los de tu proyecto de Supabase (Project Settings → API):

   cp .env.example .env
   

3. Arranca el servidor de desarrollo:

   npm run dev
   

4. Antes de dar por bueno cualquier cambio, esta es la red de seguridad real del proyecto:

   npm run lint    # detecta al instante variables no importadas (no-undef)
   npm run build   # detecta imports de módulo equivocado que el lint no ve
   npm test        # funciones puras de lib/ — puede no arrancar en algunos Mac,
                    # ver "Vitest no arranca" en CLAUDE.md; lint+build ya cubren
                    # la mayoría de fallos reales del día a día.
   

Configurar Supabase (una sola vez)

1. Crea un proyecto gratuito en supabase.com.
2. Abre el editor SQL del proyecto (Database → SQL Editor), borra cualquier contenido que hubiera antes en el editor y pega/ejecuta todo el contenido de supabase/schema.sql. Es re-ejecutable de forma segura (usa if not exists/create or replace en todo), así que también es el mismo archivo que se vuelve a pegar cuando se le añade algo nuevo.
3. Copia la Project URL y la clave anon public (Project Settings → API) a tu .env local. Nunca uses ni compartas la clave service_role — esa da acceso total sin restricciones.
4. En Authentication → URL Configuration, pon la "Site URL" real de tu despliegue (por ejemplo https://tu-dominio.com) — los enlaces de confirmación/recuperación de email de Supabase apuntan ahí.
5. En Authentication → Attack Protection, activa "Enable Captcha protection", elige Turnstile como proveedor y pega ahí la Secret Key de Cloudflare Turnstile (la Site Key, pública, va en tu .env como VITE_TURNSTILE_SITE_KEY — ver .env.example). Sitio nuevo gratis en dash.cloudflare.com → Turnstile.
6. Guarda la clave de API de Resend en la tabla config_secretos (usada por la función SQL enviar_email para mandar los avisos automáticos) — ver supabase/schema.sql para el nombre exacto de la fila esperada.

Desplegar (Vercel)

1. Conecta este repositorio de GitHub a un proyecto nuevo en vercel.com (detecta Vite automáticamente).
2. En los ajustes del proyecto en Vercel, añade las mismas dos variables de entorno que en tu .env local (VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY).
3. Cada git push a main despliega una versión nueva automáticamente.

Cómo funciona el acceso

Login real (email + contraseña, Supabase Auth) para el anfitrión y para cada colaborador:

• Cada colaborador crea su propia cuenta desde "Crear cuenta" en la pantalla de login, usando el mismo email con el que ya está dado de alta (el de los avisos) — un trigger en la base de datos (vincular_cuenta_nueva) la enlaza sola comparando ese email; si no coincide con nadie conocido, la cuenta se crea igual pero sin ningún acceso.
• Una vez dentro, el botón "Mi cuenta" (junto a "Cerrar sesión") deja a cualquiera cambiar su propia contraseña o su email de acceso sin tener que cerrar sesión. Si quien cambia el email es un colaborador, ese mismo email pasa a ser también el suyo de avisos automáticos (con aviso visible para el anfitrión en la ventana Colaboradores hasta que lo confirma).
• El aislamiento entre colaboradores se hace cumplir en el propio servidor (las RPC colaborador_* filtran siempre por "authUserId" = auth.uid()), no solo ocultando cosas en pantalla.
• Los tres formularios de login (entrar, crear cuenta, recuperar contraseña) llevan un CAPTCHA (Cloudflare Turnstile) — Supabase Auth no bloquea por sí solo tras varios intentos fallidos de contraseña, así que esto es lo que frena a un script automatizado. Sin VITE_TURNSTILE_SITE_KEY configurada no se exige (útil para desarrollo local).

El enlace-token antiguo (?rol=<secreto>) sigue existiendo solo como plan B para el anfitrión — para colaboradores ya no funciona (retirado tras confirmarse en pruebas en vivo que seguía dando acceso sin sesión real). Guarda ese enlace en un sitio privado: quien lo tenga, tiene acceso total a los datos del evento.

Tablón público de novedades

Página de solo lectura, sin login ni cuenta, en ?tablon=<token> — pensada para compartir UN único enlace en un grupo de WhatsApp "solo lectura" con los ya confirmados, en vez de saturarlo con avisos largos. Muestra fecha/hora/lugar fijos arriba y, debajo, las novedades que escriba el anfitrión (ventana "Novedades"), plegadas por secciones. El enlace vive en su propio secreto (tablon_secreto, tabla cerrada como anfitrion_secreto) — nadie sin él lo encuentra, y es el mismo enlace para todo el grupo (no uno por persona), así que crece solo con el número de confirmados sin que haga falta repartir enlaces nuevos. El tablón avisa con un candado de que el enlace es privado y no debe reenviarse. Un botón "Novedades" en la portada (visible para el anfitrión y para cada colaborador logueado) lleva directo ahí y permite volver sin perder la sesión.

Capa extra opcional: una pregunta con respuesta (configurable en Novedades) que hay que responder antes de ver nada del tablón, ni siquiera la fecha del evento — protege de verdad la propia API, no es solo una pantalla decorativa. Cada dispositivo la recuerda tras la primera vez.

Puede sonar música ambiental de fondo mientras el tablón está abierto (Configuración → Fondo musical, sube uno o varios archivos de audio a Supabase Storage). Un botón flotante la activa: los navegadores bloquean el audio automático sin que la persona interactúe antes con la página, así que nunca suena sola de verdad al cargar.

Al pegar cualquier enlace de esta web en WhatsApp/Facebook aparece una miniatura con imagen (etiquetas og:image estáticas en index.html — el rastreador no ejecuta React, así que no pueden leer datos de la base en tiempo real). La imagen se sube en Configuración → Datos del evento, a un segundo bucket de Storage (og-imagen, nombre de archivo fijo para que la URL nunca cambie).

Avisos automáticos por email

Ya en producción, probado en vivo. Vía Resend, disparado desde la propia base de datos (función SQL enviar_email, llamada fire-and-forget con pg_net — nunca espera de forma bloqueante la respuesta HTTP, ver el porqué en CLAUDE.md):

• Anfitrión asigna un invitado a un colaborador → email a ese colaborador (solo cuando el propio anfitrión lo dispara desde "Avisar ahora", no automático al asignar, para agrupar varias asignaciones en un solo correo).
• Un colaborador completa los datos de todos sus confirmados, o marca todos sus pagos → email automático al anfitrión.
• El anfitrión confirma la recogida de dinero entregado por un colaborador → acuse en PDF adjunto, por email, al propio colaborador.

Backup automático de la base de datos

Backup diario vía GitHub Actions (.github/workflows/backup.yml), también lanzable a mano desde la pestaña Actions. El volcado se guarda como artifact de la ejecución (90 días), nunca commiteado al repositorio (los datos de config_secretos/anfitrion_secreto se excluyen del volcado a propósito). Requiere el secreto de repositorio SUPABASE_DB_URL (cadena de conexión "Session pooler" de Supabase).

Estado del proyecto

• ✅ Web funcionando: datos compartidos vía Supabase, aislamiento real entre colaboradores a nivel de base de datos, despliegue automático.
• ✅ Login real (email + contraseña) para anfitrión y colaboradores, con autorregistro y autogestión de cuenta ("Mi cuenta").
• ✅ Avisos automáticos por email (Resend) en producción y probados en vivo.
• ✅ Backup diario automático de la base de datos.
• ✅ CAPTCHA (Turnstile) en los tres formularios de login.
• ✅ Tablón público de novedades, de solo lectura, sin login — con aviso de privacidad, música ambiental opcional y acceso directo desde la portada para anfitrión/colaborador.
• ✅ Fotos de matrimonio (boda y aniversario) en un cubo cerrado de Storage, con descarga en un solo ZIP para montarlas en la plantilla.
• ✅ Lint, pruebas y build se ejecutan solos en cada subida (.github/workflows/pruebas.yml).
• ✅ Carga por trozos: lo que se descarga al abrir bajó de 1,2 MB a ~530 KB; el PDF, Versiones y las vistas grandes llegan cuando se usan.
• ✅ Registro de errores con Sentry (región UE), sin datos personales: ver src/lib/registroErrores.js.
• ⏳ Pendiente (ver CLAUDE.md para el detalle):
  • probar una restauración real del volcado diario en un proyecto vacío -- un backup sin restauración probada no es un backup;
  • ampliar las pruebas al flujo de login.

Licencia

Proyecto privado. Todos los derechos reservados: el código se publica para poder enseñarlo, no para reutilizarlo sin permiso.

Confirmado por el autor el 2026-09-20.