Guía Prysma Sentinel

¿Qué es Prysma Sentinel v2?

Prysma Sentinel es una plataforma de operaciones de campo orientada a misiones críticas: visibilidad de flota en mapa táctico, alertas SOS con contexto, geocercas con reglas por zona, chat persistente por unidad e historial unificado.

La versión 2 integra el ecosistema físico (nodos y gateway LoRa) con el panel SaaS y la app móvil: una sola fuente de verdad para administradores y operarios.

Org ID y primer acceso

Cada organización tiene un identificador (Org ID) que vincula el panel web, la base de datos y la app móvil Sentinel.

En el mapa de flota podés copiar el Org ID desde el control dedicado y pegarlo en la app para que los dispositivos queden asociados a la cuenta correcta.

• No compartas el Org ID públicamente si tu despliegue es sensible; tratá el dato como parte de la configuración operativa.
• Si usás suplantación de organización (solo administración avanzada), verificá siempre qué org está activa antes de editar geocercas o facturación.

Idioma, guía y paleta de comandos

La guía de producto está disponible en español e inglés: usá el selector de idioma o la ruta /es/guide y /en/guide.

Desde el hub de flota podés abrir la guía, el chat y otras vistas desde el menú lateral, el menú hamburguesa o la paleta de comandos (búsqueda rápida de acciones).

Heltec V4 — encendido y vínculo

Los nodos Sentinel se basan en plataformas compatibles con Heltec V4 (radio LoRa, GPS y batería integrada). Tras el encendido, el dispositivo entra en modo de emparejamiento definido por la política de tu organización.

• Cargá el firmware o binario distribuido por Prysma antes del primer despliegue.
• Registrá la organización en el panel y copiá el Org ID en la app móvil Sentinel.
• Acercá el nodo al gateway o a la red mesh según el plan de cobertura acordado.
• Verificá en el mapa táctico que el nodo aparece con estado nominal antes de salir a campo.

HUD y lectura rápida

El mapa usa el estilo Sentinel Dark: fondo oscuro, vías discretas y líneas de malla (mesh) en cian entre el gateway y los nodos visibles.

En las esquinas verás coordenadas del cursor, estado del gateway, nodos activos y un log táctico de eventos recientes.

Colores de los nodos

Los marcadores circulares con anillo animado indican posición en tiempo casi real. Cian: estado nominal. Verde esmeralda: operario en turno (duty on) reportado desde la app. Naranja con pulso acelerado: alerta táctica o SOS simulado para entrenamiento.

Geocercas en el mapa

Las zonas que definís en el estudio de geocercas se dibujan como capas sobre el mapa de flota (según variante: operaciones o restringida). Así ves de un vistazo dónde están las reglas activas mientras seguís unidades.

Cuando una unidad entra o sale de una zona, el sistema puede registrar la transición en el flujo de inteligencia del mapa (mensajes de entrada/salida con nombre de unidad y de zona).

Malla mesh

Las líneas luminosas conectan el hub (gateway) con cada nodo mostrado. No representan enlaces RF medidos en vivo en esta vista; son una guía visual del despliegue lógico hasta que se conecten telemetrías de enlace.

Qué son y para qué sirven

Las geocercas delimitan áreas en el terreno para operaciones o control de acceso. Se guardan por organización y se usan en el mapa web, en la lógica de alertas del panel y en la app móvil (sincronización y avisos en campo).

• Operaciones: zona de trabajo o interés táctico (visibilidad y contexto en el mapa).
• Restringida: zona donde el ingreso del operario debe generar aviso (notificación en la app y seguimiento desde el centro de operaciones).

Crear y editar zonas

Abrí la vista de geocercas desde el menú de flota (ruta /fleet/geofences). Allí podés dibujar geometrías nuevas sobre el mapa, asignar nombre y variante, y guardar los cambios.

Soportamos formas de círculo y polígono según lo que permita el editor: ajustá vértices o radio hasta que la zona refleje el perímetro real.

• Guardá después de cada cambio importante; si ves errores de base de datos, verificá que las migraciones de Supabase estén aplicadas en el entorno que usás (local o nube).
• Renombrá las zonas con criterio operativo (p. ej. perímetro norte, área solo personal autorizado) para que los mensajes en log y en la app sean claros.

App móvil y API

La app obtiene la lista de zonas de tu organización desde el endpoint de geocercas móvil (autenticación con el mismo token JWT que el resto de la API móvil).

La configuración remota (/api/mobile/config) incluye el interruptor features.geofences: si está desactivado, la app no aplica reglas de geocerca aunque existan zonas en el servidor.

Funciones remotas (config)

