Widget de Próximas Citas

​

¿Qué es el widget de próximas citas?

• Muestra solo citas de hoy (según zona horaria de la clínica)
• Ordenadas por hora de inicio (más próximas primero)
• Incluye nombre del paciente, servicio, proveedor, hora y estado
• Acciones rápidas: Ver detalles, editar, cancelar

​

Columnas de la tabla

​

1. Hora

Ejemplo:
- Cita A: 09:00 - 09:45 (Duración: 45 minutos)
- Cita B: 10:00 - 10:30 (Duración: 30 minutos)

​

2. Paciente

• Si el paciente existe en el sistema, muestra su nombre registrado
• Si es un paciente nuevo (creado vía WhatsApp), muestra el nombre capturado por el bot
• Clickeable: Al hacer clic, abre el perfil del paciente (en desarrollo)

Ejemplo:
- Paciente: "Eduardo Cassanovas García"
- Al hacer clic → Abre modal con historial de citas, teléfono, notas

​

3. Servicio

• Muestra el servicio seleccionado al crear la cita
• Incluye duración implícita (no visible, pero determina end_datetime)
• Si no hay servicio asignado, muestra Sin servicio (raro, pero posible)

Ejemplo:
- Servicio: "Corte de pelo"
- Duración: 30 minutos (configurada en "Servicios")
- Precio: €15 (suma a "Ingresos Estimados" cuando se completa)

​

4. Proveedor

• Muestra el proveedor asignado a la cita
• Si la clínica tiene varios proveedores, ayuda a distribuir carga
• Clickeable: Al hacer clic, filtra citas de ese proveedor (en desarrollo)

​

5. Estado

CONFIRMED → COMPLETED (cuando pasa la hora de fin)
CONFIRMED → CANCELLED (cuando usuario/paciente cancela)
COMPLETED → (final, no cambia)
CANCELLED → (final, no cambia)

​

6. Acciones

​

Ver Detalles

• Icono: 👁️ (ojo)
• Acción: Abre modal con información completa de la cita
• Incluye: Teléfono del paciente, notas, fecha de creación, canal (WhatsApp/Web)

​

Editar

• Icono: ✏️ (lápiz)
• Acción: Permite modificar fecha, hora, servicio o proveedor
• Validación: Verifica disponibilidad del nuevo horario antes de guardar

​

Cancelar

• Icono: 🗑️ (basura)
• Acción: Cambia el estado a CANCELLED
• Confirmación: Muestra diálogo “¿Estás seguro?” antes de cancelar

• Libera el horario para nuevas reservas
• Elimina la cita de “Citas Confirmadas” (contador disminuye)
• NO se puede deshacer (la cita queda marcada como cancelada permanentemente)

​

Ordenamiento y filtros

​

Ordenamiento automático

Ejemplo:
09:00 - 09:30 (Corte de pelo)
10:00 - 10:45 (Tinte)
11:00 - 11:30 (Manicura)

• Si son las 12:00, las citas de 09:00 y 10:00 se muestran con estado COMPLETED
• Permanecen en la tabla hasta la medianoche (útil para revisión del día)

​

Filtros disponibles

• Fecha: Hoy (no se pueden ver citas de otros días desde el Dashboard)
• Clínica: La seleccionada en el menú superior
• Estado: Todos los estados (confirmadas, completadas, canceladas)

​

Actualización en tiempo real

​

¿Cómo se actualiza?

1. Frontend hace petición GET /v1/dashboard/appointments?clinic_id=... cada 5 minutos
2. Backend consulta PostgreSQL con filtro DATE(start_datetime) = TODAY
3. Frontend actualiza la tabla sin refrescar la página

• Nueva cita creada vía WhatsApp → Aparece en 5 minutos
• Usuario edita una cita → Cambios visibles en 5 minutos
• Cita se completa automáticamente → Estado cambia en 1-5 minutos

​

Casos de uso comunes

​

Escenario 1: Verificar próximas citas al llegar

1. Abres el Dashboard a las 09:00
2. El widget muestra:
   • 09:30 - Manuel López (Corte de pelo)
   • 10:00 - Laura García (Tinte)
   • 11:00 - Pedro Martínez (Barba)
3. Acción: Preparas los materiales para el tinte de Laura (requiere tiempo de setup)

​

Escenario 2: Cancelar cita de paciente que no viene

1. Paciente llama a las 10:15: “No puedo ir a mi cita de las 11:00”
2. Abres el Dashboard
3. Buscas la cita de las 11:00 en el widget
4. Haces clic en el botón 🗑️ (Cancelar)
5. Confirmas la cancelación
6. Resultado:
   • Estado cambia a CANCELLED
   • El horario 11:00 queda disponible para nuevas reservas
   • “Citas Confirmadas” disminuye en 1

​

Escenario 3: Editar cita porque paciente llega tarde

1. Paciente envía WhatsApp a las 09:50: “Llegaré 30 minutos tarde”
2. Abres el Dashboard
3. Encuentras la cita de las 10:00
4. Haces clic en ✏️ (Editar)
5. Cambias la hora a 10:30
6. Sistema valida:
   • ¿El slot 10:30 está libre? ✅
   • ¿El proveedor está disponible? ✅
   • ¿La clínica está abierta? ✅
7. Guardas los cambios
8. Resultado: Cita ahora aparece como 10:30 - 11:00

​

Escenario 4: Ver detalles de un paciente recurrente

