documentazione 0.5.0: PROTOCOL (/stats, campi dispositivo), PIANO, conteggi dei test

bridge/requirements.txt

@@ -1,4 +1,4 @@
 # Dipendenze del bridge. La libreria parla gRPC con il cloud Aira e porta con
 # se' il resto (grpcio, protobuf, pycognito, boto3, bleak...).
-# Versione fissata: e' quella su cui il bridge e' stato provato (27/27).
+# Versione fissata: e' quella su cui il bridge e' stato provato (48/48).
 pyairahome==2.3.0

docs/PIANO.md

@@ -211,17 +211,23 @@ andrebbe disegnata a mano.
 2. **Dati**: "Il tuo riscaldamento (questo mese)" con calore prodotto, elettricità
    usata, efficienza (COP riscaldamento / acqua calda); "I tuoi risparmi" con il
    risparmio totale del periodo, la CO₂ evitata e il risparmio Smart Tariff Control.
-3. **Impianto**: stato (connessione, modalità, vacanza, messaggi luminosi, ultima
-   lettura), accessori (termostato: zona, temperatura, umidità, segnale, batteria),
-   versioni (piattaforma, connettività, controllo climatico, unità esterna, EEPROM,
-   dispositivo ID) ed errori.
+3. **Impianto**: stato (connessione, modalità, assenza, notte, riscaldamento forzato,
+   resistenza interna, temperature, zone, ultima lettura), accessori (termostato: zona,
+   temperatura, umidità, segnale, batteria, articolo), versioni (ID dispositivo,
+   piattaforma, connettività, controllo climatico, unità esterna, EEPROM) ed errori.
+   Le luci di firma (`signature_lights`, `led_pattern`) restano per ora solo in
+   `/summary`: la pagina non le mostra.
 
 ### Lavoro
 
 - **Bridge 0.4.0**: nuova rotta `/stats` (COP, risparmi, ottimizzazione, insight) e
-  blocco `device` in `/summary` (id breve, versioni, termostato, connessione);
-  cache breve lato bridge, perché sono chiamate al cloud più lente di `/state`.
-- **App 0.5.0**: `MainPage` riordinata, nuove `DataPage.qml` e `InfoPage.qml`,
-  nuove stringhe nei due cataloghi, anteprime rigenerate, test del nucleo estesi al
-  parsing dei nuovi campi, versione e README aggiornati.
+  campi del dispositivo in `/summary` (`device_*`, `version_*`, `thermostat_*`,
+  `connected_via`, `timezone`); cache di 10 minuti lato bridge, perché sono quattro
+  chiamate al cloud, più lente di `/state`.
+- **App 0.5.0**: `MainPage` riordinata, nuove `DataPage.qml` e `PlantPage.qml`
+  (quest'ultima si è chiamata `InfoPage` nella prima stesura del piano), nuovo
+  componente `ValueRow.qml`, 86 stringhe nuove tradotte (170 in totale), anteprime
+  rigenerate (dati, impianto) in italiano e inglese, test del nucleo estesi al
+  parsing delle statistiche e alla formattazione di importi e mesi (61/61), versione,
+  README e `docs/PROTOCOL.md` aggiornati.
 - Nessun comando nuovo all'impianto: tutto questo è **sola lettura**.

docs/PROTOCOL.md

@@ -16,7 +16,7 @@ Nessuna autenticazione: serve a distinguere "server irraggiungibile" da
 "token sbagliato".
 
 ```json
-{"ok": true, "version": "0.2.0"}
+{"ok": true, "version": "0.4.0"}
 ```
 
 ## GET /summary
@@ -54,11 +54,80 @@ Valori pronti per la dashboard.
     "zone2_mode": "PUMP_MODE_STATE_IDLE",
     "zone2_cooling_setpoint": 0.0,
     "errors_count": 0,
-    "pump_updated": "2026-10-09 18:52:17.199340"
+    "pump_updated": "2026-10-09 18:52:17.199340",
+
+    "device_id": "1f4b26",
+    "device_uuid": "1f4b26c4-1800-4b21-8ea2-236925a92aeb",
+    "version_platform": "6.10.0",
+    "version_connectivity": "3.30.1",
+    "version_climate_control": "3.9.12",
+    "version_outdoor_unit": "1.30.0",
+    "version_outdoor_eeprom": "0.114.0",
+    "connected_via": "Cloud",
+    "timezone": "Europe/Rome",
+    "thermostats_count": 1,
+    "thermostat_zone": 1,
+    "thermostat_article": "201884",
+    "thermostat_temperature": 22.8,
+    "thermostat_humidity": 73.3,
+    "thermostat_rssi": -79,
+    "thermostat_battery_low": false
   }
 }
 ```
 
+Il blocco del dispositivo serve alle pagine "Impianto" e "Accessori" dell'app:
+`device_id` sono le prime 6 cifre dell'UUID (come le mostra l'app ufficiale),
+`connected_via` è la via di connessione, le `version_*` sono le versioni del
+software e i campi `thermostat_*` descrivono il termostato a parete (assenti se
+l'impianto non ne ha: in quel caso `thermostats_count` è 0 e gli altri sono
+`null`). Il termostato manda i decimali come interi (228 = 22,8 °C): la
+conversione la fa il bridge, non l'app.
+
+## GET /stats
+
+I numeri che Aira calcola nel cloud: sono gli stessi della scheda "Dati"
+dell'app ufficiale (verificati sullo stesso periodo). Il bridge li tiene in
+cache per **10 minuti** (`ttl`), perché sono quattro chiamate e cambiano
+lentamente.
+
+```json
+{
+  "ok": true,
+  "stats": {
+    "period_days": 30,
+    "currency": "EUR",
+    "month": {
+      "label": "2026-10",
+      "heat_kwh": 70.8,
+      "energy_kwh": 29.3,
+      "cop_heating": null,
+      "cop_dhw": 4.42
+    },
+    "cop_monthly": [
+      {"month": "2026-09", "heating_cop": null, "dhw_cop": 4.42, "avg_outdoor": 21.8}
+    ],
+    "insights": [
+      {"date": "2026-10-01", "energy_kwh": 29.3, "heat_kwh": 70.8}
+    ],
+    "savings": {"amount": 21.78, "co2_kg": 38.1, "show": true, "points": 31},
+    "smart_tariff": {"amount": 2.71, "hours": 180},
+    "monthly_savings": [{"month": "2026-09", "amount": 3.52}]
+  }
+}
+```
+
+- `month`: l'ultimo periodo con dati — calore prodotto (`heat_kwh`), elettricità
+  usata (`energy_kwh`) ed efficienza (COP) di acqua calda e riscaldamento.
+  **`null` significa "nessun dato"**: su un impianto recente il riscaldamento può
+  non averne ancora (mentre l'acqua calda sì). `label` è il mese `AAAA-MM`.
+- `cop_monthly` e `monthly_savings`: le serie mese per mese, per il dettaglio.
+- `savings`: risparmio in bolletta sugli ultimi `period_days` giorni (30), CO₂
+  evitata e numero di punti usati dal calcolo; `show` è il permesso di Aira a
+  mostrare il dato.
+- `smart_tariff`: il risparmio del mese mobile dovuto allo Smart Tariff Control.
+- Questa rotta è di **sola lettura**: non invia nessun comando all'impianto.
+
 ## GET /state
 
 Stato completo e grezzo dal cloud (42 campi: curve climatiche per zona,