Visión General

• Resumen del Plugin
• Arquitectura y Componentes
• Flujo de Configuración y Cita

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.