Data Flow Architecture

Questo documento descrive il flusso dei dati dalla ricezione sul decoder alla visualizzazione nelle app (Web, iOS, Android).

🔄 Overview del Flusso

┌─────────────┐      ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   DEVICE    │ ──▶  │   DECODER   │ ──▶  │   REDIS     │ ──▶  │  SERVICES   │
│  (GPS/IoT)  │ TCP  │   (Java)    │      │  Streams    │      │  (Python)   │
└─────────────┘      └─────────────┘      └─────────────┘      └─────────────┘
                                                                     │
                     ┌─────────────┐      ┌─────────────┐           │
                     │   FRONTEND  │ ◀──  │  WEBSOCKET  │ ◀─────────┘
                     │ (Web/Mobile)│      │  (Python)   │
                     └─────────────┘      └─────────────┘

---

📦 Redis Streams

Stream	Descrizione	Producer	Consumer
positions:raw	Posizioni grezze dal decoder	Decoder	Positions Service
positions:validated	Posizioni validate e arricchite	Positions Service	WebSocket, Events
presence	Status online/offline	Decoder	WebSocket
events	Allarmi, geofence, etc.	Events Service	WebSocket, Notification

---

📊 Campi Position

Campi Core (sempre presenti)

Campo	Tipo	Descrizione
deviceId	long	ID univoco del device
protocol	string	Nome protocollo (s21l, v6c, g11lse, etc.)
deviceTime	timestamp	Ora del dispositivo
fixTime	timestamp	Ora fix GPS
serverTime	timestamp	Ora ricezione server
latitude	double	Latitudine
longitude	double	Longitudine
altitude	double	Altitudine (metri)
speed	double	Velocità (knots)
course	double	Direzione (gradi)
valid	boolean	GPS valido

Campi Arricchiti (aggiunti dal Positions Service)

Campo	Tipo	Descrizione
distance	double	Distanza dall'ultima posizione (metri)
totalDistance	double	Distanza totale cumulativa (metri)
motion	boolean	In movimento (speed > threshold)

Campi Status

Campo	Tipo	Descrizione
ignition	boolean	Contatto acceso
motion	boolean	In movimento
blocked	boolean	Dispositivo bloccato
charging	boolean	In carica

Campi Power

Campo	Tipo	Descrizione
batteryLevel	integer	Percentuale batteria (0-100)
battery	double	Tensione batteria (V)
power	double	Tensione alimentazione esterna (V)

Campi Network/GPS

Campo	Tipo	Descrizione
rssi	integer	Potenza segnale GSM (0-100)
satellites	integer	Numero satelliti GPS
hdop	double	Precisione orizzontale GPS

Campi Cell Tower

Campo	Tipo	Descrizione
cellId	long	Cell ID
lac	integer	Location Area Code
mcc	integer	Mobile Country Code
mnc	integer	Mobile Network Code

Campi Odometer

Campo	Tipo	Descrizione
odometer	long	Contachilometri totale (metri)
odometerTrip	double	Contachilometri viaggio (metri)
hours	long	Ore motore

Campi OBD

Campo	Tipo	Descrizione
obdSpeed	integer	Velocità da OBD (km/h)
obdOdometer	long	Chilometraggio da OBD
rpm	integer	Giri motore
throttle	double	Posizione acceleratore (%)
engineLoad	double	Carico motore (%)
coolantTemp	integer	Temperatura liquido raffreddamento (°C)

Campi Fuel

Campo	Tipo	Descrizione
fuelLevel	double	Livello carburante (%)
fuelConsumption	double	Consumo carburante (L/100km)
fuelUsed	double	Carburante usato (L)

Campi Allarmi

Campo	Tipo	Descrizione
alarm	string	Tipo allarme corrente
alarms	array[string]	Lista allarmi attivi
event	integer	Codice evento protocollo
status	integer	Codice status protocollo

Campi Driver/IO

Campo	Tipo	Descrizione
driver	string	Nome autista
driverId	string	ID autista (iButton, RFID)
input	long	Input digitali (bitmask)
output	long	Output digitali (bitmask)
io1	integer	Input digitale 1
adc1	double	Input analogico 1
adc2	double	Input analogico 2

Campi Vehicle

Campo	Tipo	Descrizione
vin	string	Vehicle Identification Number
dtcs	string	Diagnostic Trouble Codes

Campi Altri

Campo	Tipo	Descrizione
iccid	string	ID SIM card
gSensor	string	Dati accelerometro
tilt	string	Angolo inclinazione
geofence	integer	ID geofence corrente
wakeSource	integer	Causa risveglio

Campi Complessi (JSONB)

Campo	Tipo	Descrizione
network	object	Info rete completa
cellTowers	array	Lista cell tower
wifiAccessPoints	array	Lista WiFi AP
temperatures	array	Sensori temperatura
locks	object	Stato serrature
geofenceIds	array	ID geofence attivi
attributes	object	Campi custom/sconosciuti

