📋 Proposta Ristrutturazione Database Devices

Data: 12 Dicembre 2025
Stato: Draft - In discussione
Autori: Team Visla GPS

---

🎯 Obiettivo

Separare nettamente i dati fissi del dispositivo (gestiti da admin) dai dati personalizzabili per utente (gestiti da owner/viewer), migliorando la gestione della condivisione e riducendo la complessità dello schema.

---

📊 Schema Attuale vs Proposto

Schema Attuale (3 tabelle)

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   DeviceList    │    │     Device      │    │   UserDevice    │
│  (inventario)   │    │   (runtime +    │    │  (permessi +    │
│                 │    │   custom attrs) │    │    ownership)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Problemi:

• Device mescola dati fissi (model) con dati runtime (status) e custom (name)
• Duplicazione di dati tra DeviceList e Device
• Il nome del device è unico, ma ogni utente potrebbe volerlo vedere diversamente

Schema Proposto (2 tabelle)

┌──────────────────┐         ┌─────────────────────┐
│  DeviceCatalog   │ ◄──1:N──│   UserDeviceView    │
│    (FIXED)       │         │ (CUSTOM + PERMESSI) │
└──────────────────┘         └─────────────────────┘

Vantaggi:

• ✅ Separazione chiara delle responsabilità
• ✅ Ogni utente può personalizzare il proprio "view" del device
• ✅ Meno tabelle, meno complessità
• ✅ Condivisione più naturale

---

📐 Schema Dettagliato

Tabella device_catalog (FIXED - gestita da Admin)

Contiene i dati immutabili del dispositivo fisico, gestiti esclusivamente dall'amministratore.

Colonna	Tipo	Constraints	Descrizione
id	BIGINT	PK, AUTO_INCREMENT	ID primario
imei	VARCHAR(128)	UNIQUE, NOT NULL	IMEI del dispositivo
device_unique_id	VARCHAR(128)		Device unique ID originale
protocol_id	VARCHAR(128)	UNIQUE, INDEX, NOT NULL	ID usato dal decoder per match
model	VARCHAR(128)	NOT NULL	Modello (S21L, G11-SE, etc.)
sim	VARCHAR(128)		Numero SIM associata
claim_token	VARCHAR(128)	UNIQUE, NOT NULL	Token per claim da app
status	VARCHAR(32)	DEFAULT 'offline'	online/offline (runtime)
last_update	DATETIME		Ultimo aggiornamento posizione
position_id	BIGINT		ID ultima posizione
created_at	DATETIME	NOT NULL	Data creazione inventario

CREATE TABLE device_catalog (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    imei VARCHAR(128) UNIQUE NOT NULL,
    device_unique_id VARCHAR(128),
    protocol_id VARCHAR(128) UNIQUE NOT NULL,
    model VARCHAR(128) NOT NULL,
    sim VARCHAR(128),
    claim_token VARCHAR(128) UNIQUE NOT NULL,
    status VARCHAR(32) DEFAULT 'offline',
    last_update DATETIME,
    position_id BIGINT,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    
    INDEX idx_protocol_id (protocol_id),
    INDEX idx_claim_token (claim_token)
);

---

Tabella user_device_view (CUSTOM - gestita da Owner/Viewer)

Contiene la "vista" personalizzata che ogni utente ha del dispositivo, inclusi permessi e attributi custom.

Colonna	Tipo	Constraints	Descrizione
id	BIGINT	PK, AUTO_INCREMENT	ID primario
user_id	BIGINT	NOT NULL, INDEX	ID utente
device_id	BIGINT	FK → device_catalog, NOT NULL	Riferimento al device
OWNERSHIP
is_owner	BOOLEAN	NOT NULL, DEFAULT FALSE	TRUE se è il proprietario
shared_by	BIGINT		user_id di chi ha condiviso (NULL se owner)
CUSTOM ATTRIBUTES
name	VARCHAR(128)	NOT NULL	Nome personalizzato
category	VARCHAR(128)		Categoria (auto, moto, bici...)
icon	VARCHAR(64)		Icona personalizzata
color	VARCHAR(32)		Colore nel UI
attributes	TEXT		JSON con attributi extra
group_id	BIGINT		Gruppo/folder per organizzazione
PERMISSIONS
permission_position	BOOLEAN	DEFAULT TRUE	Può vedere posizione
permission_events	BOOLEAN	DEFAULT TRUE	Può vedere eventi
permission_geofences	BOOLEAN	DEFAULT TRUE	Può gestire geofence
permission_notifications	BOOLEAN	DEFAULT TRUE	Riceve notifiche
permission_commands	BOOLEAN	DEFAULT FALSE	Può inviare comandi
META
created_at	DATETIME	NOT NULL	Data creazione relazione

