Manual del Global Hub

◆ ¿Qué es Global Hub?

Middleware de retransmisión GPS. Toma los datos de tus unidades desde la plataforma del proveedor (Protrack/TrackSolid/Wialon), los transforma al formato que cada entidad peruana exige, y los envía en tiempo real.

🏗 Arquitectura

Tres capas: colectores → BD SQLite → transmitters. Cada uno es un servicio systemd independiente.

  ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
  │   PROTRACK     │    │   TRACKSOLID   │    │    WIALON      │
  │  (colector)    │    │   (colector)   │    │   (colector)   │
  └───────┬────────┘    └───────┬────────┘    └───────┬────────┘
          │                     │                     │
          └─────────────────────┼─────────────────────┘
                                ▼
                   ┌──────────────────────────┐
                   │   SQLite + FastAPI       │
                   │   devices + tx_logs      │
                   └─────┬────────────────────┘
                         │
      ┌──────────┬──────┴─────┬─────────┬──────────┐
      ▼          ▼            ▼         ▼          ▼
   SUTRAN   OSINERGMIN     UNIGIS    MAERSK     SIPCOP
(transm)  (transm)       (transm)  (transm)   (pendiente)

Servicios activos

🔑 Ingresar al panel

El Hub requiere autenticación — no hay acceso público. Los usuarios los crea el admin.

1. URL oficial: https://apirest.globalgpsperu.com
2. Alternativa en Piura (WiFi bloquea 443): http://apirest.globalgpsperu.com:8080 — redirige a HTTPS
3. Ingresa usuario y contraseña
4. Al primer login se pide verificar email si aún no se ha hecho

📊 Dashboard

Vista principal del estado de la flota.

Tarjetas principales

Tabla de flota

Lista por unidad con: placa, proveedor (Protrack/TrackSolid/Wialon), coordenadas, velocidad, ignición, destinos activos, última actualización. Filtro por placa arriba.

🚚 Unidades

CRUD de devices. Normalmente se crean automáticamente vía auto-activate desde el CRM, pero también se pueden crear a mano.

Crear unidad manualmente

1. Menú → Unidades → + Nueva unidad
2. IMEI (15 dígitos del chip GSM)
3. Placa con guión (formato peruano XXX-999)
4. Proveedor: Protrack / TrackSolid / Wialon
5. Nombre de la empresa del cliente (va en el campo transport_vendor)
6. Notas opcionales (contacto, observaciones)
7. Guardar → queda active=1, sin destinos activos aún

Editar unidad

Tabla → clic en icono lápiz. Puedes cambiar placa, proveedor, notas, estado activo/inactivo.

Eliminar

📡 Transmisiones

Control de a qué entidades retransmite cada unidad.

Activar transmisión (manual)

1. Menú → Unidades → seleccionar unidad
2. Panel Destinos — 5 toggles (SUTRAN, OSINERGMIN, UNIGIS, MAERSK, SIPCOP)
3. Para SUTRAN: ingresa speed_limit (10-200 km/h). Este valor se aplica realmente — si speed_limit=60, SUTRAN verá máximo 60 km/h aunque el GPS reporte 90.
4. Para OSINERGMIN: asegúrate que la placa tenga guión (el Hub normaliza automáticamente si viene sin guión).
5. Guardar → la próxima iteración del transmitter respectivo (cada 15 seg) envía la trama a la entidad.

Desactivar transmisión

Mismo flujo, toggle a OFF. La trama deja de enviarse inmediatamente.

Auto-activate (desde CRM)

Normalmente NO tocas esto manualmente. Al guardar un cliente con filtros regulatorios en el CRM, este hace POST /api/transmission/auto-activate con IMEI + provider + destino + speed_limit, y el Hub:

1. Verifica que la unidad exista en la plataforma del proveedor
2. Si no existe, la registra (device_created=true)
3. Para OSINERGMIN: normaliza la placa al formato peruano con guión
4. Activa la transmisión
5. Retorna al CRM: imei, plate, device_created, transmitting=true

🔍 Búsqueda externa (antes de registrar)

Verifica que una unidad exista en la plataforma del proveedor antes de registrarla.

🚛 SUTRAN

