Saltar a contenido

svc-tracking: seguimiento GPS de rutas

svc-tracking es una propuesta de servicio independiente para recibir y consultar puntos GPS de sesiones manuales de ruta de la app móvil del CRM. La app puede capturar en segundo plano sólo durante una ruta activa y dentro del horario autorizado; mantiene las escrituras de alta frecuencia fuera de la base transaccional del CRM y ofrece las rutas como una capa del mapa, sin apropiarse de los datos comerciales.

Estado: documentación propuesta. Los requisitos que confirmó el usuario se distinguen de las decisiones arquitectónicas todavía pendientes de aprobación.

Recomendación de stack — Propuesto

Se recomienda conservar Flutter en el cliente y usar Python + FastAPI para svc-tracking, siguiendo las convenciones existentes de CRM: routers delgados, reglas en servicios de dominio y acceso a datos en repositorios; Poetry, SQLAlchemy 2 asíncrono, asyncpg, Alembic y Pydantic; pruebas con pytest, Ruff y mypy estricto, contrato OpenAPI y pruebas de aislamiento por empresa. No hay mediciones de concurrencia, latencia ni benchmarks que justifiquen Go. Antes de escalar o apartarse del runtime común se deben medir ingestión por lotes y lecturas de rutas con carga y distribución de empresas representativas.

La app debe agregar un módulo de tracking con cliente API y repositorio como frontera de datos, cola local durable/outbox y envío diferido. Se recomienda reutilizar la frontera Drift/SQLite prevista por los ADR móviles 0001, 0003 y 0004, sin introducir otro sistema local ni seleccionar un paquete de ubicación en este documento. La inspección del repositorio Flutter actual encontró sólo el scaffold inicial: pubspec.yaml no instala Drift y todavía no refleja la estructura modular documentada; confirmar y alinear esa base antes de implementar.

Backend lógico propuesto Responsabilidad
app/main.py, app/core/, app/api/ Composición FastAPI, configuración, autenticación/tenancy y dependencias de sesión/transacción.
app/domains/sesiones/ Router HTTP delgado, reglas de ciclo de sesión y repositorio de metadatos mínimos.
app/domains/puntos/ Validación/ingestión de lotes, consulta ordenada por tiempo y repositorio de puntos GPS.
app/infrastructure/mongodb/ Colecciones de sesiones y series temporales de puntos; filtros obligatorios por empresa en cada operación.
tests/unit/, tests/integration/, tests/contract/ Reglas, autorización de servicio, consultas Mongo tenant-scoped, no interferencia entre empresas e invariantes OpenAPI.

Los paquetes son una propuesta lógica alineada con la estructura por dominio, no código ni una decisión de implementación aprobada. Referencias: ADR transversal 0001, 0005, 0016 y 0017; ADR 0001 y 0002 de svc-fuerza-ventas y ADR 0023 de svc-fuerza-ventas.

Módulo móvil propuesto

modules/tracking/
├── api/                 # Cliente tipado del contrato OpenAPI de svc-tracking
├── models/              # Modelos que consumen providers y UI
├── tracking_repository.dart  # Única frontera entre API, Drift y outbox
├── providers/           # Estado de sesión, captura y sincronización
├── local/               # Repositorio/consultas locales si corresponde
├── pages/               # Inicio, estado y cierre de ruta
└── tracking.dart        # API pública del módulo

core/database/           # Drift/SQLite compartido, según ADR móvil 0003
core/sync/               # Despertar y procesar outbox durable

Flujo propuesto: Iniciar ruta → API crea tracking_session_id → captura autorizada → persistencia local → lotes cada dos minutos → vaciado de pendientes → cerrar sesión. Check-in/check-out va de inmediato a la API propietaria de svc-fuerza-ventas, con tracking_session_id como referencia; no se espera al lote GPS.

Diagrama interactivo

El diagrama reúne el ciclo móvil, los contratos ilustrativos y los límites de propiedad. Usa los controles para resaltar una zona o cambiar el tema.

Abrir el diagrama interactivo en una pestaña nueva

El navegador puede mostrar la pestaña nueva como una ventana según su configuración.

