# Visión General Resumen funcional y arquitectura general del plugin de citas. # Resumen del Plugin El plugin `com.cdsoftware.appointment` agrega a iDempiere 12 un módulo reutilizable para gestionar citas, servicios, empleados, horarios, días no disponibles y disponibilidad de agenda. > **Idea clave:** la disponibilidad no depende solo de la interfaz. La validación queda centralizada en backend para proteger tanto las citas creadas desde ventanas iDempiere como las creadas desde REST/API. ## Objetivo El objetivo es permitir que una organización configure servicios agendables, defina qué empleados pueden atender cada servicio, establezca horarios de atención y bloquee días o rangos no disponibles. Con esa información, el sistema genera slots disponibles y valida cada cita antes de guardarla. ## Alcance funcional

Área	Qué cubre
Configuración	Parámetros generales por organización, límites de anticipación, reglas de aprobación e intervalos de slots.
Servicios	Servicios agendables con precio, duración, intervalo, capacidad y requerimiento de aprobación.
Empleados	Personas o usuarios disponibles para atender citas, vinculados a terceros y opcionalmente a usuarios iDempiere.
Disponibilidad	Horarios semanales, días libres de empleado, días libres de organización y validación de conflictos.
Citas	Registro principal de la cita con cliente, empleado, servicio, fecha, hora, duración, precio, estado y slot seleccionado.

## Principios de diseño - El plugin es genérico y no depende del proyecto IEA. - La creación desde REST/API usa la tabla estándar `CDS_Appointment`. - Las reglas críticas se validan en eventos de modelo, no solo en callouts. - Los modelos generados `I_CDS_*` y `X_CDS_*` son la fuente de constantes de tabla, columnas y valores. - El campo `R_Request_ID` puede existir como referencia manual, pero el código del plugin no depende de solicitudes. # Arquitectura y Componentes La arquitectura del plugin separa la definición de modelos, la disponibilidad, la experiencia de ventana iDempiere y la validación obligatoria antes de guardar citas. ## Componentes principales

Componente	Responsabilidad
`AppointmentAvailabilityEngine`	Centraliza cálculo de disponibilidad, validación de horarios, días libres, conflictos y generación de slots.
`AppointmentModelValidator`	Valida citas antes de crear o modificar registros, incluyendo consistencia del slot y conflictos de agenda.
`CalloutAppointment`	Apoya la captura en ventana iDempiere copiando precio, duración, empleado y horas desde servicio o slot.
`GenerateAppointmentSlots`	Genera registros `CDS_AppointmentSlot` para un empleado, servicio y fecha específicos.
`ReopenAppointment`	Permite reabrir una cita procesada de forma controlada.

## Flujo general 1. El usuario configura servicios, empleados, capacidades, horarios y días no disponibles. 2. Desde una cita se selecciona empleado, servicio y fecha. 3. El proceso de generación crea slots disponibles para esa combinación. 4. El usuario selecciona un slot y el callout copia datos a la cita. 5. Al guardar, el evento valida disponibilidad, consistencia y conflictos. 6. Los clientes REST/API pueden crear la cita directamente y reciben la misma validación por evento.

**Nota:** los callouts mejoran la experiencia de captura, pero no son la capa de seguridad. La regla final vive en `AppointmentModelValidator`.

# Flujo de Configuración y Cita Esta página describe el flujo objetivo para preparar una agenda y poder crear citas válidas. El flujo parte de una configuración general, continúa con servicios y empleados, y termina con la creación de una cita validada por backend.

**Importante:** parte de este flujo representa el comportamiento objetivo. Algunas reglas todavía deben implementarse en el modelo y en `AppointmentModelValidator` para que sean obligatorias tanto desde la UI como desde REST/API.

## Flujo objetivo

## Secuencia funcional 1. Crear una configuración de agenda por organización o por alcance operativo. 2. Definir reglas generales como anticipación mínima, anticipación máxima, regla de asignación y política de aprobación. 3. Definir el horario macro de la agenda. Por ejemplo: lunes a viernes de 8:00 a 17:00. 4. Relacionar cada servicio con una sola configuración de agenda. 5. Configurar cada servicio con duración, precio, intervalo de slot y si requiere aprobación. 6. Configurar empleados y definir qué servicios puede atender cada uno. 7. Definir horario laboral y días libres del empleado. 8. Crear la cita seleccionando empleado, servicio, fecha y slot. 9. Validar primero la configuración de agenda y luego las reglas del empleado. 10. Guardar la cita como pendiente o aprobada según las reglas de aprobación. ## Jerarquía de disponibilidad esperada

Nivel	Regla	Prioridad
Configuración de agenda	Define el marco general de operación: anticipación, días permitidos, horarios macro y aprobación.	Debe estar por encima del empleado. Si la agenda general está cerrada, ningún empleado puede abrir disponibilidad.
Servicio	Define duración, precio, intervalo y si requiere aprobación.	Debe resolver qué configuración aplica.
Empleado	Define servicios que puede atender, horario propio y bloqueos personales.	Solo puede reducir o especializar la disponibilidad de la configuración, no ampliarla.
Cita	Consume empleado, servicio, configuración, slot y reglas de conflicto.	Debe ser validada por evento antes de guardarse.

## Reglas pendientes para completar el flujo - Relacionar cada servicio con una configuración de agenda. - Validar que un servicio no pertenezca a más de una configuración. - Agregar horario macro de configuración, similar al horario del empleado. - Validar anticipación mínima y máxima desde la configuración. - Aplicar la política de aprobación automática o forzada en `BeforeNew`. - Hacer que los días libres de organización puedan aplicar por configuración cuando corresponda.