Al iniciar sesión, la app consulta la configuración del backend para saber qué módulos están habilitados para tu despliegue.

• SOS: si features.sos está desactivado, el flujo de emergencia en la app se oculta o deshabilita según la versión del cliente.
• Geocercas: si features.geofences está activo y concedés permisos de ubicación, la app evalúa la posición respecto de las zonas restringidas y puede mostrar una notificación al ingresar.

Geocercas en campo

Las zonas restringidas están pensadas para avisar al operario en el momento; las de operaciones ayudan al contexto en el mapa del panel.

La evaluación en dispositivo usa la geometría sincronizada del servidor; mantené buena señal GPS y abrí la app al menos una vez con red para refrescar las zonas.

Misiones desde el panel y la app

Los administradores crean misiones por nodo en el hub (drawer de misiones): título, descripción y estado. Al asignar una misión, el operario puede verla en la app móvil en la pestaña Misiones mientras el módulo esté habilitado en la configuración remota.

El operario puede marcar una misión como completada desde el teléfono; el cambio se persiste en Supabase y queda disponible para el equipo en el panel web.

Control de inactividad (Dead Man Switch)

Sentinel vigila el último arreglo GPS válido de cada nodo en base de datos (`last_gps_fix_at`). Cuando llega telemetría sin coordenadas nuevas y el arreglo GPS previo supera el umbral configurado (`SENTINEL_DEAD_MAN_MINUTES`, por defecto 30 minutos), el backend puede registrar un evento de advertencia en el log de flota.

Ese mecanismo actúa como dead man switch operativo: no reemplaza el SOS explícito, pero ayuda a detectar unidades que dejaron de reportar posición durante demasiado tiempo mientras siguen enviando otros datos.

• El umbral es por organización vía variable de entorno en el servidor Next.js.
• Los avisos se deduplican por nodo (~2 h) para no saturar el historial.

Hilos por unidad

El chat de flota (ruta /fleet/chat) concentra la mensajería entre el centro de operaciones y cada nodo identificado.

Los mensajes quedan asociados a la organización y al nodo, lo que permite seguir conversaciones aunque cambie el operario del dispositivo, siempre que el hardware conserve el mismo node id.

• Los administradores envían como admin; los mensajes originados en campo se marcan como node en el historial.
• Usá el chat para coordinación breve; para incidentes críticos seguí además el protocolo de voz y el flujo SOS del panel.

Gestionar un SOS

Cuando un operario dispara SOS desde el dispositivo o desde la app, el panel muestra una alerta de alta prioridad y puede centrar el mapa en la última posición conocida.

Desde el panel de unidad podés revisar identidad, tiempo de última conexión y resolver la alerta táctica cuando corresponda. Las alertas de plataforma pueden acusarse recibo con el flujo de reconocimiento del hub.

• Priorizá la comunicación por voz o protocolo interno antes de cerrar el incidente en software.
• Documentá el cierre en tus procedimientos operativos estándar.

Alertas y eventos por geocerca

En el mapa web, las transiciones de unidades entre dentro y fuera de una geocerca pueden reflejarse en el log táctico y en los textos de inteligencia asociados a la unidad.

En la app, el ingreso a una zona restringida puede disparar una notificación local para el operario; el detalle exacto depende de permisos de ubicación y de la configuración features.geofences.

Perfil, ajustes y equipo

Desde el menú de flota podés abrir tu perfil, los ajustes de la experiencia (tema del mapa, preferencias de UI) y la vista de equipo cuando tu rol lo permita.

Los alias de visualización de nodos ayudan a reconocer unidades por nombre amigable en el mapa y en los paneles; se administran desde los flujos de administración de hardware o alias según tu despliegue.

Facturación y límites de plan

Si tu organización tiene facturación o cupos por plan, el panel puede mostrar avisos sobre estado de pago o uso cercano al límite.

Revisá la sección de facturación en el menú para datos de suscripción y, ante dudas, contactá a soporte con el Org ID y el correo del administrador.

Exportación de datos

Según el plan y los permisos, puede estar disponible la exportación de datos de flota (CSV) desde el hub para análisis externo o archivo.

La retención de historial configurable en el servidor afecta cuánto tiempo quedan disponibles ciertos eventos para exportar o revisar.

Caso SOS: alerta en vivo

Cuando suena una alarma SOS, el centro de operaciones debe actuar en segundos: ubicar al operario, despachar una misión de respuesta y notificar al equipo por los canales acordados.

En el hub web, el mapa puede enfocar la unidad y el panel de detalle muestra contexto reciente. El log táctico registra el incidente para auditoría posterior.

