Documentazione Tecnica

Documentazione completa di DigitalDraw: architettura, database, API e funzionalità.

Panoramica

Panoramica

DigitalDraw è una piattaforma completa per la gestione documentale su tablet Android. Il sistema è composto da tre componenti principali:

  • Console Web Amministrativa - SvelteKit
  • App Android - Flutter
  • Infrastruttura - Firebase

La piattaforma permette di:

  • Inviare PDF, manuali tecnici e file CAD ai tablet
  • Tracciare lo stato di ogni documento (inviato, scaricato, visualizzato, completato)
  • Monitorare la flotta tablet in tempo reale (online/offline)
  • Comunicare con i tablet tramite chat bidirezionale
  • Gestire utenti con tre livelli di ruolo: SuperAdmin, Admin, User
  • Distribuire aggiornamenti APK direttamente dalla console
  • Inviare comandi remoti ai tablet (riavvio, factory reset, kiosk)

Ambienti

Il sistema esiste in due ambienti separati con Firebase projects distinti:

Ambiente Firebase project Package app
Production digitaldraw-production com.digitaldraw.app
Test digitalplan-25645 com.example.digitalplan

Architettura

Architettura

Stack Tecnologica

Frontend Web (Console Amministrativa)

  • Framework: SvelteKit
  • Styling: TailwindCSS
  • Charts: ECharts
  • Alerts: SweetAlert2
  • Backend API: Firebase Admin SDK

App Android

  • Framework: Flutter
  • Auth: Firebase Auth
  • Database: Cloud Firestore
  • Storage: Firebase Storage
  • Notifications: Firebase Cloud Messaging
  • State: Provider/ChangeNotifier

Infrastruttura

  • Auth: Firebase Authentication
  • Database: Cloud Firestore (europe-west1)
  • Storage: Firebase Storage
  • Hosting web: Vercel (Console Web) / Firebase Hosting (sito pubblico)
  • Cloud Functions: Firebase Functions (Node.js, europe-west1) — backup auth utenti giornaliero, marcatura dispositivi inattivi ogni 30 minuti

Struttura Database

Struttura Database

Collection Firestore

users

Documento ID = email dell'utente.

  • email: string
  • role: "SuperAdmin" | "Admin" | "User"
  • company_id: string
  • language: "it" | "en"
  • theme: "light" | "dark"
  • web_session_token: string (token sessione unico per browser, previene accessi multipli)
  • dismissed_news: string[] (IDs news silenziati)
  • last_activity: timestamp

companies

  • id: string (document ID)
  • name: string
  • location: string
  • contact_info: string
  • auto_logout_app_minutes: number (default: 30)

devices

Documento ID = device_uuid.

  • device_uuid: string
  • device_name: string
  • company_name: string
  • last_communication: timestamp
  • status: "Online" | "Offline"
  • remote_command: string | null (comando remoto da eseguire: kiosk, restart, factory_reset)

pdfs

  • file_name: string
  • device_uuid: string
  • company_name: string
  • status: "Inviato" | "Scaricato" | "Visualizzato" | "Completato" | "Eliminato"
  • upload_time: timestamp
  • downloaded_at: timestamp | null
  • expiry_date: timestamp | null
  • uploaded_by: string (email utente)

