0002. Sesión manual de ruta e ingestión móvil¶
Fecha: 2026-11-10 Estado: Propuesto Módulo(s) afectado(s): ciclo de sesiones, ingestión, app móvil
Contexto¶
El tracking se requiere durante una ruta iniciada por el promotor y dentro de la jornada autorizada, no como monitoreo permanente. Un promotor puede trabajar con varias instalaciones; además, la app Flutter debe convivir con permisos, batería y conectividad intermitente de Android e iOS.
Decisión¶
El promotor inicia y finaliza cada ruta explícitamente en la app; la API crea la sesión y devuelve tracking_session_id. Sólo se capturan puntos si la ruta manual está activa y el servidor confirma que la jornada está autorizada, incluso en segundo plano. El muestreo es adaptativo: aproximadamente cada 10 s en movimiento y 30–60 s en reposo. Se guardan puntos localmente, se envían lotes cada 2 min y se vacía la cola antes del cierre; pueden cargarse después puntos capturados válidamente dentro de horario, pero no se capturan puntos nuevos fuera de él.
Cada sesión y punto lleva empresa_id, tracking_session_id, promotor e instalación. La app obtiene el tenant de su contexto autenticado y no de un campo libre. Para el API interno consumidor, el caller confiable suministra empresa_id; tracking autentica/autoriza al caller para esa empresa y lo usa como ámbito de servidor. El campo por sí solo nunca autoriza. El servidor también decide el horario permitido: su fuente exacta y zona horaria quedan abiertas. Se registra hora del dispositivo y recepción UTC del servidor, pero no se confía en el reloj del teléfono ni se fija aún una política de tolerancia/manipulación. La precisión, el consumo de batería y la ejecución de plataforma requieren validación; permisos denegados o límites del sistema operativo pueden causar huecos. No se prescriben paquetes Flutter ni APIs de implementación.
La cadencia adaptativa no garantiza ejecución continua. También deben validarse los límites de la cola offline y la recuperación de sesiones abandonadas.
Alternativas descartadas¶
- Captura siempre activa o inicio automático — contradice el alcance de jornada y elimina el control manual confirmado.
- Usar una cadencia fija — no adapta el consumo y el volumen a movimiento y reposo; batería, precisión y ejecución real aún requieren pruebas de campo.
- Identificar una ruta sólo por el promotor — no distingue instalaciones concurrentes o sesiones diferentes.
Consecuencias¶
Una ruta puede incluir múltiples visitas. El check-in/check-out sigue en la API CRM de visitas de svc-fuerza-ventas, que recibe tracking_session_id como referencia y persiste la visita con empresa_id bajo RLS; no se almacena en MongoDB y el identificador no autoriza la operación. La regla de captura en segundo plano modifica parcialmente el ADR 0011 móvil sólo para tracking de ruta; agenda y check-in conservan sus decisiones. Quedan por definir horario/zona horaria, tolerancia temporal, retención local, aplicación y aprobación del aislamiento multi-tenant, recuperación de sesiones interrumpidas y compatibilidad de visitas históricas. Android/iOS pueden interrumpir la captura por permisos o límites del sistema.
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.