1. Ves en el widget: 11:00 - Juan Pérez (Corte de pelo)
2. Haces clic en 👁️ (Ver detalles)
3. El modal muestra:
   • Teléfono: +34612345678
   • Notas: “Prefiere corte corto, sin tijera en las patillas”
   • Historial: 5 citas previas (todas completadas)
4. Acción: Preparas la máquina de afeitar (no tijera) antes de que llegue

​

Integración con WhatsApp

​

Citas creadas por el bot

1. Bot captura: Nombre, fecha, hora, servicio
2. Crea la cita en la base de datos con estado CONFIRMED
3. En 5 minutos (máximo), la cita aparece en el widget del Dashboard

[WhatsApp - 10:15]
Paciente: "Quiero una cita mañana a las 16:00"
Bot: "¿Qué servicio necesitas?"
Paciente: "Corte de pelo"
Bot: "Perfecto, ¿cómo te llamas?"
Paciente: "Carlos Ruiz"
Bot: "✅ Cita agendada para mañana 16:00"

[Dashboard - 10:20]
Widget muestra nueva fila:
- Fecha: Mañana
- 16:00 - 16:30
- Carlos Ruiz
- Corte de pelo
- Peluquero 1
- CONFIRMED

​

Cancelaciones vía WhatsApp

1. Paciente: “Cancela mi cita de las 16:00”
2. Bot pregunta: “¿Quieres cancelar o reagendar?”
3. Paciente: “Cancelar”
4. Bot ejecuta cancel_appointment(appointment_id=...)
5. Estado cambia a CANCELLED en la base de datos
6. En 5 minutos, el widget muestra el badge rojo ❌

​

Limitaciones actuales

​

1. Solo muestra citas de HOY

​

2. No permite crear citas

• Vía WhatsApp: El paciente agenda con el bot
• Manualmente: Usa la sección “Citas” → Botón “Nueva Cita”

​

3. No filtra por proveedor

​

4. No muestra citas pasadas de otros días

​

Estados especiales y casos raros

​

Cita creada pero paciente no vino

• Estado: COMPLETED (marcado automáticamente por el job)
• Ingresos estimados: Suma el precio del servicio (€15)
• Problema: El ingreso real fue €0 (paciente no vino)

1. Cancela la cita (cambia a CANCELLED)
2. Esto elimina el ingreso de “Ingresos Estimados”
3. Opcional: Agrega nota en el perfil del paciente (“No se presentó el 15/01/2026”)

​

Cita con servicio eliminado

• La cita sigue existiendo
• Columna “Servicio” muestra: Servicio eliminado (ID: abc-123)
• Puedes editar la cita para cambiar a otro servicio

​

Cita con proveedor suspendido

• Cita sigue apareciendo en el widget
• Columna “Proveedor” muestra: Peluquero 2 (nombre original)
• Puedes reasignar la cita a otro proveedor activo

1. Haz clic en ✏️ (Editar)
2. Cambia el proveedor a “Peluquero 1”
3. Guarda los cambios
4. Sistema valida que “Peluquero 1” esté disponible en ese horario

​

Rendimiento y escalabilidad

​

¿Cuántas citas puede mostrar?

• Clínica abierta: 10:00 - 20:00 (10 horas)
• Duración promedio por cita: 30 minutos
• Citas máximas/día: 10h × 2 citas/h = 20 citas
• Con 3 proveedores: 20 × 3 = 60 citas/día

• El widget mostrará todas, pero con scroll vertical
• Considera usar filtros por proveedor (cuando esté disponible)

​

Impacto en la base de datos

SELECT a.id, a.start_datetime, a.end_datetime, a.status,
       u.full_name AS patient_name,
       s.name AS service_name,
       p.name AS provider_name
FROM appointments a
JOIN users u ON a.patient_id = u.id
JOIN services s ON a.service_id = s.id
JOIN providers p ON a.provider_id = p.id
WHERE a.clinic_id = :clinic_id
  AND DATE(a.start_datetime) = CURRENT_DATE
ORDER BY a.start_datetime ASC;

• Índice compuesto en (clinic_id, start_datetime) → query <10ms
• Cache de 5 minutos → 12 queries/hora (carga mínima)

​

Solución de problemas

​

Las citas no aparecen en el widget

1. Zona horaria incorrecta: La cita está en UTC pero la clínica en Europe/Madrid
   • Solución: Verifica CLINIC_DEFAULT_TZ en configuración
2. Cita creada para otro día: El widget solo muestra HOY
   • Solución: Verifica la fecha en la sección “Citas”
3. Estado cancelado: Las citas canceladas aparecen pero con badge rojo
   • Solución: Verifica el estado en la columna “Estado”

​

El estado no cambia de CONFIRMED a COMPLETED

1. Verifica que el job del scheduler esté corriendo:
   Copy

   curl http://localhost:8000/system/scheduler/status
   
2. Revisa los logs del scheduler:
   Copy

   grep "complete_appointments" /var/log/clinic/app.log
   

• Job pausado: El scheduler no está activo
• Error en la query: Verifica logs de errores en PostgreSQL

​

Editar cita falla con “Horario no disponible”

1. Verifica que el nuevo horario esté dentro de work_hours de la clínica
2. Verifica que el proveedor NO tenga otra cita en ese horario
3. Verifica que NO haya un closure (cierre) en esa fecha/hora

Error: El proveedor "Peluquero 1" no está disponible a las 15:00
Causa: Peluquero 1 solo trabaja de 09:00-13:00 (mañanas)
Solución: Cambia a las 12:00 o elige otro proveedor

​

Próximos pasos