# Quick Start Guide - Terrain Monitor

Guida rapida per avviare il sistema di monitoraggio terreni in locale.

## Prerequisiti

- Python 3.12+
- Docker e Docker Compose
- Account Firebase (gratuito)

## Setup in 5 Passi

### 1. Clona e Prepara Ambiente

```bash
# Entra nella directory del progetto
cd web-app-python

# Crea virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# Installa dipendenze
pip install -e .
```

### 2. Avvia Infrastruttura (PostgreSQL + MQTT)

```bash
# Avvia database e broker MQTT
docker-compose up -d

# Verifica che siano in esecuzione
docker-compose ps
```

Servizi disponibili:
- PostgreSQL: `localhost:5432`
- MQTT Broker: `localhost:1883`
- pgAdmin: http://localhost:5050 (user: admin@terrain.local, pwd: admin)

### 3. Configura Firebase

1. Vai su https://console.firebase.google.com/
2. Crea nuovo progetto "Terrain Monitor"
3. Abilita Cloud Messaging
4. Scarica credenziali:
   - ⚙️ Settings → Service Accounts
   - "Generate new private key"
   - Salva come `firebase-credentials.json` nella root

### 4. Configura Variabili d'Ambiente

```bash
# Copia template
cp .env.example .env

# Modifica .env (usa questi valori per local development)
nano .env
```

```env
DATABASE_URL=postgresql://terrain_user:terrain_pass@localhost:5432/terrain_monitor
SECRET_KEY=dev-secret-key-change-in-production-minimum-32-chars
MQTT_BROKER_HOST=localhost
MQTT_BROKER_PORT=1883
MQTT_TOPIC=terrain/alarms/#
FIREBASE_CREDENTIALS_PATH=./firebase-credentials.json
DEBUG=True
```

### 5. Inizializza Database e Avvia Server

```bash
# Inizializza database con dati di esempio
python scripts/init_db.py

# Avvia il server FastAPI
python main.py
```

Server disponibile su: http://localhost:8000

## Test del Sistema

### 1. Verifica API

Apri http://localhost:8000/docs per la documentazione interattiva Swagger.

### 2. Login

```bash
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@azienda.it",
    "password": "admin123"
  }'
```

Salva il token restituito.

### 3. Test Allarme MQTT

In un nuovo terminale:

```bash
# Attiva virtual environment
source .venv/bin/activate

# Invia allarme di test
python scripts/test_mqtt.py
```

Dovresti vedere:
1. ✓ Log nel backend che riceve l'allarme
2. ✓ Nuovo record nella tabella `allarmi`
3. ✓ Notifica push inviata (se hai configurato FCM token)

### 4. Verifica Allarmi via API

```bash
curl -X GET http://localhost:8000/allarmi \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Credenziali Utenti Demo

Dopo `init_db.py` avrai questi utenti:

| Email | Password | Ruolo |
|-------|----------|-------|
| admin@azienda.it | admin123 | Admin |
| operatore@azienda.it | operatore123 | Operatore |
| viewer@azienda.it | viewer123 | Visualizzatore |

## Siti Monitorati Demo

1. **Ponte Morandi** (ID: 1) - Genova
2. **Galleria San Boldo** (ID: 2) - Treviso
3. **Diga del Vajont** (ID: 3) - Pordenone
4. **Versante Cà di Sotto** (ID: 4) - Parma

## Struttura Allarme MQTT

Per inviare allarmi personalizzati via MQTT:

```bash
mosquitto_pub -h localhost -t "terrain/alarms/1" -m '{
  "sito_id": 1,
  "tipo": "movimento_terreno",
  "severita": "critical",
  "titolo": "Movimento rilevato",
  "descrizione": "Movimento anomalo di 15mm",
  "valore_rilevato": 15.0,
  "valore_soglia": 10.0,
  "unita_misura": "mm",
  "timestamp": "2025-10-18T10:30:00Z",
  "dati_sensori": {
    "sensore_1": 15.0,
    "sensore_2": 12.3
  }
}'
```

## Monitoraggio Logs

```bash
# Backend logs
# Visibili nel terminale dove hai eseguito python main.py

# MQTT broker logs
docker-compose logs -f mosquitto

# Database logs
docker-compose logs -f postgres
```

## Stop e Cleanup

```bash
# Ferma il server FastAPI
Ctrl+C nel terminale

# Ferma i container Docker
docker-compose down

# Rimuovi anche i dati (ATTENZIONE: cancella il database!)
docker-compose down -v
```

## Troubleshooting

### Errore: "Connection refused" su PostgreSQL
```bash
# Verifica che il container sia in esecuzione
docker-compose ps

# Riavvia PostgreSQL
docker-compose restart postgres
```

### Errore: "Firebase credentials not found"
```bash
# Verifica che il file esista
ls -la firebase-credentials.json

# Controlla il path in .env
cat .env | grep FIREBASE
```

### MQTT non riceve messaggi
```bash
# Testa la connessione MQTT
mosquitto_sub -h localhost -t "terrain/alarms/#" -v

# In un altro terminale, pubblica un test
mosquitto_pub -h localhost -t "terrain/alarms/test" -m "hello"
```

## Prossimi Passi

1. **App Mobile**: Sviluppa client Flutter/React Native
2. **Integrazione**: Connetti il tuo sistema di monitoraggio reale
3. **Deployment**: Usa Docker per deployare in produzione
4. **Sicurezza**: Configura MQTT con autenticazione
5. **Monitoring**: Aggiungi logging e metriche

## Risorse

- FastAPI Docs: https://fastapi.tiangolo.com/
- Firebase FCM: https://firebase.google.com/docs/cloud-messaging
- MQTT Protocol: https://mqtt.org/
- SQLAlchemy: https://docs.sqlalchemy.org/

## Supporto

Per problemi o domande, consulta il [README.md](README.md) completo.