• Ver: abrí el mapa y la ficha de la unidad; confirmá identidad y última posición.
• Despachar misión: desde Misiones asigná una tarea al nodo o a un equipo de respuesta.
• Notificar: usá chat de flota o protocolo de voz según tu SOP; no cierres el incidente en software sin validación operativa.

+-------------+     +-----------------+     +------------------+
   | SOS dispara | --> | Mapa + unidad   | --> | Mision + avisos |
   | (app/nodo)  |     | Ver / focalizar |     | Chat / protocolo |
   +-------------+     +-----------------+     +------------------+
          |                       |
          +-----------+-----------+
                      v
              Log tactico (auditoria)

Caso logística: heatmap y kilometraje

Para optimizar rutas y cobertura, combiná la capa de calor del mapa con los reportes de distancia: el heatmap muestra dónde se concentró la actividad histórica; los informes cuantifican recorridos por ventana de tiempo.

Usá esos datos para reasignar bases, ajustar turnos o validar SLAs con clientes internos.

Actividad GPS historica Informe km / trazas
         |                                |
  +---------------+                +---------------+
  |    Heatmap    | --compare--> | Kilometraje   |
  |   (densidad)  |   tendencias |  por unidad   |
  +---------------+                +---------------+
         |                                |
         +----------------+----------------+
                          v
               Ajuste de rutas y turnos

Caso seguridad: Dead Man Switch (operario solo)

En trabajos aislados, el Dead Man Switch (DMS) exige confirmación periódica de que el operario está bien. Si no hay check-in a tiempo, el sistema puede escalar a supervisores o disparar una misión de bienestar.

Configurá el intervalo y los contactos según el riesgo del sitio; coordiná con el equipo legal y de HSE antes de activar políticas agresivas.

Operario en campo
  +---------------------+
  | Check-in periodico  +---- Temporizador DMS
  +----------+----------+
             |
       a tiempo? ---- no
        | |
        v              v
     Normal        Escalada
                  (alerta / mision)

Datos vivos y KV

El panel se sincroniza con el backend mediante snapshot periódico y, cuando está disponible, streaming de eventos. Los alias de nodos y políticas de retención se aplican del lado servidor.

Si usás el simulador táctico (solo laboratorio), las posiciones se generan en el servidor y se fusionan con los nodos reales para pruebas de UI sin hardware en campo.

Ejecutar la suite de pruebas

Sentinel incluye una suite de pruebas unitarias con Vitest que cubre el motor de ingest (procesamiento GPS, detección SOS) y la lógica SaaS (límite de nodos por plan). Corré las pruebas antes de cualquier deploy para verificar que el pipeline funcione de punta a punta.

• npm test — ejecuta todos los tests en modo run (CI-friendly).
• npm run test:watch — modo interactivo con hot-reload para desarrollo.
• Los tests mockean Supabase y KV; no necesitan servicios externos para pasar.

cd web-dashboard
  npm test

  ✓ Ingest Engine – GPS processing (5 tests)
  ✓ Ingest Engine – SOS alert trigger (4 tests)
  ✓ Ingest Engine – Supabase upsert (2 tests)
  ✓ SaaS plan enforcement – node limit (3 tests)

Logs del sistema (sentinel_system_logs)

Los endpoints críticos de /api/fleet/** están protegidos con un wrapper de error tracking. Cualquier excepción inesperada se registra automáticamente en la tabla sentinel_system_logs de Supabase, incluyendo nivel (info/warn/error/fatal), fuente, mensaje, metadata JSON y stack trace.

Consultá la tabla desde el panel de Supabase o con una query SQL para auditoría del SuperAdmin. Los registros incluyen org_id cuando está disponible para filtrar por organización.

• Nivel error: excepción no manejada en un endpoint fleet.
• Nivel warn: degradación de servicio (Supabase lento, KV timeout).
• Nivel fatal: falla crítica del sistema que requiere intervención.
• Si Supabase no está disponible, los logs se guardan en un buffer de memoria y se imprimen en stderr.

SELECT level, source, message, created_at
  FROM sentinel_system_logs
  WHERE level = 'error'
  ORDER BY created_at DESC
  LIMIT 20;

Health Check avanzado

El endpoint GET /api/health verifica la conectividad con Supabase y el estado de la cola KV/Redis. Devuelve un JSON con el estado de cada servicio, latencia de conexión y el uptime del proceso.

Usá este endpoint en tu monitoreo externo (UptimeRobot, Checkly, etc.) para detectar degradaciones antes de que impacten a los usuarios.

• HTTP 200 + status:ok = todos los servicios saludables.
• HTTP 503 + status:degraded = al menos un servicio caído (revisá supabase.connected y kv.connected en el JSON).