Guía técnica · ClinicOS-CRM

Agenda avanzada

Cómo el sistema decide qué huecos ofrecer, cómo configurarlo para tu clínica y cómo se comportan los flujos típicos.

Contenido

1. Las 6 reglas que validan toda cita
2. Cómo el sistema rankea los huecos disponibles
3. Configurar paso a paso (5 mini-guías)
4. Ejemplos por tipo de clínica
5. ¿Qué hago si…? (resolución de problemas)

1. Las 6 reglas que validan toda cita

Cuando el sistema valora si un hueco se puede reservar, comprueba 6 condiciones en orden. Si cualquiera falla, el hueco no se ofrece. Si las 6 pasan, el hueco es válido.

Regla 1 — Servicio ↔ Profesional

El servicio debe estar autorizado para ese profesional. Configurable en: Configuración → Servicios → botón "Especialistas". Si no marcas a nadie, el servicio lo puede hacer cualquier profesional.

Regla 2 — Servicio ↔ Gabinete

El servicio debe estar permitido en ese gabinete. Configurable en: Configuración → Servicios → botón "Cualquier sala". Si no marcas ninguna sala, se permite en cualquiera.

Regla 3 — Profesional disponible

El profesional debe estar dentro de su horario laboral, sin otra cita solapada (con overbooking opcional permite N concurrentes), y sin bloqueo de calendario (vacaciones, baja, etc.).

Regla 4 — Gabinete disponible

El gabinete debe estar activo, dentro de su horario operativo, sin otra cita solapada y sin un bloqueo de mantenimiento. Bloqueos en: Configuración → Gabinetes → botón "Bloqueos".

Regla 5 — Buffers (margen pre/post)

Una cita "ocupa" en realidad [start - pre_buffer, end + post_buffer]. Útil para limpiar instrumental, preparar la sala, etc. Jerarquía: el buffer del servicio gana al del profesional, que gana al de la clínica.

Regla 6 — Equipamiento disponible

Para cada equipo requerido por el servicio:
· Si es fijo → debe estar instalado en el gabinete propuesto.
· Si es móvil → debe estar libre en ese rango (no asignado a otra cita simultánea).
· Si es pool (varios intercambiables) → al menos N miembros libres.

💡 Convención permisiva

Si una clínica todavía no ha configurado nada, el sistema funciona como un calendario simple: cualquier servicio se puede hacer en cualquier sala con cualquier profesional, sin equipos requeridos. A medida que vas marcando restricciones, el sistema las respeta. Empieza simple, añade reglas según las vayas necesitando.

2. Cómo el sistema rankea los huecos

Cuando un paciente busca cita, normalmente hay varios huecos válidos que cumplen las 6 reglas. Para decidir cuáles mostrar primero, el sistema usa una función de optimización con 5 criterios ponderables.

Hueco candidato ↓ ┌───────────────┐ │ ¿Cumple las │ ← regla 1, 2, 3, 4, 5, 6 │ 6 reglas? │ └───────┬───────┘ ↓ (sí) ┌──────────────────┐ │ Calcula score │ │ Σ pesoᵢ · valorᵢ │ └──────────────────┘ ↓ Ordena por score desc (en empate: el más temprano)

Los 5 scorers

Criterio	Qué premia
Proximidad temporal	Huecos más próximos a hoy
Ocupación de agenda	Días ya parcialmente llenos (eficiencia)
Equilibrio de carga	Profesionales con menos carga esa semana
Preferencia del paciente	Match con doctor/sala/franja preferida del paciente
Minimizar huecos muertos	Huecos adyacentes a citas existentes (evita huecos sueltos)

📍 ¿Dónde se ajustan estos pesos?

Configuración → Optimización. Cada peso entre 0 (desactivar) y 5 (manda). Si todos están a 1, todos los criterios se ponderan por igual. Si no sabes qué priorizar, deja todo a 1 — el sistema decide con un balance equilibrado.

3. Mini-guías de configuración

3.1 — Bloquear una sala por mantenimiento

