# Gateway letture acqua

## Obiettivo

NetGescon puo ricevere letture cumulative dei contatori acqua da un gateway esterno e salvarle nello stesso archivio operativo usato da `servizi-utenze` e dalla scheda `unita-immobiliare`.

## Configurazione

Impostare un token condiviso nell'ambiente applicativo:

```env
WATER_GATEWAY_TOKEN=<token-gateway>
```

Il gateway deve inviare il token in uno di questi modi:

- header `X-Netgescon-Water-Token`
- bearer token `Authorization: Bearer ...`
- query string `?token=...`

In ambiente non locale, se il token non e configurato l'endpoint risponde `503`.

## Endpoint

```http
POST /api/netgescon/v1/water-meter/readings
Content-Type: application/json
X-Netgescon-Water-Token: <token-gateway>
```

Payload minimo:

```json
{
  "device_id": "GW-ACEA-0001",
  "serial": "WTTS115224000400",
  "value": 123.456,
  "read_at": "2026-06-27T10:00:00+02:00",
  "unit": "mc"
}
```

Campi accettati:

- `device_id`: identificativo dispositivo gateway, preferenziale per aggancio unita;
- `serial`: seriale/matricola contatore acqua dell'unita;
- `unita_id`: opzionale, utile per test o gateway gia mappati;
- `value`: lettura cumulativa;
- `read_at`: data/ora lettura;
- `unit`: unita di misura, default `mc`;
- `battery`, `rssi`, `payload`: dati diagnostici opzionali.

## Aggancio unita

La scheda `admin-filament/unita-immobiliare?unita_id=...` espone in modifica:

- `acqua_contatore_seriale`
- `acqua_gateway_device_id`

L'API cerca l'unita in questo ordine:

1. `unita_id`, se inviato;
2. `acqua_gateway_device_id = device_id`;
3. `acqua_contatore_seriale = serial`.

Se l'unita viene trovata e non esiste ancora un servizio acqua attivo nello stabile, viene creato un servizio `Acqua - gateway contatori`.

## Salvataggio lettura

La lettura viene salvata in `stabile_servizio_letture` con:

- `canale_acquisizione = gateway`
- `rilevatore_tipo = gateway_iot`
- `lettura_fine = value`
- `lettura_inizio` e `lettura_precedente_valore` dalla lettura precedente della stessa unita/servizio
- `consumo_valore = max(0, lettura_fine - lettura_precedente)`
- `raw.source = water_meter_gateway`

Queste righe diventano visibili nella scheda unita e nella pagina `condomini/servizi-utenze`, e potranno essere confrontate con le fatture acqua/ACEA per riparti piu precisi.