Alcance confirmado

  • Un promotor puede usar más de una instalación o dispositivo de la app.
  • El promotor habilita el seguimiento con Iniciar ruta y lo detiene con Finalizar ruta. La app inicia la sesión en la API dedicada de tracking y recibe tracking_session_id. La captura —también en segundo plano o con pantalla bloqueada— sólo ocurre mientras la ruta manual está activa y el servidor determina que el horario laboral está autorizado. No se obtienen puntos nuevos al terminar esa ventana.
  • El muestreo es adaptativo: aproximadamente cada 10 segundos en movimiento y cada 30–60 segundos en reposo. La app conserva puntos en una cola local y envía lotes cada 2 minutos; antes del cierre manual vacía los pendientes. Puntos capturados válidamente dentro del horario pueden cargarse más tarde, incluso fuera de horario: esa carga tardía no autoriza capturar puntos nuevos.
  • empresa_id es obligatorio en cada sesión y punto. La app móvil obtiene el tenant de su contexto autenticado, no de un campo libre. Para consumo servicio-a-servicio, el caller confiable envía empresa_id y svc-tracking autentica/autoriza que ese caller pueda operar para esa empresa; el campo por sí solo no es autorización. Se registran el tiempo del dispositivo y la recepción UTC del servidor. No se confía en el reloj del dispositivo para decidir el horario y la política de tolerancia/desfase queda pendiente.
  • La fuente exacta del horario y su zona horaria siguen abiertas. Permisos denegados, suspensión o terminación del proceso y otros límites del sistema operativo pueden causar huecos; el uso de segundo plano requiere permisos y configuración adecuados y debe validarse en dispositivos reales.
  • La ingestión y el almacenamiento de tracking deben estar aislados del servidor y la base transaccional del CRM: las escrituras de alto volumen de puntos GPS no deben competir con la carga transaccional.
  • Se desea conservar el historial de forma permanente. No se propone TTL ni eliminación automática por defecto.
  • Locales, pedidos y actividades siguen perteneciendo a sus servicios CRM actuales. El mapa debe combinar sus datos mediante APIs, nunca mediante acceso cruzado directo a bases de datos.
  • Todas las operaciones Mongo quedan limitadas a empresa_id autorizado por el servicio; empresa_id es obligatorio en cada sesión y punto y se devuelve en las respuestas. La autorización del caller precede a aplicar el tenant como predicado de servidor.

Recomendación de almacenamiento — Propuesto, pendiente de aprobación: MongoDB time-series para svc-tracking, con sesiones y puntos aislados por empresa_id mediante autorización y predicados obligatorios aplicados por la API. MongoDB no implementa PostgreSQL RLS: ésta es una excepción acotada para tracking a la política transversal aceptada en 0002/0012, que requiere reconciliación y aprobación explícitas, y no modifica esos ADR globales. Si el aislamiento impuesto por la base mediante PostgreSQL RLS es innegociable, la alternativa adecuada es PostgreSQL particionado por tiempo con RLS. MongoDB resulta atractivo para escritura append-heavy y consultas temporales de telemetría; sus controles de tenant son disciplina de aplicación y las colecciones time-series tienen límites de índices únicos/idempotencia. TimescaleDB sigue condicionado a validar versión, privilegios y compatibilidad RLS con columnstore y agregados continuos. Véanse ADR 0005, ADR 0006, ADR 0007 y el historial de ADR 0004.

Vista de arquitectura propuesta

Módulo lógico Responsabilidad
Ciclo de sesiones Abrir y finalizar sesiones de ruta asociadas a empresa_id, promotor e instalación de app.
Ingestión y validación por lotes Validar identidad, sesión, límites del lote, orden y calidad básica antes de aceptar puntos.
Persistencia recomendada MongoDB time-series propuesto para sesiones y puntos, con aislamiento tenant aplicado por la API. Es una excepción de tracking pendiente de aprobación; PostgreSQL con particiones temporales y RLS permanece como opción cuando la garantía de base de datos sea obligatoria.
Consulta de rutas Recuperar puntos por empresa, sesión e intervalo; aplicar límites y orden cronológico.
Autenticación y ámbito de empresa Autenticar al caller servicio-a-servicio, autorizar su acceso a la empresa solicitada y aplicar empresa_id como predicado obligatorio de servidor a cada lectura/escritura/listado/borrado. La app móvil deriva su ámbito del contexto autenticado. Mongo no aporta RLS; la excepción está pendiente de aprobación.
Composición del mapa CRM Consultar rutas por sesión y visitas por tracking_session_id en sus APIs propietarias, dentro del ámbito autorizado de empresa.
Observabilidad Medir recepción, rechazos, duplicados, retraso de ingestión, colas móviles y latencia de consulta.

La separación lógica por esquema o nombre de base no equivale a aislamiento de recursos si se comparte el mismo clúster. La instancia, topología y controles de capacidad deben definirse con el volumen esperado. La recomendación de servicio/instancia dedicada es Propuesta y requiere resolver su encaje con los ADR transversales 0002 y 0003, que establecen una base por producto y documentan dos servicios CRM.