1
Ve a Configuración → Gabinetes.
2
Junto a la sala que quieres bloquear, pulsa el botón Bloqueos.
3
En el panel rojo que se abre, rellena: Desde día / Hora y Hasta día / Hora. Si dejas las horas en 00:00 y 23:59 bloqueas el día completo.
4
Opcional: pon un motivo ("Reforma suelo", "Mantenimiento aire").
5
Pulsa Bloquear. Durante ese rango, ningún paciente podrá reservar esa sala desde el portal y la regla 4 rechaza cualquier cita admin que la intente usar.

3.2 — Crear un pool de equipos intercambiables

Útil si tienes varios equipos idénticos (ej. 3 ecógrafos) y un servicio puede usar cualquiera.

1
Ve a Configuración → Equipamiento.
2
En la sección Pools de equipos, escribe el nombre (ej. "Ecógrafos") y opcionalmente el tipo. Pulsa Añadir pool.
3
Baja a Equipos individuales y crea cada equipo (ej. "Ecógrafo #1", "Ecógrafo #2"…). Selecciona Móvil en movilidad y elige el pool en el dropdown.
4
Para asociarlo al servicio: ve a Configuración → Servicios, edita el servicio (ej. "Punción ecoguiada"), pulsa el botón Sin equipos, marca el pool, y pon cantidad 1 (necesita 1 ecógrafo cualquiera).
5
Guarda. A partir de ahora, si los 3 ecógrafos están ocupados a las 10:00, esa franja desaparece automáticamente de la reserva en línea.

3.3 — Configurar los pesos del optimizer

1
Ve a Configuración → Optimización.
2
Decide tu objetivo principal. Ejemplos:
- · "Llenar la agenda cuanto antes" → Proximidad temporal a 3, resto a 1.
- · "Agrupar citas para tener días libres" → Ocupación de agenda a 3.
- · "Repartir entre profesionales" → Equilibrio de carga a 3.
- · "Respetar lo que pide el paciente" → Preferencia del paciente a 3.
3
Pulsa Guardar pesos. El cambio aplica inmediatamente al siguiente paciente que entre al portal a reservar.

3.4 — Reservar un hueco de urgencia

1
En la agenda (icono 📅 sidebar), pulsa el botón rojo Urgencias arriba a la derecha.
2
En el formulario de abajo, pon: fecha + hora desde, fecha + hora hasta. Profesional y sala son opcionales — déjalos en blanco si quieres bloquear "para lo que sea".
3
Pulsa Reservar hueco. Durante ese rango el portal del paciente NO mostrará esa franja. El hueco queda disponible para que tú asignes manualmente una urgencia.
4
Si al cierre del día el hueco no se ha usado, sale en el reporte diario (cron scripts/report_unused_emergency_slots.php).

3.5 — Poner preferencias a un paciente

1
Abre la ficha del paciente (Pacientes → clic en su nombre).
2
En la pestaña General, baja del todo. Verás una sección rosa colapsable "Preferencias de reserva". Despliégala.
3
Configura lo que aplique: profesional preferido, sala, franja horaria (desde/hasta), días de la semana (botones L M X J V S D — pulsa para activarlos).
4
Pulsa Guardar preferencias. La próxima vez que ese paciente busque hueco, los huecos que coincidan con sus preferencias salen ranqueados primero (si el peso "Preferencia del paciente" en Optimización está > 0).

4. Ejemplos por tipo de clínica

🦷 Clínica DENTAL

Sillón fijo + servicios específicos por profesional

Configuración:

2 gabinetes con su sillón fijo cada uno → en Configuración → Equipamiento creas "Sillón Adec #1" (Fijo en Gabinete 1) y "Sillón Adec #2" (Fijo en Gabinete 2).
Servicio "Endodoncia" → en Configuración → Servicios, edita endodoncia, pulsa "Sin equipos" → marca ambos sillones (cualquiera vale).
Solo los endodoncistas hacen endodoncia → mismo formulario, pulsa "Especialistas" → marca a los 2 endodoncistas de tu equipo.
Necesita 10 min para limpiar instrumental → mismo formulario, campo post-buffer = 10.