---

🗃️ Database Schema

Tabella positions (PostgreSQL)

Tutti i campi position sono ora colonne dedicate per query performanti. Solo i campi sconosciuti/custom vanno nella colonna attributes JSONB.

Tabella user_device_attributes

Campo	Tipo	Descrizione
status	string	"online" / "offline"
last_update	timestamp	Ultimo aggiornamento
position_id	bigint	FK a positions.id (ultima posizione)

---

📱 Pattern "Load + Subscribe" (Web & Mobile)

Tutte le app client (Web, iOS, Android) seguono lo stesso pattern:

1. Al Caricamento (Load)

// Chiamate API iniziali
const devices = await api.get('/api/devices');
// Restituisce per ogni device:
// - id, name, status (online/offline), lastUpdate, positionId, ...

const positions = await api.get('/api/positions');
// Restituisce ultima posizione per ogni device:
// - latitude, longitude, speed, battery, rssi, ...

// Mostra i dati sulla mappa
renderDevices(devices, positions);

2. In Real-Time (Subscribe)

// Connessione WebSocket
const ws = new WebSocket('wss://api.vislagps.com/ws');

// Ascolto aggiornamenti
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  
  switch (msg.type) {
    case 'position':
      // Nuova posizione → aggiorna mappa
      updateDevicePosition(msg.data);
      break;
      
    case 'device_status':
      // Online/offline → aggiorna icona
      updateDeviceStatus(msg.data.deviceId, msg.data.status);
      break;
      
    case 'event':
      // Allarme → mostra notifica
      showEventNotification(msg.data);
      break;
  }
};

Flusso Completo

┌─────────────────────────────────────────────────────────────┐
│                        APP STARTUP                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. GET /api/devices          2. GET /api/positions         │
│       ↓                            ↓                        │
│  ┌──────────────┐            ┌──────────────┐               │
│  │ status       │            │ latitude     │               │
│  │ lastUpdate   │            │ longitude    │               │
│  │ positionId   │            │ speed        │               │
│  │ name, icon   │            │ battery      │               │
│  └──────────────┘            │ rssi, etc.   │               │
│                              └──────────────┘               │
│                                                             │
│  3. RENDER → Mostra mappa con posizioni e status           │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                        REAL-TIME                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  4. WebSocket Connect → Subscribe a updates                  │
│                                                             │
│  5. On message:                                              │
│     - position → Muovi marker                                │
│     - device_status → Cambia icona online/offline           │
│     - event → Toast notifica                                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

📲 Mobile Apps (iOS & Android)

SÌ, le app mobile usano la stessa logica:

1. Al login/avvio: GET /api/devices + GET /api/positions
2. Connessione WebSocket per aggiornamenti real-time
3. Push notifications per allarmi critici (via Firebase/APNs)

Differenze Mobile:

Aspetto	Web App	Mobile App
WebSocket	Sempre connesso	Background limitato
Notifiche	Toast in-app	Push notifications
Offline	Non supportato	Cache locale
Background	Tab switch = pause	App lifecycle management

Background Behavior (Mobile)

Quando l'app va in background:

1. WebSocket viene chiuso
2. Push notifications attive per allarmi critici
3. Al ritorno in foreground:
   • Re-fetch GET /api/devices + GET /api/positions
   • Re-connect WebSocket

---

🔐 Autenticazione

Client	Metodo
Web App	Cookie httpOnly (access_token)
Mobile Apps	Bearer Token (header Authorization)
WebSocket	Token nel query param (?token=...)

---

📡 WebSocket Messages

Position Update

{
  "type": "position",
  "data": {
    "deviceId": 123,
    "latitude": 45.4642,
    "longitude": 9.1900,
    "speed": 45.5,
    "altitude": 150,
    "course": 180,
    "valid": true,
    "motion": true,
    "ignition": true,
    "battery": 85.5,
    "rssi": 90,
    "distance": 125.5,
    "totalDistance": 50234.7,
    "serverTime": "2024-12-30T22:00:00Z"
  }
}

Device Status Update

{
  "type": "device_status",
  "data": {
    "deviceId": 123,
    "protocolId": "999999999321",
    "status": "online"
  }
}

Event Notification

{
  "type": "event",
  "data": {
    "id": 456,
    "type": "alarm",
    "deviceId": 123,
    "attributes": {
      "alarm": "sos"
    },
    "eventTime": "2024-12-30T22:00:00Z"
  }
}

---

✅ Vantaggi Architettura

1. Single Source of Truth: Database è la fonte, non cache
2. Persistenza: Stato sopravvive ai riavvii
3. Consistenza: API e WebSocket danno gli stessi dati
4. Performance: Colonne dedicate per query veloci
5. Scalabilità: WebSocket stateless, può scalare orizzontalmente