harbour-aira/docs/PIANO.md

# harbour-aira — app Sailfish per la pompa di calore Aira

Piano scritto il 9 ottobre 2026, prima di scrivere la UI (convenzione di lavoro).

## 1. Stato verificato sul campo

| Cosa | Esito |
|---|---|
| Accesso cloud Aira | **funziona** — `pyairahome` 2.3.0, pool Cognito `eu-north-1_cnqyjWtbz` (indice 0), token salvati in `~/.hermes/profiles/carlo/aira_tokens.json` (600) |
| Lettura impianto | **funziona** — esterna, interna, ACS attuale/obiettivo, modalità, curve zone, firmware, errori |
| Bridge HTTP sul server | **scritto e provato** — `~/workspace/Carlo/Aira/aira_bridge.py`, v**0.3.0** (servizio systemd utente attivo) |
| Bluetooth sul server | **assente** — nessun adattatore HCI (esclude la via locale BLE su questa macchina) |
| SDK Sailfish (`sfdk`) | **assente qui** — build e deploy li fa Carlo dal suo PC |
| Jolla Phone 2026 | non raggiungibile dalla rete del server: deploy solo dal PC |

## 2. Perché serve un bridge e non una chiamata diretta

Il cloud Aira espone **gRPC su HTTP/2**. Qt 5.6 — il toolkit su cui gira Sailfish —
**non ha HTTP/2**, quindi un'app nativa non può parlarci direttamente. Vie alternative
valutate e scartate:

- **PyOtherSide + pyairahome dentro l'app**: servirebbe impacchettare `grpcio` e `bleak`
  compilati per aarch64/SFOS, con l'RPM che diventa fragile a ogni aggiornamento.
- **Cognito + gRPC riscritti in C++**: HTTP/2 e protobuf da zero. Molto lavoro, molto rischio.

Scelta: **la logica resta sul server** (dove Python e i token già funzionano), l'app è un
client sottile. Vantaggio collaterale: credenziali e token non stanno mai sul telefono.

```
 Jolla (QML/C++ Qt 5.6)  --HTTP/1.1 + JSON-->  bridge sul server  --gRPC-->  cloud Aira
                                              (pyairahome + token)
```

## 3. Protocollo del bridge (v1 — già implementato)

Autenticazione: `Authorization: Bearer <token>` su tutto tranne `/health`.
Token generato al primo avvio in `~/.hermes/profiles/carlo/aira_bridge.json` (600).

| Metodo | Rotta | Risposta |
|---|---|---|
| GET | `/health` | `{ok, version}` — nessuna auth, per la diagnostica |
| GET | `/summary` | valori leggibili: temperature, ACS, modalità, flag, errori |
| GET | `/state` | stato completo grezzo (42 campi) |
| GET | `/commands` | elenco comandi ammessi + parametri |
| POST | `/command` | `{"id": "...", "value": ...}` |

Comandi ammessi in v1: `ping`, `set_hot_water_target` (45–60 °C), `hot_water_boost_on/off`,
`hot_water_heating_on/off`, `away_mode_on/off`, `night_mode_1h`, `force_heating_on/off`,
`heating_on/off`, `legionella_cycle`.

**Whitelist voluta**: la libreria espone ~90 comandi, inclusi `FactoryReset`,
`InstallFirmware`, `RebootDevice`, `RotateCertificate`. Quelli restano fuori di proposito:
un client mobile non deve poter riformattare l'impianto per un tap sbagliato.

## 4. Architettura dell'app

- `harbour-aira.pro` / `rpm/` / `icons/` dai template consolidati della skill.
- **C++ minimo**: `Settings` (QSettings su `AppConfigLocation`, obbligatorio per la sandbox
  SailJail) e `ApiClient` (QNetworkAccessManager + watchdog di timeout 15 s, JSON parsing).
  Esposti come context properties: `appSettings`, `api`.
