Saltar al contenido principal

Buscador Público

1. Definición y Propósito​

Permite a pacientes encontrar profesionales de la salud y sedes filtrando por geografía, especialidad y seguro, aplicando Validación Triple para resultados veraces.

2. Lógica Visual y de Procesos​

2.1 Board Miro (referencia visual)​

2.2 Flujo Lógico Canonico​

Resumen textual (fallback)​

  • Entrada: texto libre + filtros (área médica, especialidad, seguro, modalidad, rango geográfico, disponibilidad).
  • Aplica Validación Triple si se selecciona seguro: excluye combinaciones sin convenio/acreditación.
  • Orden por distancia (default) con opción rating/relevancia.
  • Paginación server-side (page/page_size).

Evidencia visual​

  • Fuente canonica: diagrama Mermaid de esta seccion.
  • Si UX adjunta board Miro, se agrega solo como complemento y no reemplaza este flujo contractual.

3. Actores y Permisos (RBAC)​

ActorPermisos
Paciente (Guest/Logueado)Puede buscar y ver resultados; si logueado, personaliza por seguros guardados.
Profesional de la Salud/Entidad de SaludNo accede al buscador público con privilegios especiales.
AdminPuede ver métricas internas (no en este módulo).

4. Reglas de Negocio (BR)​

  • BR-BUS-01: Si se indica insurance_id, solo mostrar resultados con convenio institucional o acreditación del profesional de la salud vigente.
  • BR-BUS-02: Distancia calculada contra lat/lng del usuario o ubicaciones frecuentes si está logueado.
  • BR-BUS-03: Paginación obligatoria; page_size máximo 100.
  • BR-BUS-04: Sin texto libre, el filtro mínimo es geografía o especialidad.
  • BR-BUS-05: Si no hay resultados con seguro, ofrecer fallback “particular” explícito.
  • BR-BUS-06: Permitir filtro area_id (área médica) para casos como Infantil, Salud mental, etc.; si se envía, debe filtrar por especialidades asociadas en area_taxonomy.
  • BR-BUS-07: Filtrar por modality (presencial, domicilio, teleconsulta) y reflejarlo en resultados.
  • BR-BUS-08: Flag urgency=true prioriza entidades con urgencias/24h y próximos horarios disponibles (slot más cercano).
  • BR-BUS-09: Filtro availability (hoy/mañana) requiere consultar affiliations.schedule y/o slots publicados.

5. Endpoints (contrato inicial)​

RecursoMétodoDescripciónRoles
/api/v1/search/entitiesGETBusca sedes por filtros (geo, área, especialidad, modalidad, seguro, disponibilidad, urgencia).Público
/api/v1/search/doctorsGETBusca profesionales de la salud y su sede principal para resultados (geo, área, especialidad, modalidad, seguro, disponibilidad, urgencia).Público

Ver detalles y parámetros en Swagger/OpenAPI (/swagger.html y /openapi.yaml).

6. Resultados y Ordenamiento​

  • Orden default: distancia; alternativos: rating, relevancia.
  • Campos mínimos por item: nombre, tipo (CLINIC/LAB/PHARMACY), distancia_km, rating, área/especialidades, modalidad (presencial/domicilio/tele), seguros soportados, próxima disponibilidad (slot), dirección, flag 24h/urgencias.

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

  • Handlers en interfaces/http/search mapean DTOs a use cases SearchEntities, SearchDoctors en application/search.
  • Repositorios SearchRepo (PostGIS/FTS) y CacheRepo son interfaces; implementaciones en infrastructure/persistence y infrastructure/cache (Redis).
  • DTOs expuestos en OpenAPI son de interfaz; modelos de dominio no arrastran detalles de persistencia.
  • Nomenclatura completa: ver arquitectura-y-despliegue.md §7.1.

7. Métricas y Observabilidad​

  • Tiempo de respuesta P95 < 300ms.
  • Tasa de resultados vacíos por filtro (alertar si >10%).
  • Cache hit ratio en Redis para consultas repetidas.
  • Trazas con trace_id, q, lat, lng, specialty_id, insurance_id.

8. Casos de Borde y Manejo de Errores​

  • Sin filtros mínimos (geo/especialidad) → 422 “Filtros insuficientes”.
  • Seguro sin convenios → mostrar fallback “particular” y registro de evento.
  • Coordenadas fuera de rango válido → 400.
  • Cache miss prolongado → degradar a búsqueda directa en DB y alarmar si latencia supera umbral.

9. Control de Abuso/Fraude​

  • Throttling de búsqueda pública por IP (ej. 60 req/min); captcha si hay scraping.
  • Limitar page_size a 100; evitar deep paging (cap en page máx).
  • Sanitizar texto libre para prevenir inyección en FTS.

10. Checklist de QA / Testing​

  • Búsqueda con especialidad + seguro devuelve solo convenios válidos.
  • Distancia ordena correctamente con lat/lng simulados.
  • Texto libre + filtros combinados no superan 300ms P95 (con caché).
  • Fallback a “particular” cuando no hay convenio.
  • Throttling/captcha se dispara ante ráfagas.
  • Filtro de área (ej. Infantil) restringe resultados a especialidades asociadas.
  • Filtro urgency=true prioriza entidades con urgencias/24h y muestra próximo horario.
  • Filtro modality=domicilio muestra solo sedes/profesionales con esa modalidad.
  • Filtro availability=hoy devuelve solo quien tiene slot hoy.

11. Requerimientos No Funcionales (NFR)​

  • search_p95 < 300ms; disponibilidad 99.9% lectura.
  • Cache hit >80% en queries repetidas.
  • 429 en scraping; no debe impactar usuarios legítimos.

12. Variables de Entorno (Front)​

  • VITE_API_BASE=https://api.example.com/api/v1
  • VITE_SEARCH_MAX_RESULTS=100
  • VITE_SEARCH_ENABLE_CACHE_BUST=false

13. Accesibilidad (A11y)​

  • Campos de búsqueda accesibles con teclado; foco visible.
  • Resultados anunciados con aria-live al terminar la búsqueda.
  • Filtros toggles/select con labels y aria-expanded.

14. Métricas de Producto (Funnel)​

  • Búsqueda → Resultados → Click en resultado → Inicio de cita.
  • CTR por especialidad/seguro; tasa de “sin resultados”.

15. Enlaces y Trazabilidad​

  • Swagger UI: /swagger.html (acceso desde /swagger) y contrato YAML en /openapi.yaml.
  • Relacionados: perfil-profesional-publico.md, mapa-busqueda.md, favoritos.md, agenda-citas.md (usa resultados), admin-catalogos.md (origen de filtros), esquema-de-base-de-datos.md (indices FTS/GIST), arquitectura-y-seguridad.md (observabilidad search).

16. Dependencias​

  • health_entities.location (GIST), doctor_profiles.metadata (FTS), insurance_agreements, doctor_accreditations.