manuals

  • file_name: string
  • company_name: string
  • device_uuid: string | null (null = manuale per tutta l'azienda)
  • upload_time: timestamp
  • uploaded_by: string
  • uploaded_role: string

cads

  • file_name: string
  • company_name: string
  • device_uuid: string
  • storage_path: string (path Firebase Storage, eliminato 30s dopo il download)
  • format: "dxf" | "step" | "stp" | "iges" | "igs" (viewer integrato) | "dwg" (apertura esterna)
  • status: "Nuovo" | "Scaricato" | "Visualizzato" | "Completato" | "Eliminato"
  • upload_time: timestamp
  • downloaded_at: timestamp | null
  • complete_date: timestamp | null
  • expiry_date: timestamp | null
  • uploaded_by: string

chats/{device_uuid}/messages

Sotto-collezione per device.

  • message: string
  • timestamp: timestamp
  • sender: "console" | "device"

news

  • title: string
  • content: string
  • company_id: string (o "*" per tutte le aziende)
  • active: boolean
  • created_at: timestamp

reset_password_requests

  • email: string
  • company_id: string
  • status: "pending" | "completed"
  • timestamp: timestamp
  • nudge_count: number

logs

  • action: string
  • details: string | object
  • timestamp: timestamp
  • user_email: string
  • role: string
  • company_id: string

app_releases

  • version: string
  • apk_url: string (Firebase Storage URL)
  • uploaded_at: timestamp
  • uploaded_by: string

SiteContactRequest

Richieste contatto dal sito pubblico (digitaldraw.it).

  • name: string
  • company: string
  • email: string
  • phone: string
  • message: string
  • timestamp: timestamp

API Routes

API Routes

Endpoint Console Web (SvelteKit)

Autenticazione

  • POST /api/login - Login utente
  • POST /api/logout - Logout utente
  • POST /api/create-reset-request - Richiesta reset password
  • POST /api/change-password - Cambia password
  • POST /api/change-email - Cambia email

Gestione

  • GET /api/status - Stato server
  • GET /api/get-devices-by-status - Dispositivi per stato
  • GET /api/get-company-id - ID azienda da email
  • POST /api/delete-user - Elimina utente

Distribuzione App

  • GET /api/app-distribution/releases - Lista release
  • POST /api/app-distribution/upload - Carica nuova release
  • POST /api/app-distribution/delete - Elimina release

Contatti

  • POST /api/contact - Invia richiesta contatto

Endpoint Backend (Express)

Configurazione

  • GET /config - Restituisce configurazione Firebase per l'app Android

Sicurezza

Sicurezza

Ruoli Utente

  • SuperAdmin: Accesso globale su tutte le aziende, configurazione sistema
  • Admin: Accesso completo alla propria azienda
  • User: Accesso limitato (dashboard, documenti, chat della propria azienda)

Autenticazione

  • Firebase Authentication (email/password)
  • Cookie JWT HttpOnly lato server (token=JWT; secure; samesite=strict)
  • Token refresh automatico ogni 50 minuti lato client
  • Auto-logout configurabile per inattività (default: 30 minuti in app, configurabile per company)
  • Verifica token lato server via Firebase Admin SDK a ogni richiesta protetta

Sessione Unica per Browser

Ogni accesso genera un web_session_token UUID salvato su Firestore. Il client verifica ogni 30 secondi che il token corrisponda: se un altro accesso è avvenuto da un altro browser, viene fatto logout automatico. Previene sessioni concorrenti non autorizzate.

Protezione Route (Console Web)

  • Route pubbliche (no auth): /, /login, /api/login, /api/status
  • Route protette: richiedono token valido
  • Route solo Admin: /users, /companies, /machines, /manuals, /pdfs (upload), /app-distribution
  • Route solo SuperAdmin: /superadmin-settings, /news, /permissions, /contact-requests

Regole Firestore

  • Ogni utente può vedere solo dati della propria company_id
  • Solo Admin/SuperAdmin possono scrivere su users, companies, devices
  • Gli utenti del tablet possono aggiornare solo i campi status, downloaded_at sui propri documenti
  • Manuali: Admin può leggere/scrivere per la propria azienda, SuperAdmin su tutto
  • Audit log per tutte le operazioni sensibili

Storage

Tutti i file (PDF, manuali, CAD, APK) sono archiviati su Firebase Storage.

  • Accesso richiede autenticazione (request.auth != null)
  • Path strutturati per azienda e device: /pdfs/{company}/{device}/{fileName}
  • I file CAD vengono eliminati da Storage 30 secondi dopo il download sul tablet

Best Practices

  • HTTPS obbligatorio in tutti gli ambienti
  • Nessuna credenziale hardcoded nel codice
  • Variabili d'ambiente per config Firebase (server-side via FIREBASE_PROJECT_ID, FIREBASE_CLIENT_EMAIL, FIREBASE_PRIVATE_KEY)
  • Variabili Vite per Firebase client (VITE_FIREBASE_*)
  • Nessun dato sensibile esposto lato client

Funzionalità App

Funzionalità App Android

1. Login

Descrizione

Schermata di autenticazione utente con email/password. Gestisce il login tramite Firebase Authentication e verifica lo stato offline del dispositivo.

Funzionalità principali

  • Login con email/password via Firebase Auth
  • Sincronizzazione password con polling periodico
  • Aggiornamento automatico dati azienda ogni 24h
  • Login offline con password criptata localmente
  • Visualizzazione errori con messaggi descrittivi
  • Timeout logout automatico impostabile dalla console admin
  • Verifica device registrato in console

2. Home

Descrizione

Dashboard principale con navigazione tra le sezioni dell'app (PDF, CAD, Manuali, Chat, News, Impostazioni, Oscura Schermo). Gestisce lo stato globale dell'applicazione e i servizi in background.

Funzionalità principali

  • Bottom navigation bar con 7 sezioni (PDF, CAD, Manuali, Chat, News, Impostazioni, Oscura Schermo)
  • Badge e popup per nuovi contenuti (PDF, CAD, News)
  • Notifiche push per i messaggi ricevuti dalla console amministrativa
  • Oscuramento schermo per privacy del progetto visualizzato

3. PDF List & Viewer

Descrizione

Sezione per la gestione dei documenti PDF ricevuti. Include lista documenti con ricerca e visualizzatore integrato.

Funzionalità principali

Lista PDF:

  • Lista PDF ricevuti dalla console amministrativa
  • Barra di ricerca per nome file
  • Indicatore di stato del documento (Nuovo, Scaricato, Completato)
  • Controllo e download nuovi PDF ogni 30 secondi
  • Completamento progetto con selezione multipla PDF
  • Eliminazione PDF locali al completamento
  • Gestione file duplicati (mantiene la versione più recente)

Visualizzatore PDF:

  • Visualizzazione PDF integrata nell'app
  • Controlli zoom In/Out (0.5x - 4.0x)
  • Gestione pagine
  • Indicatore pagina corrente / totale
  • Reset zoom al cambio pagina

4. Manual List & Viewer

Descrizione

Sezione per la gestione dei manuali tecnici. Download automatico all'apertura.

Funzionalità principali

  • Lista di manuali ricevuti dalla console amministrativa
  • Barra di ricerca per nome file
  • Download automatico iniziale all'apertura per la versione più aggiornata
  • Visualizzazione integrata
  • Cache locale manuali

Visualizzatore manuali:

  • Visualizzazione PDF integrata nell'app
  • Controlli zoom In/Out (0.5x - 4.0x)
  • Gestione pagine
  • Indicatore pagina corrente / totale
  • Reset zoom al cambio pagina

5. CAD List & Viewer

Descrizione

Sezione per la visualizzazione di file CAD (DXF, STEP/IGES). Struttura simile a PDF/Manuali.

Funzionalità principali

Lista CAD:

  • Lista di file CAD ricevuti dalla console amministrativa
  • Barra di ricerca per nome file
  • Indicatore di stato del documento (Nuovo, Scaricato, Completato)
  • Controllo e download nuovi CAD ogni 30 secondi
  • Completamento progetto con selezione multipla CAD
  • Eliminazione CAD locali al completamento
  • Gestione file duplicati (mantiene la versione più recente)

Viewer CAD:

  • Visualizzazione DXF
  • Visualizzazione STEP/IGES
  • Supporto rotazione, zoom, spostamento disegno
  • Visualizzazione 3D per file STEP/IGES
  • Caricamento CAD a fasi

6. News

Descrizione

Sistema di notifiche "news" con popup e opzione "non mostrare più".

Funzionalità principali

  • Notifiche push in tempo reale
  • Opzione "Non mostrare più" con persistenza locale
  • Ogni device vede le news della propria azienda, oppure quelle destinate solo ad esso
  • Badge sulla campanella nella barra di navigazione
  • Controllo news pendenti al cambio pagina

7. Chat

Descrizione

Sistema di messaggistica bidirezionale in tempo reale blindato per device.

Funzionalità principali

  • Messaggistica bidirezionale realtime
  • Storico conversazioni
  • Notifiche push per nuovi messaggi
  • Auto-scroll al nuovo messaggio
  • Segna messaggi come già letto automaticamente all'apertura
  • Sono mostrate le informazioni del mittente
  • E' mostrata la data/ora di invio del messaggio
  • Disattivazione notifiche quando si è nella schermata chat

8. Settings

Descrizione

Pannello con info dispositivo (visualizzazione) e impostazioni modificabili (tema, lingua, luminosità, volume, timezone)

Funzionalità principali

Info dispositivo:

  • UUID dispositivo
  • Nome dispositivo
  • Email utente connesso
  • Versione app e build number
  • Nome azienda

Impostazioni:

  • Tema chiaro/scuro
  • Lingua applicazione (italiano/inglese)
  • Controllo luminosità schermo
  • Controllo volume sistema
  • Informazione relativa alla modalità kiosk
  • Selezione della timezone
  • Data e ora configurabile o sincronizzabile
  • Logout con conferma

9. Dark Screen (Overlay)

Descrizione

Schermata nera full-screen per nascondere eventuali progetti aperti e dati sensibili.

Funzionalità principali

  • Background nero full-screen
  • Immagine overlay centrale
  • Chiudi con tap sullo schermo

Funzionalità Console

Funzionalità Console Web

Dashboard

  • Statistiche generali (dispositivi, documenti)
  • Grafico attività dispositivi
  • Storico recente

Gestione Dispositivi

  • Registrazione nuovi dispositivi
  • Assegnazione ad azienda
  • Stato online/offline
  • Ultima attività
  • Edit/elimina dispositivi

Gestione Utenti

  • Creazione utenti
  • Assegnazione ruoli (admin/user)
  • Assegnazione azienda
  • Reset password
  • Elimina utenti

Gestione Aziende

  • Creazione aziende
  • Modifica impostazioni (timeout logout)
  • Elimina aziende

Gestione Permessi

  • Definizione permessi per ruolo
  • Visualizzazione permessi utente

Distribuzione Documenti

  • Caricamento PDF
  • Selezione destinatari (dispositivi)
  • Invio con un click
  • Tracciamento stato invio

Gestione PDF/Manuali

  • Lista globale documenti
  • Filtri (nome, azienda, stato)
  • Eliminazione documenti

Gestione CAD

  • Caricamento file CAD (DXF, DWG, STEP, IGES)
  • Assegnazione a dispositivo specifico per azienda
  • Tracciamento stato (Nuovo / Scaricato / Visualizzato / Completato)
  • Impostazione data di scadenza opzionale per ogni file
  • Eliminazione file dalla console (rimuove anche dal dispositivo)

Log Attività

  • Storico completo azioni
  • Filtro per tipo azione
  • Esportazione dati

Chat

  • Conversazione per dispositivo
  • Invio messaggi
  • Visualizzazione letto/non letto

Distribuzione App

  • Caricamento APK
  • Gestione versioni
  • Download diretto APK

Richieste Contatto

  • Visualizzazione richieste
  • Marcatore come elaborato

Gestione News

  • Creazione e modifica news
  • Targeting per azienda o dispositivo specifico
  • Attivazione/disattivazione news
  • Opzione "non mostrare più" per gli utenti

Richieste Reset Password

  • Visualizzazione richieste reset password
  • Approvazione/rifiuto richieste
  • Notifica utente

Supporto

  • Pagina di supporto per gli utenti
  • Visualizzazione informazioni di contatto

Account Utente

  • Visualizzazione profilo utente
  • Modifica dati personali
  • Gestione password

Impostazioni (Super Admin)

  • Configurazione parametri globali
  • Gestione impostazioni di sistema

Console Tablet (script)

Script a riga di comando nella cartella console/ del progetto Flutter per gestire i tablet fisicamente via USB.

Avvio

OS Comando
Linux / Mac ./console/console.sh
Windows doppio click su console/console.bat

Selezione ambiente

All'avvio chiede l'ambiente da usare e mostra i percorsi configurati:

  • T — Test (com.example.digitalplan)
  • P — Production (com.digitaldraw.app)
  • C — Configura percorsi (salvati in console/.console_config)

Opzioni menu

# Funzione Disponibilità
1 Nuovo tablet (build + installa + kiosk) Dev con Flutter
2 Aggiorna app (build + reinstalla) Dev con Flutter
3 Test + log (flutter run, debug) Dev con Flutter
4 Solo log (logcat filtrato) Tutti
5 Riavvia app tablet Tutti
6 Info tablet Tutti
7 Apri impostazioni tablet Tutti
8 Prepara pacchetto per collega (ZIP) Dev con Flutter
9 Cambia ambiente Tutti

Pacchetto per collega (opzione 8)

Genera DigitalDraw-Setup-TEST.zip o DigitalDraw-Setup-PROD.zip contenente:

  • APK compilato (app-test.apk o app-prod.apk)
  • console.bat + console.ps1 — script Windows
  • adb.exe, AdbWinApi.dll, AdbWinUsbApi.dll — ADB già incluso

Il collega estrae lo ZIP e fa doppio click su console.bat. Non deve installare nulla.

Prerequisito una-tantum

I binari ADB Windows vanno salvati in console/tools/windows-adb/ nel repo (una volta sola, poi si committano):

adb.exe
AdbWinApi.dll
AdbWinUsbApi.dll

Scaricabili da: https://dl.google.com/android/repository/platform-tools-latest-windows.zip

Modalità collega (Windows senza Flutter)

Quando adb.exe è nella stessa cartella dello script (pacchetto collega), la console entra automaticamente in modalità ridotta:

  • Nessuna build Flutter
  • APK letto dalla stessa cartella (app-test.apk / app-prod.apk)
  • Menu mostra solo le operazioni disponibili (1, 2, 4, 5, 6, 7, 9)
  • Opzioni 3 e 8 non visibili

Config percorsi

I percorsi dei due progetti vengono salvati in console/.console_config (ignorato da git):

TEST_DIR=/path/to/DigitalDraw-Flutter-AndroidApp-Test
PROD_DIR=/path/to/DigitalDraw-Flutter-AndroidApp-Production

Deploy

Deploy

Console Web (SvelteKit)

  • Piattaforma: Vercel
  • Build: npm run build
  • Adapter: @sveltejs/adapter-auto

Cloud Functions (Firebase)

  • Piattaforma: Firebase Functions (Node.js, europe-west1)
  • Deploy: firebase deploy --only functions
  • Funzioni attive:
    • backupAuthUsers — backup giornaliero utenti Firebase Auth su Storage (01:00 Roma, retention 30 giorni)
    • markInactiveDevices — marca offline i device senza comunicazione da 24h (ogni 30 minuti)

App Android

  • Build: flutter build apk --release
  • Firma: keystore digitale
  • Distribuzione: Firebase App Distribution / APK diretto

Console Tablet

La cartella console/ nel progetto Flutter contiene gli script per gestire i tablet via USB:

  • console/console.sh — Linux / Mac
  • console/console.bat — Windows (lancia console.ps1)
  • console/console.ps1 — Windows PowerShell

Per creare un pacchetto autonomo per un collega Windows (senza Flutter):

./console/console.sh  →  opzione 8

Genera uno ZIP con APK, script e ADB già inclusi. Il collega non installa nulla.

Prerequisito una-tantum per l'opzione 8

Salvare i binari ADB Windows in console/tools/windows-adb/ nel repo:

  • adb.exe
  • AdbWinApi.dll
  • AdbWinUsbApi.dll

Download: https://dl.google.com/android/repository/platform-tools-latest-windows.zip

Firebase

  • Authentication: Abilitato
  • Firestore: Database predefinito
  • Storage: Bucket predefinito
  • Hosting: Opzionale