- **QML**: `MainPage` (dashboard), `SettingsPage` (indirizzo bridge + token), `CoverPage`.
- Nessun dato personale nel binario: indirizzo e token si configurano nell'app
  (le repo sono pubbliche su Gitea).

## 5. Fasi

- **F0 — ponte (fatto)**: bridge scritto, provato su `/health`, `/summary`, `/commands`,
  errori 400/401 verificati. Nessun comando inviato all'impianto.
- **F1 — v0.1 in sola lettura (fatto)**: dashboard con esterna/interna/ACS, modalità, stato ACS,
  pull-to-refresh, copertina con le temperature.
- **F2 — comandi (fatto in v0.1)**: obiettivo ACS (slider 45–60), boost on/off, con conferma
  `RemorseItem`. Gli altri comandi della whitelist restano raggiungibili dal bridge ma non
  hanno ancora un pulsante nell'app.
- **F3 — servizio e rete**: unità systemd per il bridge (avvio automatico), accesso dal
  telefono. *Decisione dell'utente: per ora solo rete locale* — quindi l'indirizzo del bridge
  è l'IP del server in LAN, e la copertura fuori casa si affronta più avanti (VPN WireGuard
  già attiva, oppure sottodominio HTTPS).

## 5-bis. Consegna del 9 ottobre 2026 (sera)

Stato: progetto completo in `~/workspace/Carlo/AppSailfish/harbour-aira`
(commit iniziale, 27 file) e tarball `AppSailfish/pacchetti/harbour-aira-0.1.0.tar.gz`.

Verificato qui, senza SDK:
- nucleo puro (`src/airajson.cpp`): **26/26** verifiche superate con l'harness Qt 5.15;
- compilazione del nucleo **senza warning** (`-Wall -Wextra`);
- `qmllint` sui 6 file QML: nessun errore oltre ai moduli Silica assenti (atteso senza SDK).

Non verificabile qui (serve il suo PC + il telefono): build RPM, istallazione, UI reale.


## 5-ter. Aggiornamento del 10 ottobre 2026 — v0.2.0 (riscaldamento)

- **Bridge 0.2.0**: comandi `set_heating_setpoint` e `set_cooling_setpoint` (5–30 °C, zona
  opzionale 1 o 2) e campi `zone1_*` / `zone2_*` nel riassunto. Il messaggio
  `ZoneTemperatures` va inviato **completo**: la zona non toccata viaggia col suo valore
  attuale (letto dall'ultimo stato, tenuto in cache nella sessione), altrimenti a zero
  verrebbe spenta. Verifica: `test_bridge_commands.py`, **19/19**, nessun comando inviato
  all'impianto.
- **App 0.2.0**: sezione "Riscaldamento" nella dashboard (temperatura in casa, obiettivo,
  stato zona, slider 5–30 °C a passi di 0,5 con conferma) e copertina con la temperatura di
  casa. Aggiunte le etichette per gli stati `PUMP_MODE_STATE_*`. Nucleo: **29/29**.
- **Bridge 0.3.0 + App 0.3.0**: pagina **"Altri comandi"** nell'app (dalla tendina in
  alto o dal pulsante in fondo alla home) con assenza, night mode un'ora, riscaldamento
  forzato on/off, funzione riscaldamento on/off, ciclo antilegionella, riscaldamento ACS
  on/off e verifica impianto; i comandi che durano (forzato, legionella, disabilitazioni)
  chiedono conferma. In cima alla pagina lo **stato attuale**, così non si preme alla
  cieca. **Bug corretto nello stesso giro**: `force_heating` nello stato è un oggetto
  `{enabled, remaining_time}`, e il bridge lo leggeva con `bool()` — sempre vero. Ora si
  legge il campo `enabled`; il test lo copre (27/27). Nucleo app: **31/31**.
