Ciclo de vida de bookings y citas
Idea principal
Cutlyy separa la reserva comercial del trabajo operativo:
- el
bookingrepresenta la reserva - la
appointmentrepresenta la cita real en agenda
Eso permite que el negocio tenga control comercial y operativo sin mezclar ambos conceptos.
Flujo de punta a punta
Paso 1. Reserva inicial
La reserva puede empezar desde dos lugares:
- el flujo publico del cliente
- el panel privado del negocio
En ambos casos el sistema valida antes de crear:
- negocio y sede validos
- servicio activo
- empleado habilitado
- horario permitido
- ausencia de cruces en agenda
- capacidad disponible del plan
Si el negocio esta inactivo o con suscripcion no operativa, la reserva publica deberia detenerse desde el inicio con un mensaje de indisponibilidad del negocio.
Paso 2. Nace el booking
Cuando la operacion es valida:
- se crea un booking en estado
CREATED - se crean una o varias appointments en estado
CREATED - se calcula el total economico
- se consumen cupos del plan segun corresponda
Paso 3. La agenda se bloquea
Las appointments son las que realmente ocupan tiempo en el calendario.
Eso significa que:
- la vista operativa del dia depende de ellas
- los conflictos de horario se calculan contra ellas
- mover o cancelar una cita cambia la disponibilidad real
Estados y significado
Estados del booking
| Estado | Significado |
|---|---|
CREATED | La reserva existe y sigue abierta operativamente |
CANCELLED | La reserva ya no se prestara |
FINISHED | El servicio termino |
DELETED | La reserva fue eliminada logicamente |
Estados de la appointment
| Estado | Significado |
|---|---|
CREATED | La cita existe y aun no empieza |
IN_PROGRESS | La cita ya empezo |
CANCELLED | La cita se cancelo |
FINISHED | La cita termino |
DELETED | La cita fue eliminada logicamente |
Paso 4. Cambios durante la vida de la reserva
Reprogramar o editar
Mientras el booking siga en CREATED, normalmente se pueden hacer cambios como:
- ajustar sede
- ajustar cliente
- cambiar metodo de pago
- agregar nuevas citas
- editar citas existentes
- cancelar citas
En la gestion publica del booking existe una regla adicional:
- el cliente puede editar o cancelar citas existentes
- el cliente puede cancelar el booking completo
- el cliente no deberia agregar nuevas citas desde ese flujo
- el backend usa
PUT /bookings/public-manage/:id, no la mutacion privada completa
Cada cambio obliga a recalcular coherencia entre:
- agenda
- total del booking
- estado de pago
- automatizaciones pendientes
Cancelar
Cancelar no es solo cambiar una etiqueta. En la practica puede implicar:
- liberar agenda
- detener tareas programadas
- recalcular estados agregados
- avisar a personas involucradas
Finalizar
Cuando una cita o un booking terminan:
- se actualiza el estado operativo
- se actualizan metricas
- se limpia automatizacion pendiente
- puede habilitarse la etapa de reseñas
Como se sincronizan booking y appointments
Del booking hacia las citas
Si el booking cambia manualmente, el sistema intenta propagar ese cambio a sus citas cuando la regla lo permite.
Ejemplos:
- cancelar booking intenta cancelar sus citas
- finalizar booking intenta finalizar sus citas
De las citas hacia el booking
El booking se sincroniza automaticamente cuando todas sus citas quedan alineadas en un mismo estado compatible.
Si las citas quedan mezcladas, el booking puede conservar su estado anterior.
Diferencia entre cambio comercial y cambio operativo
| Situacion | Impacto comercial | Impacto operativo |
|---|---|---|
| Cambiar pago | Afecta el booking | No necesariamente cambia la agenda |
| Reprogramar cita | Puede afectar total y estado | Si cambia la agenda |
| Cancelar una cita | Puede afectar saldo y estado global | Libera ese bloque de agenda |
| Finalizar una cita | Acerca el booking al cierre | Marca servicio realizado |
Pagos durante el ciclo
El booking guarda:
totalAmountpaidAmountpaymentStatuspaymentMethod
La regla clave es que el total se recalcula usando solo citas vigentes para la operacion. Citas canceladas o eliminadas no deberian seguir pesando igual en el resultado economico.
Hay dos formas de tocar el monto pagado:
- agregar un abono con
POST /bookings/:id/payments - declarar/sobrescribir el total pagado con
PUT /bookings/:id/paid-amount
En edicion privada, paidAmount debe leerse como total pagado final declarado. No es acumulativo y no debe superar el total vigente del booking.
Reseñas al final del flujo
Una vez el servicio termina:
- el cliente puede dejar reseña
- la reseña puede ser para la sede o para el empleado
- el sistema evita duplicados indebidos por cita cuando aplica
Automatizaciones asociadas
Durante este ciclo el backend puede disparar:
- tasks para pasar citas a
IN_PROGRESS - tasks para pasar citas a
FINISHED - mensajes de WhatsApp
- push al equipo
- recalculo de metricas
Caso especial: bookings creados antes del vencimiento del plan
Si un booking ya fue creado y luego el negocio pierde vigencia operativa del plan:
- las citas ya creadas pueden mantener su ciclo de vida operativo
- las tasks programadas y automatizaciones asociadas pueden seguir ejecutandose
- la gestion publica del booking puede seguir permitiendo cancelar o reprogramar citas existentes
- la operacion privada del negocio puede seguir bloqueada por la validacion normal del plan
Casos limite que conviene entender
- una cita finalizada no deberia volver a un estado inicial
- una cita eliminada no deberia restaurarse como si nada hubiera pasado
- si existen citas en estados mixtos, el booking puede no reflejar de inmediato un unico estado global
- una falla de notificacion no siempre invalida la reserva principal
Traduccion simple del flujo
Si una persona no tecnica necesita resumirlo, puede pensarlo asi:
- El cliente hace una reserva.
- El negocio recibe una o varias citas en agenda.
- El equipo las atiende, las mueve o las cancela segun corresponda.
- El sistema recalcula pagos, estado y metricas.
- Al final puede quedar evidencia en forma de reseña.