Saltar al contenido principal

Agenda y Citas

1. Definición y Propósito​

Gestiona la disponibilidad de los profesionales, permite a los pacientes reservar, reagendar o cancelar, y sincroniza recordatorios automáticos (email/SMS/push) para reducir el ausentismo.

  • Contexto: El paciente necesita ver horarios válidos por sede y seguro antes de reservar.
  • Valor de Negocio: Disminuye no‑shows, mejora ocupación de agenda y asegura que cada cita cumple la Validación Triple.

2. Lógica Visual y de Procesos​

2.1 Board Miro (referencia visual)​

2.2 Flujo Lógico Canonico​

2.3 Prototipo de Alta Fidelidad (Figma)​

  • Fuente contractual de flujo: diagrama Mermaid de esta seccion.
  • Fuente de UI: especificacion en Diccionario UX-Tecnico por Pantalla (seccion 5).
  • Si UX publica prototipo en Figma, se referencia como anexo no contractual.

3. Actores y Permisos (RBAC)​

ActorPermisos clave
PacienteBusca disponibilidad, crea/cancela/reagenda sus citas, recibe recordatorios.
Profesional de la Salud (DOCTOR)Define schedules, bloqueos y reglas de duración; acepta/rechaza solicitudes si el modo es “aprobación manual”.
Entidad (Sede)Administra salas/consultorios y límites de capacidad simultánea.
Admin PlataformaFuerza reprogramaciones, ve auditoría de cambios de cita.
Cron/WorkerEnvía recordatorios y marca citas expiradas.

4. Reglas de Negocio (BR)​

  • BR-CIT-01 (Validación Triple): Una cita solo se confirma si doctor_id, entity_id y insurance_id son válidos y están vigentes.
  • BR-CIT-02 (Capacidad): No se permite solapamiento si room_id tiene una cita activa en el mismo intervalo.
  • BR-CIT-03 (Cancelación): Paciente puede cancelar hasta 4h antes; después requiere aprobación del profesional de la salud o entidad.
  • BR-CIT-04 (Reagendar): Reagenda mantiene mismo seguro; si cambia, se revalida la cobertura.
  • BR-CIT-05 (No-show): 2 no‑shows consecutivos bloquean nuevas reservas por 7 días (desbloqueo manual por soporte).
  • BR-CIT-06 (Bloqueos de Agenda): Profesional de Salud puede bloquear franjas por vacaciones/emergencias; no afecta citas ya confirmadas.
  • BR-CIT-07 (Duración): Duración por especialidad; default 30 min, configurable por profesional/sede.

5. Diccionario UX-Técnico por Pantalla (IDs sugeridos)​

ID PantallaObjetivoAcción Técnica
APP-100 Selección de profesional/sedeMostrar slots disponibles filtrados por seguroGET /api/v1/availability
APP-200 Confirmar citaReservar slot y aplicar Validación TriplePOST /api/v1/appointments
APP-300 Resumen/CancelaciónMostrar info de cita y permitir cancelar/reagendarPATCH /api/v1/appointments/{id}

6. Endpoints Propuestos (contrato inicial)​

RecursoMétodoDescripciónRoles
/api/v1/availabilityGETSlots por profesional/sede/seguro/rango fechas.PACIENTE, DOCTOR
/api/v1/appointmentsGETListar citas por rol/estado/rango.PACIENTE, DOCTOR
/api/v1/appointmentsPOSTCrear cita pendiente/confirmada.PACIENTE
/api/v1/appointments/{id}PATCHCancelar, confirmar, reagendar.PACIENTE, DOCTOR, ENTITY_ADMIN
/api/v1/appointments/{id}GETDetalle de cita.PACIENTE, DOCTOR, ENTITY_ADMIN
/api/v1/appointments/{id}/evidencePOSTAdjuntar comprobante (para reseñas o seguros).PACIENTE, ENTITY_ADMIN

Campos mínimos POST /api/v1/appointments:

  • doctor_id (string), entity_id (uuid), insurance_id (uuid, opcional si particular), slot_start (ISO 8601), slot_end (ISO 8601), reason (string opcional).

Implementación Backend (Go, DDD + Clean Architecture):

  • Handlers en interfaces/http/appointments mapean DTOs a use cases GetAvailability, CreateAppointment, UpdateAppointment.
  • Repositorios AvailabilityRepo, AppointmentRepo, ValidationRepo como interfaces en domain/application; implementación en infrastructure/persistence (Postgres) y infrastructure/cache (Redis).
  • DTOs de OpenAPI son de interfaz; entidades de dominio permanecen aisladas. - Nomenclatura completa: ver arquitectura-y-despliegue.md §7.1.

