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

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,