Ciclo de Vida del Evento

1. Maquina de Estados

Cada evento en Nvito sigue un ciclo de vida estricto con 4 estados en base de datos y 1 estado visual derivado (Expirado). Las transiciones estan controladas por EventLifecycleService y EventSchedulerService, garantizando que ningún cambio de estado ocurra fuera de las reglas definidas.

1.1 Diagrama de Estados

1.2 Descripción de Estados

1.3 Estado Visual Derivado: EXPIRED (Expirado)

El estado Expirado no existe como valor en el enum EventStatus de la base de datos. Es un estado visual calculado en el frontend cuando se cumplen estás condiciones:

• El evento está en COMPLETED y nunca tuvo una invitación publicada (activatedAt === null)
• O la fecha del evento ya paso, no tiene activatedAt, y no está cancelado

Formula en el frontend (EventContext):

isEventExpired = (isEventCompleted && !event.activatedAt)
  || (isEventPast && !event.activatedAt && !isEventCancelled)

Diferencia con COMPLETED: Un evento COMPLETED fue publicado, vivido y finalizado normalmente. Un evento Expirado nunca llego a publicar su invitación — la fecha paso sin que el organizador completara la preparación.

Comportamiento: Mismo bloqueo que COMPLETED y CANCELLED — todas las acciones de modificación deshabilitadas, servicios bloqueados, solo lectura. El dashboard muestra un badge "Expirado" y la tarjeta de estado con icono de advertencia.

2. Transiciones Detalladas

2.1 DRAFT --> ACTIVE (Activación automática)

Esta transición no es manual. Se dispara automáticamente cuando una invitación del evento es publicada (estado PUBLISHED).

Servicio responsable: EventLifecycleService.activateEventOnPublish(eventId)

Flujo:

1. El usuario aprueba la invitación (POST /invitations/:id/approve)
2. ApprovalWorkflowService cambia la invitación a PUBLISHED
3. Se ejecuta EventLifecycleService.activateEventOnPublish(eventId)
4. Si el evento está en DRAFT, transiciona a ACTIVE
5. Si el evento ya está en ACTIVE (otra invitación previa), no hace nada

Validaciones:

• El evento debe existir y pertenecer a la organización
• El evento debe estar en estado DRAFT
• Debe haber al menos una invitación en estado PUBLISHED

Efectos colaterales:

• Se activan los workflows de comunicación programados
• Los endpoints moviles del evento quedan habilitados
• El EventAccessCode ya está disponible (se género en creación)

2.2 ACTIVE --> COMPLETED (Auto-complete)

Transición automática ejecutada por un cron job.

Servicio responsable: EventSchedulerService

Frecuencia: Cada hora (0 * * * *)

Flujo:

1. El cron busca eventos en estado ACTIVE donde endDate es menor o igual a now
2. Para cada evento encontrado:
   • Cambia el estado a COMPLETED
   • Cierra todas las invitaciones en PUBLISHED (transición a CLOSED)
   • Pausa todos los workflows activos
   • Registra completedAt con timestamp

Validaciones:

• Solo eventos en estado ACTIVE
• endDate debe ser menor o igual a now()

Efectos colaterales:

• Invitaciones cerradas (estado CLOSED con closeReason: 'EVENT_COMPLETED')
• Workflows pausados
• Campanas de comunicación en SCHEDULED se cancelan
• Se dispara el trigger POST_EVENT para workflows configurados

2.3 ACTIVE/DRAFT --> CANCELLED (Cancelación manual)

Transición manual iniciada por el organizador.

Endpoint: PATCH /events/:id/cancel

Roles permitidos: OWNER, ADMIN

Flujo:

1. El usuario envia la solicitud de cancelación
2. Se valida que el evento no este ya en COMPLETED o CANCELLED
3. Se cambia el estado a CANCELLED
4. Se ejecutan los efectos colaterales de cierre

Body: cancellationReason (string, obligatorio) — razon de la cancelación que se muestra en el dashboard

Validaciones:

• El evento debe estar en DRAFT o ACTIVE
• El usuario debe tener rol OWNER o ADMIN en la organización
• Se registra cancelledAt, cancelledBy y cancellationReason

Efectos colaterales:

• Todas las invitaciones en UNPUBLISHED o PUBLISHED se cierran (CLOSED con closeReason: 'EVENT_CANCELLED')
• Todos los workflows activos se pausan
• Campanas en SCHEDULED o SENDING se cancelan
• Se envia notificación al equipo del evento

3. Creación del Evento

Al crear un evento, se generan automáticamente varios recursos asociados.

3.1 EventAccessCode

Cada evento recibe un código de acceso único para la app movil.

Uso: El host ingresa el código + PIN en la app movil para acceder como anfitrion del evento. Los invitados acceden via deep link o QR (sin PIN).

3.2 Flujo de Creación

4. Flujo de Publicación y Activación

El momento más importante del ciclo de vida: cuando una invitación se pública y el evento se activa.

5. Actores del Sistema

6. Restricciones y Limites

7. Archivos Clave

8. Diagrama de Flujo Completo

9. Consideraciones de Timezone

• Cron de auto-complete: Ejecuta cada hora en UTC. La comparacion endDate menor o igual a now usa UTC.
• Fechas del evento: Se almacenan en UTC en la base de datos. La conversión a timezone local se hace en el frontend.
• Cierre de invitaciones por evento completado: Usa timezone America/Mexico_City para el cron diario de medianoche que cierra invitaciones de eventos pasados (complementario al cron horario de auto-complete de eventos).

10. Relación con Otros Flujos