Límites de propiedad de datos

Capa del mapa Propietario Integración propuesta
Metadatos mínimos de sesiones de ruta y puntos GPS svc-tracking API de consulta de rutas.
Locales de clientes svc-clientes API del servicio propietario.
Visitas/check-in/check-out, actividades y pedidos svc-fuerza-ventas API del servicio propietario.

El almacenamiento dedicado de tracking conserva tanto los puntos GPS como los metadatos mínimos necesarios para el ciclo manual de cada ruta: empresa_id, atribución al promotor, instalación de la app, inicio, fin y estado. Cada sesión puede abarcar múltiples visitas. El check-in/check-out se gestiona mediante la API de visitas de svc-fuerza-ventas, que recibe el tracking_session_id activo como referencia de correlación y persiste los datos de visita en su almacenamiento CRM protegido por RLS, junto con su empresa_id. No se duplica el registro de visita en el almacenamiento de tracking. El identificador es una referencia, no una autorización.

La validación de la referencia mediante una lectura servicio-a-servicio de tracking (misma empresa, promotor y sesión activa) es opcional y está pendiente: mejora la validación estricta, pero añade acoplamiento de disponibilidad entre APIs. Si se adopta, debe ser de solo lectura; la API de visitas no escribe la visita en tracking.

La composición consulta puntos por sesión y visitas por tracking_session_id, sin FK entre bases ni join directo. No se agrega visita_id a cada punto GPS; las horas y coordenadas propias del check-in/check-out pueden correlacionarse cuando existan.

Esto no copia datos de negocio del CRM: svc-tracking no replica locales, pedidos ni visitas a su almacenamiento. La composición puede estar en la app o en una fachada/BFF; ese punto queda por definir. En ambos casos cada servicio conserva su autoridad y sus reglas de autorización. La relación propuesta requiere definir compatibilidad para visitas anteriores y para visitas iniciadas sin una sesión de tracking activa.

Captura móvil y volumen inicial

La app está construida con Flutter; esta propuesta no selecciona paquetes ni APIs de implementación de ubicación. El ADR móvil 0014 modifica parcialmente el ADR 0011: mantiene intactas las decisiones de agenda y visitas, y permite tracking en segundo plano sólo dentro de una ruta manual activa y la ventana autorizada. El servidor debe resolver la autorización horaria; la fuente del horario y la zona horaria todavía no están decididas.

El muestreo previsto es de aproximadamente 10 segundos en movimiento y 30–60 segundos en reposo. La captura se detiene al cerrar la ruta o al terminar la ventana laboral. La cola local puede conservar y enviar después puntos capturados válidamente dentro de esa ventana, pero nunca debe generar puntos nuevos fuera de ella. Se registran la hora reportada por el dispositivo y la recepción UTC del servidor; la política de tolerancia frente a desfases o manipulación queda abierta.

La ejecución depende de permisos, configuración y límites propios de cada sistema operativo. Android puede requerir permiso de ubicación en segundo plano y un servicio foreground de ubicación con notificación persistente, según versión/configuración. iOS requiere configurar actualizaciones en segundo plano y la autorización apropiada, con indicación del sistema. La suspensión o terminación del proceso y permisos denegados todavía pueden producir huecos. Deben probarse precisión y consumo de batería en campo; estas restricciones no cambian la regla de no capturar fuera de horario.

Referencias oficiales de plataforma:

Envío por lotes recomendado

Para mapas históricos o de recorrido diario, se conserva cada punto en una cola local y se sube un lote cada 2 minutos (aproximadamente cuatro puntos en reposo; hasta doce con muestreo cada 10 segundos). Frente a una solicitud HTTP por punto, el lote reduce las solicitudes de transporte, a cambio de hasta unos 2 minutos de demora en la frescura del mapa. Es un valor propuesto, no un SLA de tiempo real.

Al finalizar la ruta, la app vacía inmediatamente los puntos pendientes y después cierra la sesión. Si vence el horario autorizado antes del cierre manual, la captura se detiene; los puntos válidos ya capturados pueden subirse luego, mientras que no se admiten puntos nuevos de ese período posterior. El servidor decide si una sesión está dentro del horario: no confía en un reloj libre del dispositivo. Se conserva hora del dispositivo y recepción del servidor para definir una política de validación/tolerancia aún pendiente. El check-in/check-out se envía de inmediato a la API de visitas de svc-fuerza-ventas, sin retenerlo en el lote GPS. empresa_id es obligatorio en cada sesión lógica y punto; la app móvil deriva el ámbito de su contexto autenticado y el API interno consumidor suministra el tenant autorizado. tracking_session_id es sólo una referencia, no autorización.

