Reglas de negocio

Regla madre

Cutlyy intenta que cada operacion importante sea valida al mismo tiempo para:

• el negocio
• la agenda
• el cliente
• el equipo
• la capacidad del plan

Por eso una accion aparentemente sencilla puede activar varias validaciones.

1. Reglas de acceso y contexto

Estar logueado no basta

Para entrar al panel privado normalmente se necesita:

• sesion valida
• usuario existente en el sistema
• membresia activa
• rol con permisos suficientes
• contexto activo de negocio

No todas las rutas funcionan igual

Hay rutas:

• publicas, pensadas para clientes
• privadas globales, pensadas para administracion de la plataforma
• privadas del negocio, que solo funcionan cuando ya existe un negocio activo en contexto

2. Reglas de capacidad por plan

Cada negocio opera bajo un plan. Ese plan define limites practicos como:

• numero de empleados
• numero de sedes
• numero de bookings
• numero de roles personalizados

El sistema consume y libera cupos segun las operaciones.

Ejemplos:

• crear una sede consume cupo de sedes
• convertir una membresia en empleado consume cupo de empleados
• crear un booking consume cupo de bookings

Si no hay capacidad disponible, la operacion debe bloquearse.

3. Reglas de estructura del negocio

Sedes

• una sede pertenece a un solo negocio
• su nombre debe ser unico dentro de ese negocio
• no deberia eliminarse si todavia tiene operacion activa relacionada
• no deberia poder cambiar su horario si deja citas activas por fuera del nuevo horario

Servicios

• un servicio pertenece a un solo negocio
• su nombre debe ser unico dentro de ese negocio
• aporta duracion y precio al agendamiento
• no deberia eliminarse si existen citas activas que dependen de el
• no deberia poder inactivarse si existen citas activas que dependen de el

Negocio e identificacion publica

• el nombre del negocio puede repetirse entre negocios distintos
• el slug publico debe seguir siendo unico
• el slug se genera al crear el negocio y luego debe mantenerse estable
• si el nombre ya existe, el slug puede recibir un sufijo corto alfanumerico
• ese slug tambien se usa de cara al usuario como identificador de negocio

4. Reglas sobre personas y equipo

Usuarios

• el documento debe ser unico
• el correo debe ser unico
• una misma persona puede tener relacion con varios negocios mediante membresias distintas

Membresias

• una membresia no puede activarse sin rol
• solo una membresia activa puede operar normalmente
• una membresia inactiva o eliminada pierde validez operativa
• borrar una membresia es una eliminacion logica: queda DELETED, se marca deletedAt y deja de operar
• al borrar una membresia de empleado, el sistema debe proteger citas activas, metricas, reseñas, cupos y asignacion de sede
• un superadmin global puede reactivar su propia membresia admin de negocio si existe una relacion pendiente, inactiva o eliminada para ese negocio

Empleados

• solo una membresia activa puede marcarse como empleado
• solo un empleado activo puede recibir citas
• cambios fuertes sobre empleado o sede deben respetar si existen citas activas asociadas

5. Reglas de agenda

Lo que siempre debe ser valido al agendar

• el negocio existe y esta operativo
• la sede existe y esta habilitada
• el servicio pertenece al negocio y esta activo
• el empleado existe y esta activo
• la fecha y la hora no estan en el pasado
• el horario esta dentro de la agenda de la sede
• no existe traslape con otra cita del mismo empleado

Regla especial de indisponibilidad publica

Si un negocio esta inactivo o su suscripcion no esta operativa:

• el cliente no deberia avanzar en la reserva publica
• la UI deberia mostrar indisponibilidad del negocio sin exponer detalles del plan
• los mensajes tecnicos de plan o suscripcion deben reservarse para usuarios internos

Booking vs appointment

Concepto	Regla base
Booking	Es la reserva como compromiso comercial
Appointment	Es la cita operativa que realmente bloquea agenda

Un booking puede tener una o varias appointments.

6. Reglas de estados

Booking

Estados principales:

• CREATED
• CANCELLED
• FINISHED
• DELETED

Appointment

Estados principales:

• CREATED
• IN_PROGRESS
• CANCELLED
• FINISHED
• DELETED

Regla de sincronizacion

El booking no siempre cambia de estado de inmediato cuando cambia una sola cita. Normalmente solo se sincroniza automaticamente cuando todas sus citas quedan alineadas en un mismo estado compatible.

7. Reglas de pago

El booking concentra la parte economica:

• metodo de pago
• total esperado
• total abonado
• estado de pago

Reglas importantes:

• el abono no puede superar el total
• no se aceptan abonos invalidos sobre bookings cancelados o eliminados
• el estado de pago se recalcula segun el saldo real
• agregar un pago y sobrescribir paidAmount son acciones distintas
• PUT /bookings/:id/paid-amount representa el total pagado final declarado por admin, no un abono incremental

8. Reglas de reseñas

Las reseñas no estan pensadas para cualquier momento del flujo. La regla general es:

• primero ocurre el servicio
• despues se habilita la reseña

Ademas:

• una reseña puede apuntar a sede o a empleado
• si esta ligada a una cita concreta, el sistema evita duplicados para la misma cita
• crear o borrar reseñas modifica promedios y conteos del objetivo evaluado

9. Reglas de eliminacion

En varias entidades la eliminacion es logica, no fisica. Eso significa que el sistema conserva trazabilidad mediante estado o campos como deletedAt.

Esto es importante porque:

• evita perder historial
• protege auditoria operativa
• permite compatibilidad con datos legacy

10. Regla sobre automatizaciones

WhatsApp, push y tareas programadas son importantes, pero se manejan como procesos de apoyo.

En la practica:

• si falla una validacion o la persistencia critica, la operacion debe abortar
• si falla una notificacion o una accion best effort, la reserva principal no necesariamente se revierte

Tabla rapida de decisiones

Tema	El sistema protege que...	Impacto para el negocio
Acceso	Solo entre quien tiene sesion, membresia y permisos validos	Reduce errores y accesos indebidos
Plan	El negocio no supere la capacidad contratada	Evita sobreuso operativo
Agenda	No haya cruces ni horarios imposibles	Protege la experiencia del cliente
Pagos	El booking mantenga saldo coherente	Mejora control financiero
Reseñas	Solo se califique un servicio realmente prestado	Hace confiable la reputacion
Roles	No se pierda control administrativo por accidente	Protege la gobernabilidad del negocio

Documentos relacionados

• Actores y roles
• Ciclo de vida de bookings
• Overview del backend
• Datos y servicios del backend