Resultado:

Si el paciente reserva endodoncia online y elige al higienista en vez de un endodoncista → la regla 1 lo rechaza, no aparece esa opción.
Si elige Gabinete 1 pero el sillón #1 está libre y el sillón #2 también → cualquier gabinete vale.
Si la cita siguiente del endodoncista empieza 5 min después → la regla 5 rechaza el hueco por buffer insuficiente.

🤸 Clínica FISIOTERAPIA

Sala genérica + equipamiento móvil compartido

Configuración:

1 sala única (o varias intercambiables) → no necesitas restringir servicios a salas, lo dejas vacío.
3 ecógrafos compartidos → en Equipamiento, creas un pool "Ecógrafos" y luego 3 equipos móviles vinculados al pool.
Servicio "Punción ecoguiada" requiere 1 ecógrafo cualquiera → en Servicios, edita el servicio, pulsa "Sin equipos" → marca el pool "Ecógrafos" con cantidad 1.

Resultado:

3 punciones a las 10:00 → todas válidas (3 ecógrafos disponibles).
4ª punción a las 10:00 → la regla 6 rechaza porque solo hay 3 ecógrafos. La franja desaparece del portal.
Punción a las 11:00 con un ecógrafo libre → válida, el sistema asigna automáticamente cuál de los 3 cuando el admin confirma.

👁️ Clínica OFTALMOLOGÍA

Cita encadenada: técnico → médico

Configuración:

Servicio "Prueba con técnico" (15 min) restringido al técnico.
Servicio "Consulta médico" (30 min) restringido al oftalmólogo.
El paciente pasa primero por el técnico y luego por el médico, con una separación de 0 a 30 min.

Estado actual de la UI:

El backend ya soporta cadenas atómicas (App\Core\Scheduling\ChainScheduler) pero la UI de admin para crear paquetes encadenados está pendiente. Como workaround, el admin crea las dos citas manualmente desde la agenda asegurándose de respetar la separación.

5. ¿Qué hago si…?

…un paciente me dice que no ve huecos en el portal.

Comprueba que el servicio tiene marcado 📱 Online en Configuración → Servicios.
Comprueba que al menos un profesional de los autorizados tiene horario laboral en los próximos días.
Si el servicio tiene salas restringidas, comprueba que al menos una de esas salas está activa.
Si el servicio requiere equipo, comprueba que el equipo está activo y que su sala (si fijo) o el pool (si móvil) tiene al menos un miembro disponible.
Mira las preferencias del paciente — si tiene un día/franja muy restrictiva y no hay coincidencias, no verá huecos.

…aparecen huecos donde no debería (ej. servicio en sala equivocada).

Probablemente la restricción de sala/profesional no está configurada — el sistema usa la convención permisiva.
Ve a Configuración → Servicios, edita el servicio, marca expresamente las salas / especialistas autorizados, guarda.

…cancelan una cita y quiero saber si hay alguien en lista de espera.

El sistema lo detecta automáticamente: cuando el paciente cancela desde el portal o tú cancelas desde la agenda, mira el icono de campana 🔔 arriba.
Si había candidatos compatibles en waiting_list, recibirás una notificación en la aplicación "Hueco liberado: X candidatos".
Pulsa la notificación → te lleva a /espera donde puedes reasignar manualmente.

…dos pacientes intentan reservar el mismo hueco a la vez.

El sistema usa transacciones con bloqueo pesimista. Solo uno gana, al otro se le devuelve un error "Hueco no disponible" y se le invita a elegir otro hueco. No hay "doble reserva" posible.

…la web da error 500.

Añade ?_debug=1 al final de la URL para ver el error real en pantalla. Pásaselo a soporte (o a tu desarrollador) para que lo diagnostique.

…la web no carga del todo (timeout).

No es problema del CRM — es el hosting o el proxy (Cloudflare). Ver runbook de operaciones para los pasos de diagnóstico.

ClinicOS-CRM · Guía de Agenda avanzada · Generada para uso interno de las clínicas usuarias.

Documentación técnica detallada: docs/scheduling.md