El lote reduce solicitudes de transporte, no el muestreo del sensor GPS ni la energía que éste consume. La cadencia adaptativa, la precisión y las restricciones de ejecución pueden afectar la batería y requieren validación en campo. La captura en segundo plano está permitida únicamente bajo las condiciones del ADR móvil 0014; límites del sistema operativo, suspensión/terminación o falta de permisos aún pueden dejar huecos.

Convenciones de endpoint verificadas: el ADR móvil 0011 documenta GET /visitas para la agenda, pero no una ruta de check-in/check-out. Por eso el diagrama nombra la operación sin inventar una URL. Las rutas de svc-tracking descritas más abajo siguen siendo contratos ilustrativos, no endpoints aprobados.

Modelo de datos preliminar

Se proponen metadatos de sesión y una colección time-series de puntos GPS. empresa_id es obligatorio en cada sesión lógica y medición; los puntos incluyen metadatos estables device_context.empresa_id y referencias a sesión/promotor, sin FK entre servicios:

tracking_session: tracking_session_id, empresa_id, promoter_id,
                  app_installation_id, started_at, ended_at?, status

location_points (time-series):
  timeField: recorded_at
  metaField: device_context = { empresa_id, app_installation_id }
  measurement/reference: empresa_id, tracking_session_id, promoter_id,
                         device_recorded_at, received_at, latitude, longitude,
                         accuracy_m, speed_mps?, heading_deg?, altitude_m?

Nombres y tipos son ilustrativos. device_context es metadato estable de la serie; sesión y promotor permanecen como referencias/mediciones, no como dimensiones variables del metaField. Debe persistirse empresa_id también en cada documento lógico de sesión y medición. Validar consultas por (device_context.empresa_id, tracking_session_id, recorded_at) para reproducir una ruta y por (device_context.empresa_id, promoter_id, recorded_at) para listar rutas por promotor/período; el plan de índice exacto depende de capacidades y pruebas de la versión de MongoDB elegida.

MongoDB no ofrece RLS de PostgreSQL para documentos de una colección compartida: la separación es aplicación-enforced. La API debe autenticar al caller confiable y autorizar su derecho a la empresa; un campo empresa_id recibido sin identidad/permiso no basta. Rechazar empresa ausente, no autorizada o incompatible con el contexto autenticado; no usar tenant predeterminado ni filtrado en cliente. Incluir empresa_id en toda consulta de lectura, listado, actualización, borrado e inserción; comprobar que la sesión pertenezca a la empresa antes de operar sobre sus puntos. Todas las respuestas incluyen empresa_id junto con los datos. Para la app móvil, el ámbito sale del contexto autenticado y no de un campo libre enviado por la app.

La ruta dibujada sólo requiere obtener latitud/longitud ordenadas por tiempo; PostGIS no es requisito. Agregarlo únicamente si el producto requiere búsquedas espaciales, proximidad o geocercas.

Comparación de almacenamiento — Propuesta

Opción Aislamiento de tenant Ventaja principal Coste o condición
MongoDB time-series empresa_id autorizado y predicado en la API; aislamiento de aplicación, no RLS Modelo orientado a mediciones temporales y escritura append-heavy; se ajusta al límite de tracking y al tenant suministrado por el API consumidor confiable. Riesgo de omisión de filtros; requiere autorización servicio-a-servicio, predicados obligatorios y pruebas de no interferencia. Excepción transversal pendiente. Recomendación propuesta para este límite.
PostgreSQL con particionamiento nativo RLS de PostgreSQL Aislamiento impuesto por la base, más alineado con política, pruebas y operaciones relacionales CRM. Automatizar creación/retirada de particiones, índices y retención; validar carga real. Preferible si RLS de base es requisito no negociable.
TimescaleDB RLS del hypertable, sujeto a privilegios y versión Automatiza chunks, políticas de retención y tareas de serie temporal. Extensión y operación adicionales; el acceso directo concedido a chunks puede eludir la política del padre, y las fuentes/versiones consultadas imponen límites de RLS con columnstore/compresión y agregados continuos. Adoptar sólo tras validar versión, privilegios y necesidad medida.

La misma unidad de servicio almacena únicamente sesiones y puntos GPS. svc-fuerza-ventas conserva visitas/check-in/check-out y almacena tracking_session_id como referencia; svc-clientes conserva clientes/locales. No hay joins, FK entre servicios ni copias comerciales.

