UNIVERZOO · Sistema de Recordatorios de Vacunación
Sistema web para la clínica veterinaria UNIVERZOO: registra propietarios, mascotas
y vacunaciones, y envía recordatorios automáticos por WhatsApp usando una fecha de
próxima vacunación ingresada manualmente (nunca calculada por el sistema).
Arquitectura y stack
Decisiones tomadas y por qué:
- Next.js 16 (App Router) + TypeScript, todo en un solo proyecto. Un único
framework full-stack (frontend + backend vía Server Actions y Route Handlers)
reduce la superficie a mantener para un equipo chico, sin sacrificar
escalabilidad (se puede desplegar en cualquier host Node.js o Docker).
- Prisma ORM 7 + PostgreSQL (Neon, vía Vercel). Conexión por WebSocket
(
@prisma/adapter-neon + ws, configurado en src/lib/db.ts) para poder
usar transacciones — la variante HTTP del driver de Neon no las soporta y
algunas operaciones de Prisma (como upsert) las requieren internamente.
El CLI de Prisma (migraciones) usa la conexión directa
(DATABASE_URL_UNPOOLED) en vez de la pooled, porque las operaciones de
esquema no son compatibles con el pooler (pgbouncer).
- Autenticación propia (bcrypt + JWT en cookie httpOnly), sin librerías de
terceros para auth. Next.js 16 es muy reciente; se evitó
next-auth
(todavía en beta) para no depender de una librería que podría no estar
alineada con la versión de Next. La sesión es un JWT firmado (jose) en una
cookie httpOnly + secure en producción, verificado en src/proxy.ts
(el archivo que reemplazó a middleware.ts desde Next.js 16).
- Roles: ADMINISTRADOR, VETERINARIO, RECEPCIÓN, con permisos verificados
tanto en la navegación (
proxy.ts) como dentro de cada Server Action
(defensa en profundidad).
- Motor de recordatorios como proceso independiente (
scripts/run-reminders.ts),
pensado para ejecutarse vía cron / Programador de tareas de Windows, no
depende de que alguien tenga el navegador abierto. También existe un Route
Handler (/api/cron/reminders, protegido con CRON_SECRET) para
integrarlo con schedulers HTTP externos si se despliega en un host serverless.
- WhatsApp Business Platform (Meta Cloud API) vía
fetch, sin
automatización no oficial ni WhatsApp Web. Las credenciales viven únicamente
en variables de entorno del servidor (src/lib/whatsapp.ts), nunca en el
frontend.
- Zod para validar toda entrada de formularios/Server Actions.
- Tailwind CSS v4 con la paleta de marca (naranja
#F78620 / marrón
#4D403A, extraída del logo) definida como tokens en src/app/globals.css.
Puesta en marcha
npm install
npm run db:migrate # aplica prisma/migrations contra DATABASE_URL_UNPOOLED
npm run db:seed # usuario admin + catálogo de vacunas + plantillas
npm run dev
Por defecto el seed crea el usuario [email protected] / Univerzoo2026!
(cambiala apenas entres). Podés fijar tus propias credenciales iniciales con
SEED_ADMIN_EMAIL y SEED_ADMIN_PASSWORD. Para incluir además datos de
ejemplo (propietario/mascota ficticios, solo útil en desarrollo local), corré
el seed con SEED_DEMO_DATA=true.
Producción (Vercel + Neon)
El proyecto está desplegado en Vercel, con Postgres provisto por la
integración Neon del propio dashboard de Vercel (Storage → Create Database).
Pasos completos en DEPLOY.md.
Cambiar esta contraseña / crear usuarios reales antes de usar en producción
desde Usuarios (solo Administrador).
Variables de entorno (.env)
Ver .env.example. Las más importantes:
DATABASE_URL: cadena de conexión (file:./dev.db en desarrollo).AUTH_SECRET: secreto para firmar las sesiones. Cambiar en producción.CRON_SECRET: secreto para invocar /api/cron/reminders por HTTP.WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID,
WHATSAPP_BUSINESS_ACCOUNT_ID, WHATSAPP_VERIFY_TOKEN: credenciales de
WhatsApp Business Platform (Meta). Sin estas variables, el sistema sigue
funcionando: genera y registra los recordatorios pendientes, pero cada envío
queda marcado como Error: Integración de WhatsApp no configurada, visible
en Mensajes.
Motor de recordatorios (ejecución diaria)
npm run reminders:run
Programarlo en el sistema operativo:
- Windows: Programador de tareas → acción "Iniciar un programa" →
npm.cmd con argumentos run reminders:run, directorio de inicio la carpeta
del proyecto, frecuencia diaria.
- Linux: cron, ej.
0 8 * * * cd /ruta/al/proyecto && npm run reminders:run.
- Alternativa HTTP (hosting sin acceso a cron del SO):
POST /api/cron/reminders con header Authorization: Bearer <CRON_SECRET>.
Plantillas de WhatsApp
Las plantillas (Configuración → Plantillas de WhatsApp) definen el texto
interno (para el registro/auditoría) y el nombre exacto de la plantilla
aprobada en WhatsApp Business Manager — WhatsApp exige plantillas
pre-aprobadas para mensajes iniciados por el negocio, así que ese nombre debe
coincidir con lo dado de alta en Meta.
Etapas de desarrollo (según el documento de requerimientos)
- Proyecto base, autenticación, base de datos — hecho
- Propietarios (CRUD, búsqueda) — hecho
- Mascotas (CRUD, ficha completa) — hecho
- Vacunas (catálogo) + Vacunaciones (registro, fecha manual, historial) — hecho
- Dashboard + estados (Al día / Próxima / Vence hoy / Vencida) — hecho
- Motor automático de recordatorios (dedupe por vacunación+etapa) — hecho
- Integración WhatsApp Cloud API (envío + webhook de respuestas) — hecho
- Plantillas + registro de mensajes + reintento manual — hecho
- Reportes (vacunaciones, vencimientos, WhatsApp) + exportación CSV — hecho
- Auditoría + seguridad (bcrypt, roles, proxy, validación) — hecho
Funciones explícitamente fuera del MVP (dejadas preparadas en la arquitectura
para el futuro, sin construir): agenda de turnos, historia clínica,
facturación, farmacia, portal del propietario, chat automatizado, múltiples
sucursales.
Estructura del proyecto
prisma/schema.prisma Modelo de datos completo (11 tablas)
prisma/seed.ts Datos iniciales (admin, catálogo, ejemplo)
scripts/run-reminders.ts Motor de recordatorios como proceso standalone
src/lib/ Lógica de negocio (auth, whatsapp, reminders, status...)
src/app/(app)/ Páginas protegidas (dashboard, propietarios, mascotas...)
src/app/login/ Login (público)
src/app/api/ Webhook de WhatsApp, cron HTTP, exportación CSV
src/proxy.ts Protección de rutas (reemplaza a middleware.ts en Next 16)
Notas para producción
- Cambiar la contraseña del usuario admin apenas entres por primera vez.
- Neon (plan gratuito) hace backups/point-in-time recovery automáticos por
varios días; para retención más larga, considerar un plan pago.
- Dar de alta las plantillas de WhatsApp en Meta Business Manager antes de
activar el motor de recordatorios en producción.
