Ciclo de Vida del Evento

Documento tecnico que describe la maquina de estados completa de un evento en Nvito, desde su creacion en borrador hasta su cierre automatico o cancelacion manual. Incluye los actores, las transiciones, los servicios involucrados y los efectos colaterales de cada cambio de estado.

1. Maquina de Estados

Cada evento en Nvito sigue un ciclo de vida estricto con 4 estados posibles. Las transiciones estan controladas por EventLifecycleService y EventSchedulerService, garantizando que ningun cambio de estado ocurra fuera de las reglas definidas.

1.1 Diagrama de Estados

1.2 Descripcion de Estados

2. Transiciones Detalladas

2.1 DRAFT --> ACTIVE (Activacion automatica)

Esta transicion no es manual. Se dispara automaticamente cuando una invitacion del evento es publicada (estado PUBLISHED).

Servicio responsable: EventLifecycleService.activateEventOnPublish(eventId)

Flujo:

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

Validaciones:

• El evento debe existir y pertenecer a la organizacion
• El evento debe estar en estado DRAFT
• Debe haber al menos una invitacion en estado PUBLISHED

Efectos colaterales:

• Se activan los workflows de comunicacion programados
• Los endpoints moviles del evento quedan habilitados
• El EventAccessCode ya esta disponible (se genero en creacion)

2.2 ACTIVE --> COMPLETED (Auto-complete)

Transicion automatica 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 (transicion 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 comunicacion en SCHEDULED se cancelan
• Se dispara el trigger POST_EVENT para workflows configurados

2.3 ACTIVE/DRAFT --> CANCELLED (Cancelacion manual)

Transicion manual iniciada por el organizador.

Endpoint: PATCH /events/:id/cancel

Roles permitidos: OWNER, ADMIN

Flujo:

1. El usuario envia la solicitud de cancelacion
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

Validaciones:

• El evento debe estar en DRAFT o ACTIVE
• El usuario debe tener rol OWNER o ADMIN en la organizacion
• Se registra cancelledAt y cancelledBy

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 notificacion al equipo del evento

3. Creacion del Evento

Al crear un evento, se generan automaticamente varios recursos asociados.

3.1 EventAccessCode

Cada evento recibe un codigo de acceso unico para la app movil.

Uso: El host ingresa el codigo + 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 Creacion

4. Flujo de Publicacion y Activacion

El momento mas importante del ciclo de vida: cuando una invitacion se publica 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 conversion 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. Relacion con Otros Flujos