CREATE TABLE user_device_view (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT NOT NULL,
    device_id BIGINT NOT NULL,
    
    -- Ownership
    is_owner BOOLEAN NOT NULL DEFAULT FALSE,
    shared_by BIGINT,
    
    -- Custom attributes
    name VARCHAR(128) NOT NULL,
    category VARCHAR(128),
    icon VARCHAR(64),
    color VARCHAR(32),
    attributes TEXT,
    group_id BIGINT,
    
    -- Permissions
    permission_position BOOLEAN NOT NULL DEFAULT TRUE,
    permission_events BOOLEAN NOT NULL DEFAULT TRUE,
    permission_geofences BOOLEAN NOT NULL DEFAULT TRUE,
    permission_notifications BOOLEAN NOT NULL DEFAULT TRUE,
    permission_commands BOOLEAN NOT NULL DEFAULT FALSE,
    
    -- Meta
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE KEY uk_user_device (user_id, device_id),
    FOREIGN KEY (device_id) REFERENCES device_catalog(id) ON DELETE CASCADE,
    INDEX idx_user_id (user_id),
    INDEX idx_device_id (device_id)
);

---

🔄 Flussi di Business

1. Admin Crea Dispositivo (Inventario)

2. Utente Claim Dispositivo

3. Owner Condivide con Viewer

4. Viewer Personalizza la sua Vista

---

📋 Matrice Permessi

Azione	Owner	Viewer (con permesso)	Viewer (senza permesso)
Vedere posizione	✅	✅ (se permission_position)	❌
Vedere eventi	✅	✅ (se permission_events)	❌
Modificare nome/categoria	✅	✅ (la sua vista)	✅ (la sua vista)
Gestire geofence	✅	✅ (se permission_geofences)	❌
Inviare comandi	✅	✅ (se permission_commands)	❌
Condividere con altri	✅	❌	❌
Rimuovere device	✅	❌	❌

---

🛠️ Impatto sui Microservizi

Servizio	Modifiche Necessarie
device-service	Refactor modelli, routes, logica claim
db-persister	Aggiornare status/position su device_catalog
tracking-service	Query join device_catalog + user_device_view
sharing-service	Logica inserimento user_device_view
admin-panel	CRUD su device_catalog, import CSV
notification-service	Query permessi da user_device_view

---

📈 Migrazione

Step 1: Creare nuove tabelle

-- Creare device_catalog e user_device_view

Step 2: Migrare dati esistenti

-- Da device_list + devices → device_catalog
INSERT INTO device_catalog (imei, device_unique_id, protocol_id, model, sim, claim_token, status, last_update, position_id)
SELECT 
    dl.imei,
    dl.device_unique_id,
    COALESCE(d.unique_id, dl.device_unique_id, dl.imei) as protocol_id,
    COALESCE(dl.model, d.model),
    dl.sim,
    dl.token,
    d.status,
    d.last_update,
    d.position_id
FROM device_list dl
LEFT JOIN devices d ON d.unique_id = dl.device_unique_id OR d.unique_id = dl.imei;

-- Da user_device + devices → user_device_view
INSERT INTO user_device_view (user_id, device_id, is_owner, shared_by, name, category, attributes, permission_position, ...)
SELECT 
    ud.user_id,
    dc.id,
    ud.is_owner,
    ud.shared_by,
    d.name,
    d.category,
    d.attributes,
    ud.permission_position,
    ...
FROM user_device ud
JOIN devices d ON d.id = ud.device_id
JOIN device_catalog dc ON dc.protocol_id = d.unique_id;

Step 3: Aggiornare codice microservizi

Step 4: Test completi

Step 5: Drop vecchie tabelle (dopo periodo di transizione)

---

❓ Domande Aperte

1. Gruppi/Folder: Ogni utente può avere i propri gruppi o sono condivisi con chi accede al device?

2. Attributi custom condivisi: Ci sono attributi che l'owner imposta e tutti vedono (es. targa)?

3. Notifiche: Le notifiche sono per device (owner imposta, tutti ricevono) o per user_device_view (ognuno imposta le sue)?

4. Storico condivisione: Serve tenere log di chi ha avuto accesso e quando?

---

✅ Prossimi Passi

• Review da parte del team
• Rispondere alle domande aperte
• Creare implementation plan dettagliato
• Stimare effort
• Pianificare sprint

---

Documento generato il 12/12/2025 - Versione 1.0