Sistema de Agenda y Reservas Multi-Staff
Plataforma de calendario con verificacion de disponibilidad real, workflow de citas (confirmar/cancelar/no-show/completar), historial de cambios, recordatorios y reportes de ocupacion para negocios de servicios.
El Reto
Una clinica, spa o consultorio con 3-5 profesionales que atienden cada uno multiples servicios sufre el mismo dolor: el calendario en Google Calendar / WhatsApp / cuaderno se desincroniza. Una recepcionista agenda con un staff que estaba de vacaciones, se duplican citas en el mismo slot, los clientes reciben un recordatorio para una cita ya cancelada. Una mala cita por dia x 30 dias = un cliente perdido al mes.
El reto era construir un sistema con verificacion REAL de disponibilidad (no solo 'staff X de 9-18hrs') — considerando: horario base del staff, dias laborales, excepciones (vacaciones, salidas medicas), citas ya agendadas, duracion del servicio, buffer entre citas. Si el staff esta de vacaciones del 1-15, el slot del 5 al 10 no debe aparecer disponible NUNCA.
Adicionalmente: workflow de citas con estados (PROGRAMADA → CONFIRMADA → COMPLETADA / CANCELADA / NO_SHOW), historial inmutable de cambios (quien hizo que y cuando), recordatorios simulados en cola (envio real fuera de scope), reportes de ocupacion / tasa de cancelacion / no-show por staff.
La Solucion
Sistema fullstack en Next.js 14 + Prisma + PostgreSQL 15 con FullCalendar (react + daygrid + timegrid) para la vista principal, date-fns para calculo de slots con manejo de timezone, Auth.js v5 + Argon2 con 4 roles (admin, recepcionista, staff, viewer). Cada rol ve su propia vista del calendario.
Algoritmo de disponibilidad en agenda.service.ts: dado un staff + servicio + fecha, devuelve los slots libres considerando (a) horario base del staff (HorarioStaff por dia de semana), (b) excepciones (ExcepcionStaff con tipo VACACIONES/SALIDA/CAMBIO), (c) citas ya agendadas (Cita.estado != CANCELADA), (d) duracion del Servicio + buffer configurable. Implementacion paso a paso: generar slots cada N minutos del horario base → restar excepciones → restar citas ocupadas → filtrar por duracion suficiente.
Workflow de citas con state machine: PROGRAMADA → CONFIRMADA (recepcion confirma con cliente) → COMPLETADA (staff cierra al terminar) o → CANCELADA (con motivo) o → NO_SHOW. Cada transicion crea CitaEvento con estadoAnterior, estadoNuevo, userId, descripcion. Transiciones invalidas (CONFIRMADA → PROGRAMADA) bloqueadas en service layer.
Features Clave
Verificacion de Disponibilidad Real
Algoritmo considera: horario base + dias laborales + excepciones (vacaciones, salidas) + citas ya agendadas + duracion del servicio + buffer entre citas. Si staff esta de vacaciones del 1-15, slots de esa franja NO aparecen disponibles. Probado con tests unitarios y E2E.
Workflow de Citas con State Machine
Estados: PROGRAMADA → CONFIRMADA → COMPLETADA / CANCELADA / NO_SHOW. Cada transicion crea CitaEvento con userId + timestamp. Transiciones invalidas bloqueadas. Cancelacion requiere motivo (min 10 chars).
Calendario Visual con FullCalendar
Vista semanal por defecto, switch a mensual o lista de dia. Cada cita renderizada con color por estado (azul programada, verde confirmada, gris completada, rojo cancelada, naranja no-show). Click abre detalle con timeline.
Gestion de Horarios + Excepciones
Cada staff tiene HorarioStaff por dia de semana (lunes 9-18, martes 10-17, etc.) + ExcepcionStaff con tipo (VACACIONES, SALIDA_MEDICA, CAMBIO_HORARIO) y rango de fechas. La excepcion sobreescribe el horario base.
Recordatorios en Cola (Simulados)
Tabla Recordatorio con citaId, tipo (24H, 1H), canal (EMAIL, WHATSAPP, SMS), estado (PENDIENTE, ENVIADO, FALLIDO). Daemon recorre PENDIENTES cada 5min y los marca ENVIADO con timestamp. Envio real (Twilio/SES) fuera de scope inicial — la cola queda lista para integrar.
Reportes de Ocupacion y Cancelaciones
Por staff y por rango de fechas: tasa de ocupacion (citas completadas / slots disponibles), tasa de cancelacion (canceladas / total), tasa de no-show, ticket promedio. Exportable a CSV.
4 Roles con Vistas Especializadas
Admin (config + reportes + todo), Recepcionista (agendar + confirmar + cancelar), Staff (su propio calendario, completar/no-show), Viewer (solo lectura). Middleware src/middleware.ts redirige a login si no hay sesion.
Como se Ve
Calendario Semanal con Citas
Vista semanal FullCalendar con citas coloreadas por estado. Hover muestra cliente + servicio + staff. Click abre modal de detalle. Switch entre semanal/mensual/lista.
Formulario de Nueva Cita
Recepcionista selecciona cliente (autocomplete) + servicio (define duracion) + staff. Sistema muestra slots disponibles del staff para los proximos 14 dias considerando todas las restricciones. Click en slot → confirmar.
Detalle de Cita + Timeline
Header con cliente + servicio + staff + estado badge. Botones contextuales segun estado y rol. Timeline con eventos: 'PROGRAMADA por recepcionista', 'CONFIRMADA por recepcionista', 'COMPLETADA por staff'.
Gestion de Horario por Staff
Vista por staff con tabla por dia de semana (horario base) + lista de excepciones (vacaciones, salidas) con rango de fechas + tipo. Botones agregar/editar/eliminar excepcion.
Detalles Tecnicos
| Componente | Tecnologia |
|---|---|
| Framework | Next.js 14 App Router + TypeScript 5 strict |
| Calendario UI | @fullcalendar/react + daygrid + timegrid |
| Fechas + slots | date-fns (timezone-aware, calculo de disponibilidad) |
| ORM + DB | Prisma 5 + PostgreSQL 15 (docker-compose) |
| Auth | Auth.js v5 + Argon2 + 4 roles |
| Validacion | Zod 3 + react-hook-form + resolvers |
| Rate limiting | rate-limiter-flexible + Redis local |
| Reportes | recharts (graficas) + papaparse (CSV) |
| Testing | Vitest unit + integration + Playwright E2E |
| Logging | pino structured |
Resultados
5 (PROGRAMADA / CONFIRMADA / COMPLETADA / CANCELADA / NO_SHOW)
Estados del workflow
4 (admin / recepcionista / staff / viewer)
Roles con vista propia
5 (horario, dias laborales, excepciones, citas, buffer)
Variables de disponibilidad
3 (VACACIONES / SALIDA / CAMBIO)
Tipos de excepcion
3 (EMAIL / WHATSAPP / SMS)
Canales de recordatorio (cola)
Ocupacion + Cancelacion + No-show + Ticket promedio
Reportes incluidos
Servicios relacionados
¿Tu negocio depende del calendario y siguen agendando dos clientes en el mismo slot?
Sistema con verificacion de disponibilidad real, workflow de citas y reportes de ocupacion. Sin doble booking, sin clientes perdidos.