# Terrain Monitor Backend Sistema backend per il monitoraggio di terreni (frane, gallerie, ponti, dighe) con notifiche push real-time per app mobile Android e iOS. ## Architettura ``` Sistema Monitoraggio ’ MQTT ’ Backend (FastAPI) ’ Firebase FCM ’ App Mobile “ PostgreSQL DB ``` ### Componenti Principali - **FastAPI**: REST API per autenticazione, gestione allarmi e storico - **PostgreSQL**: Database per clienti, siti, utenti e allarmi - **MQTT Client**: Riceve allarmi dal sistema centralizzato - **Firebase FCM**: Invia notifiche push alle app mobile - **SQLAlchemy**: ORM per gestione database ## Struttura Progetto ``` web-app-python/  app/   api/ # Endpoint API REST    auth.py # Autenticazione e gestione utenti    allarmi.py # Gestione allarmi   core/ # Configurazione core    config.py # Settings da env    database.py # Setup database    security.py # JWT e password hashing   models/ # Modelli SQLAlchemy    cliente.py    sito.py    utente.py    allarme.py   schemas/ # Schemi Pydantic per validazione    auth.py    allarme.py   services/ # Servizi business logic    firebase.py # Integrazione FCM   mqtt/ # Client MQTT e handler    client.py # Client MQTT    handler.py # Processamento allarmi   main.py # Applicazione FastAPI  main.py # Entry point  pyproject.toml # Dipendenze  .env.example # Template variabili ambiente  README.md ``` ## Setup ### 1. Requisiti - Python 3.12+ - PostgreSQL 14+ - Broker MQTT (es. Mosquitto) - Firebase project con FCM abilitato ### 2. Installazione ```bash # Crea virtual environment python -m venv .venv source .venv/bin/activate # Linux/Mac # .venv\Scripts\activate # Windows # Installa dipendenze pip install -e . ``` ### 3. Configurazione Database ```bash # Crea database PostgreSQL createdb terrain_monitor # oppure con psql psql -U postgres CREATE DATABASE terrain_monitor; ``` ### 4. Configurazione Firebase 1. Vai su [Firebase Console](https://console.firebase.google.com/) 2. Crea un nuovo progetto 3. Abilita Cloud Messaging 4. Scarica le credenziali di servizio: - Settings ’ Service Accounts ’ Generate new private key 5. Salva il file come `firebase-credentials.json` nella root del progetto ### 5. Variabili d'Ambiente ```bash # Copia il template cp .env.example .env # Modifica .env con i tuoi valori nano .env ``` Configurazione minima: ```env DATABASE_URL=postgresql://user:password@localhost:5432/terrain_monitor SECRET_KEY=genera-una-chiave-segreta-forte MQTT_BROKER_HOST=localhost FIREBASE_CREDENTIALS_PATH=./firebase-credentials.json ``` ### 6. Avvio Applicazione ```bash # Avvio in modalità development python main.py # oppure con uvicorn direttamente uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` L'API sarà disponibile su: http://localhost:8000 ## API Endpoints ### Autenticazione - `POST /auth/token` - Login (OAuth2 password flow) - `POST /auth/login` - Login (JSON) - `POST /auth/register-fcm-token` - Registra FCM token dispositivo - `GET /auth/me` - Info utente corrente ### Allarmi - `GET /allarmi` - Lista allarmi (con filtri e paginazione) - `GET /allarmi/{id}` - Dettaglio allarme - `PATCH /allarmi/{id}` - Aggiorna stato allarme - `GET /allarmi/sito/{sito_id}` - Allarmi per sito specifico ### Documentazione Interattiva - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc ## Database Schema ### Tabelle Principali **clienti** - id, nome, email, telefono, indirizzo - Relazioni: siti[], utenti[] **siti** - id, cliente_id, nome, tipo, coordinate - Tipi: frana, galleria, ponte, diga, versante, edificio - Relazioni: allarmi[] **utenti** - id, cliente_id, email, password_hash, fcm_token - Ruoli: admin, operatore, visualizzatore **allarmi** - id, sito_id, tipo, severita, stato - Severità: critical, warning, info - Stati: nuovo, visualizzato, in_gestione, risolto - timestamp_rilevamento, dati_sensori (JSON) ## MQTT Integration ### Topic Structure ``` terrain/alarms/{sito_id} ``` ### Payload Format (JSON) ```json { "sito_id": 123, "tipo": "movimento_terreno", "severita": "critical", "titolo": "Movimento terreno rilevato", "descrizione": "Rilevato movimento anomalo di 12.5mm", "valore_rilevato": 12.5, "valore_soglia": 10.0, "unita_misura": "mm", "timestamp": "2025-10-18T10:30:00Z", "dati_sensori": { "sensore_1": 12.5, "sensore_2": 8.3 } } ``` ### Flusso Allarme 1. Sistema centralizzato pubblica su MQTT 2. Backend riceve messaggio e lo valida 3. Salva allarme nel database 4. Recupera utenti del cliente associato 5. Invia notifica push tramite FCM a tutti i dispositivi ## Notifiche Push (FCM) ### Priorità - **CRITICAL**: Notifica con suono, vibrazione, priorità massima - **WARNING**: Notifica standard - **INFO**: Notifica silenziosa, solo badge ### Payload Notifica ```json { "notification": { "title": "CRITICAL: Ponte Morandi", "body": "Movimento terreno rilevato" }, "data": { "alarm_id": "456", "sito_id": "123", "sito_nome": "Ponte Morandi", "tipo": "movimento_terreno", "severita": "critical", "timestamp": "2025-10-18T10:30:00Z" } } ``` ## Testing ### Test Manuale MQTT ```bash # Pubblica un messaggio di test mosquitto_pub -h localhost -t "terrain/alarms/123" -m '{ "sito_id": 123, "tipo": "movimento_terreno", "severita": "critical", "titolo": "Test allarme", "descrizione": "Questo è un test", "valore_rilevato": 15.0, "valore_soglia": 10.0, "unita_misura": "mm", "timestamp": "2025-10-18T10:30:00Z" }' ``` ### Test API ```bash # Login curl -X POST http://localhost:8000/auth/login \ -H "Content-Type: application/json" \ -d '{"email": "user@example.com", "password": "password"}' # Lista allarmi curl -X GET http://localhost:8000/allarmi \ -H "Authorization: Bearer YOUR_TOKEN" ``` ## Deployment ### Produzione con Docker ```dockerfile FROM python:3.12-slim WORKDIR /app COPY pyproject.toml . RUN pip install -e . COPY . . CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"] ``` ### Variabili d'Ambiente Produzione ```env DEBUG=False DATABASE_URL=postgresql://user:pass@db-host:5432/terrain_monitor SECRET_KEY=chiave-molto-forte-e-casuale MQTT_BROKER_HOST=mqtt.example.com MQTT_USERNAME=username MQTT_PASSWORD=password ``` ## Sicurezza - **JWT Tokens**: Autenticazione stateless - **Password Hashing**: bcrypt - **Multi-tenant**: Isolamento dati per cliente - **CORS**: Configurabile per domini specifici - **HTTPS**: Obbligatorio in produzione ## Sviluppi Futuri - [ ] WebSocket per notifiche real-time in web app - [ ] Rate limiting su API - [ ] Grafici e analytics allarmi - [ ] Export dati (CSV, PDF) - [ ] Sistema di escalation automatica - [ ] Integrazione con sistemi esterni (email, SMS) ## Licenza MIT License - Vedi file LICENSE per dettagli