Saltar a contenido

0003. Composición del mapa mediante APIs propietarias

Fecha: 2026-11-10 Estado: Propuesto Módulo(s) afectado(s): consulta de rutas, composición del mapa, integraciones CRM

Contexto

El mapa móvil necesita mostrar puntos GPS junto con locales, pedidos, actividades y visitas. Los puntos pertenecen al dominio de tracking; los datos comerciales ya tienen servicios CRM propietarios y no deben duplicarse ni consultarse mediante acceso directo a otra base. La composición también necesita una relación explícita para ubicar cada visita en el contexto de una ruta sin acoplar sus bases.

Decisión

Se propone que el check-in/check-out gestionado por la API CRM de visitas de svc-fuerza-ventas reciba el tracking_session_id de la sesión activa como referencia de correlación y persista la visita, con su empresa_id, en el almacenamiento CRM protegido por RLS. Una sesión puede relacionarse con muchas visitas. svc-clientes conserva la propiedad de clientes y locales. La composición obtiene los puntos en svc-tracking por sesión e intervalo; las visitas, actividades y pedidos en la API de svc-fuerza-ventas; y los clientes/locales en la API de svc-clientes, bajo el contexto autorizado de empresa. Como contrato ilustrativo, svc-tracking expone GET /api/v1/rutas/sesiones/{tracking_session_id}/puntos?desde=…&hasta=…&limite=…&cursor=…. El identificador de sesión no autoriza ninguna operación: las APIs deben aplicar sus propias reglas de autorización y ámbito de empresa. No hay FK entre bases, join directo ni copia de documentos CRM a MongoDB; tampoco se agrega visita_id a cada punto GPS. Una fachada/BFF o la app puede coordinar las llamadas, pero su ubicación y el contrato final quedan pendientes.

El vínculo es una propuesta, no un esquema aprobado. Debe definirse cómo mostrar visitas anteriores a su adopción y visitas creadas/ejecutadas sin una sesión de tracking activa; las horas y coordenadas de check-in/check-out pueden correlacionarse cuando estén disponibles, sin reemplazar la relación por sesión. La API de visitas podría validar la referencia mediante una consulta servicio-a-servicio de solo lectura (misma empresa y promotor, sesión activa). Esa validación estricta queda abierta: mejora la consistencia, pero crea una dependencia de disponibilidad con tracking. El identificador por sí solo no es autorización; la API de visitas no escribe la visita en tracking.

Alternativas descartadas

  • Consultas entre bases desde tracking — acopla disponibilidad y esquema, y elude las fronteras de servicio.
  • Replicar entidades CRM a MongoDB o unir bases directamente — produce copias potencialmente obsoletas, elude la propiedad de datos y acopla los almacenamientos; además, las visitas pertenecen al almacenamiento CRM protegido por RLS.
  • Hacer que tracking sea propietario de todas las capas del mapa — confunde la presentación con la propiedad de negocio.

Consecuencias

Cada servicio conserva autorización y fuente de verdad. La consulta de sesión/puntos y la de visitas deben quedar filtradas por el empresa_id autorizado; el identificador opaco de sesión no sustituye el aislamiento por empresa. El rango consultado y el tamaño de página deben estar acotados; sus límites concretos quedan por definir. La composición debe tolerar errores parciales y coordinar alcance temporal y filtros; su latencia, degradación y SLA se validarán con las consultas reales.


Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.