Superintendencia de Transporte Terrestre. Fiscaliza buses interprovinciales, carga pesada y transporte escolar.

⛽ OSINERGMIN

Organismo Supervisor de la Inversión en Energía y Minería. Fiscaliza transporte de hidrocarburos (combustibles).

⛏ UNIGIS

Monitoreo de minería y seguridad. Envío de posiciones + eventos de seguridad.

⚓ MAERSK

Naviera. Retransmisión a su plataforma de visibilidad logística para contenedores en ruta.

📦 SIPCOP

Sistema de transporte de productos controlados.

📝 Logs de transmisión

Cada trama enviada a una entidad queda registrada con status HTTP y respuesta del destino.

Consultar

1. Menú → Logs
2. Filtros: por IMEI, por entidad, por status (200 / error)
3. Vista muestra payload enviado + respuesta recibida + timestamp

Retención

Los logs se guardan 90 días en la tabla principal. Después pasan automáticamente a transmission_logs_archivo vía cron semanal (domingos 3 AM). Permanecen consultables desde esa tabla por 5 años antes de ser eliminados.

🛰 Auditoría

Bitácora de acciones del personal. Solo Admin

Registra: LOGIN, DEVICE_CREATE, DEVICE_UPDATE, DEVICE_DELETE, TRANSMISSION_ON, TRANSMISSION_OFF. Cada evento con usuario, IP, timestamp y detalle completo.

👤 Usuarios

Gestión de cuentas del Hub. Solo Admin

Roles

Crear usuario

1. Menú → Usuarios → + Nuevo
2. Username (sin espacios), email corporativo, nombre completo
3. Rol: admin u operator
4. Password inicial fuerte
5. El sistema envía email de verificación al usuario
6. Al verificar + cambiar password, queda activo

🔐 Privacidad — Ley 29733

Cumplimiento de la Ley de Protección de Datos Personales del Perú.

Qué datos procesa Global Hub

• IMEI del equipo GPS
• Placa del vehículo
• Coordenadas en tiempo real (últimas + histórico)
• Velocidad, ignición, odómetro
• Razón social del cliente (transport_vendor)

Tabla consent_log

Cada activación/desactivación de destino queda registrada con:

• device_imei, device_plate
• destination (sutran/osinergmin/unigis/maersk/sipcop)
• action: granted | revoked
• granted_at, revoked_at
• contract_ref: referencia al contrato del cliente en el CRM
• granted_by: usuario que ejecutó + IP

Derechos del titular (art. 18-22)

Acceso, rectificación, cancelación y oposición. Canal: contacto@globalgpsperu.com. Plazo: 20 días hábiles.

🔗 Integración con el CRM

Cómo el CRM se comunica con el Hub para automatizar la activación de filtros.

Flujo completo

1. En el CRM: al guardar una unidad GPS con filtros marcados (SUTRAN, OSINERGMIN, etc.) y speed_limit
2. CRM hace POST /api/unidades/{uid}/filtros/sync internamente
3. El módulo api/globalhub_integration/ del CRM:
   • Obtiene token JWT del Hub (POST /api/login) con credenciales dedicadas (usuario crm_integration)
   • Por cada filtro nuevo: POST /api/transmission/auto-activate con IMEI/placa, provider, destination
   • Por cada filtro a desactivar: POST /api/transmission/toggle enabled=false
4. El Hub responde con estado final; el CRM actualiza su tabla unidad_filtros_regulatorios
5. Si algo falla, el CRM reintenta con cron cada 15 min. Tras 3 fallos: estado error_persistente + alerta al admin.

Credenciales Hub en el CRM

Variables del /etc/crm/env:

GHUB_API_URL=https://apirest.globalgpsperu.com
GHUB_USER=crm_integration
GHUB_PASS=<secret>

⚡ API endpoints

Lista completa de endpoints REST. Todos requieren JWT excepto /api/login.

Autenticación

Unidades

Transmisión

Logs

❓ Preguntas frecuentes

gpg -d --batch --passphrase "$BACKUP_PASSPHRASE" \
  backup.db.gz.gpg | gunzip > restore.db

⚠ Errores comunes

📞 Soporte