7. Eventos y Notificaciones​

  • appointment_created → email/SMS/push a paciente y profesional de la salud.
  • appointment_rescheduled → aviso con nuevo horario y delta de tiempo.
  • appointment_cancelled → liberar slot; si <4h dispara alerta de penalización.
  • appointment_reminder → T‑24h y T‑2h por cron/worker.

8. Auditoría​

Cada cambio de estado de cita genera un registro en audit_logs con trace_id, actor_id, old_status, new_status, ip_address.

9. Dependencias Técnicas​

  • affiliations.schedule para disponibilidad base.
  • insurance_agreements y doctor_accreditations para validar cobertura.
  • file_assets para adjuntos de evidencia.

10. Requerimientos No Funcionales (NFR) y SLIs/SLOs​

MétricaSLOAlerta
availability_p95< 300msWarn > 400ms 5m
appointment_create_p95< 400msWarn > 500ms 5m
double_booking_rate0% (bloqueado por constraint)Crit si >0
noshow_rate< 5% mensualWarn > 7%
reminder_success> 98%Warn < 95%
cancellation_<4h_rate< 10%Warn > 15%

10.1 Ejemplos de Requests/Responses​

  • Crear cita (POST /api/v1/appointments)
    Request: { "patient_id":"uuid", "doctor_id":"12345", "entity_id":"uuid-entity", "slot_start":"2026-03-01T14:00:00Z", "slot_end":"2026-03-01T14:30:00Z" }
    201: { "id":"uuid-cita", "status":"PENDING" }
    409: { "message":"Slot no disponible" }
  • Disponibilidad (GET /api/v1/availability)
    Params: doctor_id, entity_id, from, to
    200: { "slots":[{"start":"...","end":"...","is_available":true}] }

10.2 Observabilidad​

  • Logs/trazas con trace_id, appointment_id, doctor_id, entity_id, patient_id.
  • Métricas de colas de recordatorios: queue_depth, dlq_depth, processing_latency.

11. Checklist de Seguridad​

  • Validación Triple obligatoria antes de confirmar.
  • Constraint única para evitar double booking (slot_start/slot_end/room_id).
  • Rate limit creación/cancelación por IP/usuario; captcha adaptativo si hay abuso.
  • Tokens JWT con rol; pacientes solo pueden cancelar citas propias.
  • Sanitizar/validar reason y adjuntos (extensión, peso).

12. Casos de Borde y Manejo de Errores​

  • Slot caducado entre selección y POST → 409 “Slot no disponible”.
  • Reagendar hacia una entidad no cubierta por seguro → 422 “Seguro no cubre la sede”.
  • Cancelación menor a 4h → 403 con mensaje y opción de solicitud a soporte.
  • No-show marcado por worker → cambia estado a NOSHOW, genera penalización.

13. Checklist de QA / Testing​

  • Crear cita con Validación Triple exitosa.
  • Intento de doble booking mismo room/intervalo → 409.
  • Reagendar cambia horario y mantiene cobertura; 422 si seguro no aplica.
  • Cancelación menor a 4h rechazada; mayor o igual a 4h aceptada.
  • Recordatorios: se envían T‑24h y T‑2h; DLQ vacío.
  • Auditoría registra cada transición de estado.

14. Variables de Entorno (Front)​

  • VITE_API_BASE=https://api.example.com/api/v1 (prod)
  • VITE_API_BASE=http://localhost:8080/api/v1 (local)
  • VITE_APPT_FEATURE_FLAGS=... (para toggles de no-show, aprobaciones)

15. Accesibilidad (A11y)​

  • Calendario navegable con teclado; foco visible.
  • Estados de error en reservas con texto y aria-live.
  • Confirmaciones/cancelaciones accesibles (botones con labels claros).

16. Control de Abuso/Fraude​

  • Rate limit de creación y cancelación; captcha si >N intentos fallidos.
  • Detección de scraping de disponibilidad (múltiples queries por segundo) → throttling.
  • Bloqueo temporal por no-shows repetidos (BR-CIT-05).

17. Fallback de Notificaciones​

  • Reintentos exponenciales; si falla canal primario (email), usar SMS cuando el usuario lo tenga habilitado.
  • Alertar a soporte si reminder_success cae por debajo de 95 % en 15 min.

18. Métricas de Producto (Funnel)​

  • Búsqueda de disponibilidad → selección de slot → cita creada → recordatorio entregado → cita atendida.
  • Tasa de no-show, tasa de cancelación menor a 4h, conversión disponibilidad→cita.

19. Enlaces y Trazabilidad​

  • Swagger UI: /swagger.html (acceso desde /swagger) y contrato YAML en /openapi.yaml.
  • Relacionados: buscador.md, perfil-profesional-publico.md, checkout-pagos.md, cupones-promociones.md, esquema-de-base-de-datos.md (tablas availability, appointments), notificaciones.md (recordatorios), arquitectura-y-seguridad.md (checklist de observabilidad).