- **App 0.2.1** (richiesta dell'utente): la temperatura della casa diventa il dato
  principale **in cima** alla home (valore grande, barra, obiettivo, slider e pulsante),
  l'acqua calda sanitaria scende in una propria sezione sotto, lo stato impianto va in
  fondo. Stessa gerarchia nella copertina: casa in grande, ACS in una riga secondaria.
- **F3 fatto**: `harbour-aira-bridge.service` (systemd utente, `enable --now`, parte al boot
  grazie a `Linger=yes`, `Restart=on-failure` verificato con SIGKILL → riparte in ~10 s) e
  regola `52-aira-bridge-lan.conf` in `/etc/nftables.d/`. Il firewall YunoHost ha
  `policy drop` e apriva solo 22/25/53/80/443/587/993/5349/5350: la 8790 va aperta a mano,
  solo per LAN e VPN. *Lezione*: un test da `127.0.0.1` non attraversa quelle regole e non
  rivela il problema — va provato dalla LAN.

- **App 0.4.0 — localizzazione ita/eng** (richiesta dell'utente): l'interfaccia si
  può mettere in italiano o inglese **dalle impostazioni**; di serie segue la lingua
  del sistema, con **ripiego sull'inglese**. L'inglese è la lingua sorgente delle
  stringhe (restano nel codice), l'italiano sta in `translations/harbour-aira-it.ts`
  (**99 stringhe**, aggiornate con `lupdate` e compilate da `lrelease` in build).
  Nuova classe `Translator` (`src/translator.{h,cpp}`): risolve la lingua **prima**
  di `createView`, così le `qsTr()` del QML nascono già tradotte, e allinea
  `QLocale::setDefault` alla lingua scelta — così i numeri seguono la lingua
  (`23,0 °C` in italiano, `23.0 °C` in inglese): le temperature si formattano in
  `ApiClient::formatValue`, non più con il `toFixed()` di JavaScript, che avrebbe
  sempre messo il punto. *Vincolo di piattaforma*: **Qt 5.6 non ha
  `QQmlEngine::retranslate()`** (arriva con Qt 5.10), quindi installare il
  traduttore non ritraduce ciò che è già a schermo: al cambio lingua l'app
  **ricarica la radice QML**. *Trappola di `lupdate`*: riconosce solo le funzioni di
  traduzione note (`tr()`, `QCoreApplication::translate()`), **non una funzione
  wrapper scritta da noi** — le etichette di `airajson.cpp` sono quindi chiamate
  `QCoreApplication::translate("AiraJson", …)` per esteso, altrimenti sparirebbero
  dal catalogo. Nucleo app: **39/39** (le attese sono cambiate in inglese e il test
  carica il `.qm` vero come fa `main.cpp`, verificando entrambe le lingue, il
  ripiego e i formati numerici). Anteprime rigenerate in **due lingue**
  (`docs/anteprima/` inglese, `docs/anteprima/it/` italiano), impostazioni comprese
  la nuova riga della lingua.

## 6. Rischi noti

- **Dipendenza dal server**: se il bridge è spento, l'app non vede nulla. Mitigazione: unità
  systemd con riavvio automatico (F3).
- **Scadenza credenziali**: i token Cognito si rinnovano da soli per settimane; quando il
  refresh token scade serve rilanciare `setup_creds.py` sul server. L'app deve mostrare un
  errore chiaro, non un retry infinito.
- **Assenza di test sulla UI**: senza SDK né device raggiungibile da qui, la UI Silica si
  verifica solo sul telefono di Carlo (ciclo consolidato: io consegno il tarball, lui compila
  e incolla i log).
- **Token del bridge**: è l'unica credenziale sul telefono; va trattato come una password e
  revocabile rigenerando `aira_bridge.json`.

## 7. Decisioni aperte

1. **Come raggiungere il bridge dal telefono**: VPN WireGuard (già attiva, zero configurazione
   nuova) oppure sottodominio HTTPS pubblico con reverse proxy.
2. **Ambito della v0.1**: sola lettura (consigliata) oppure lettura + comandi ACS subito.
3. **Nome visibile dell'app**: default proposto "Aira" (pacchetto `harbour-aira`).