Referencias: PostgreSQL RLS, particionamiento, TimescaleDB hypertables y MongoDB time-series, multi-tenant MongoDB.

Contratos ilustrativos

Los siguientes recursos son ejemplos para discutir el contrato, no una API aprobada:

  • POST /api/v1/rutas/sesiones — iniciar una sesión explícitamente; la respuesta entrega tracking_session_id a la app.
  • POST /api/v1/rutas/sesiones/{tracking_session_id}/puntos — ingerir un lote de puntos.
  • POST /api/v1/rutas/sesiones/{tracking_session_id}/finalizacion — finalizar la sesión explícitamente.
  • GET /api/v1/rutas?promotor_id=…&desde=…&hasta=… — consultar rutas para el mapa, siempre bajo el empresa_id autorizado del token.
  • GET /api/v1/rutas/sesiones/{tracking_session_id}/puntos?desde=…&hasta=…&limite=…&cursor=… — consultar los puntos de una sesión dentro de un intervalo explícito.

La API interna consumidora suministra empresa_id; antes de usarlo, tracking autentica al caller y autoriza su derecho a esa empresa. La empresa ausente, no autorizada o incompatible con el contexto autenticado se rechaza. El valor bruto del campo no es autoridad, no existe tenant predeterminado y el cliente nunca filtra resultados. Cada lectura/listado/actualización/borrado aplica empresa_id como predicado obligatorio junto con sesión y rango temporal; cada inserción verifica la pertenencia de la sesión al tenant autorizado. Las respuestas devuelven empresa_id junto con los datos. El tracking_session_id identifica la sesión, pero no autoriza su acceso. Los puntos se devuelven ordenados cronológicamente y con respuesta acotada y paginada; los límites quedan por definir. La app móvil obtiene tenant de su contexto autenticado, no de un campo libre. Para componer visitas, CRM consulta su propia API y su contexto de empresa.

Pendiente de validación

Tema abierto Qué falta acordar o medir
Captura Validar en campo el muestreo adaptativo (aprox. 10 s en movimiento, 30–60 s en reposo), la precisión objetivo y el consumo de batería por plataforma.
Jornada Definir la fuente autoritativa del horario laboral y su zona horaria; establecer tolerancia ante desfase/manipulación comparando hora del dispositivo con recepción del servidor.
Captura en segundo plano Permitida sólo con ruta manual activa y dentro de la ventana laboral autorizada (ADR móvil 0014); confirmar permisos/configuración por sistema y evaluar interrupciones por restricciones o terminación del proceso. Aceptar carga tardía de puntos capturados dentro de la ventana sin permitir nuevas capturas fuera de ella.
Compatibilidad de topología Resolver cómo encaja el nuevo servicio y la instancia/base dedicada con los ADR transversales 0002 («una base por producto») y 0003 (topología CRM de dos servicios); un nombre de base o esquema en el clúster compartido no proporciona aislamiento de recursos.
Capacidad y runtime Medir ingestión por lotes y lecturas tenant/sesión/intervalo con concurrencia y distribución representativas; fijar SLO e índices. Si se elige PostgreSQL/RLS, también definir y medir el intervalo de partición. Sólo cambiar a Go si benchmarks representativos prueban que FastAPI no alcanza el SLO.
Motor y gobernanza Aprobar o rechazar la excepción específica de svc-tracking a la política transversal 0002/0012. MongoDB no implementa RLS: exige controles de aplicación y pruebas de no interferencia. Si RLS de base es obligatorio, elegir PostgreSQL particionado; validar versión y TimescaleDB bajo RLS si se considera.
App local La arquitectura documental prevé Drift/SQLite, pero el repo actual es un scaffold sin Drift; alinear implementación futura sin incorporar otro sistema de persistencia.
Asociación de visitas Definir el contrato de svc-fuerza-ventas para recibir y persistir tracking_session_id, la compatibilidad con visitas históricas o sin sesión activa y si se requiere una validación de solo lectura contra tracking. Esta validación estricta añade acoplamiento de disponibilidad; no está decidida.
Historial Archivo, costos, política de retención y requisitos legales de acceso/privacidad; sin TTL por defecto mientras no se resuelva.
Sesiones y conectividad Recuperación de sesiones abandonadas y límites/expiración de la cola móvil sin conexión.
Lecturas Consultas dominantes, volumen concurrente, intervalo máximo, tamaño de página y SLA de rutas/mapa.

Documentación relacionada