download-dati-centraline/CLAUDE.md

# CLAUDE.md — Portale Centraline 37100lab

## Lingua

Tutto il progetto deve essere in **italiano**: commenti nel codice, messaggi
all'utente, testo dell'interfaccia, documentazione interna, messaggi di errore,
label dei pulsanti, intestazioni CSV.

Fanno eccezione — e restano in inglese — i nomi di variabili, funzioni,
componenti, file, classi CSS, e qualsiasi termine tecnico consolidato (es.
`fetch`, `endpoint`, `build`, `download`, `timestamp`).

---

## Panoramica

Portale web per visualizzare le centraline di monitoraggio ambientale di
37100lab e scaricare i dati storici come archivio ZIP contenente CSV.

**Stack**: SvelteKit + Vite + TypeScript. La lista centraline viene caricata
lato server al page load (`+page.server.ts`); le richieste di misurazioni
vengono instradate attraverso una route API interna (`/api/get_station_data`)
che funge da proxy verso il backend esterno, aggiungendo sanitizzazione e
cache HTTP.

**Ambiente di sviluppo**: Nix flake + Bun. Entrare nell'ambiente con
`nix develop`, poi usare i comandi `bun run dev`, `bun run build`,
`bun run preview`.

---

## Struttura del progetto

```
download-dati-centraline/
├── CLAUDE.md
├── package.json
├── svelte.config.js
├── vite.config.ts
├── tsconfig.json
├── flake.nix
├── static/
│   └── favicon.svg
└── src/
    ├── app.css            # variabili CSS globali, font, stili base
    ├── app.html           # template HTML (carica Poppins da Google Fonts)
    ├── app.d.ts
    ├── lib/
    │   ├── types.ts           # interfacce Station e Measurement
    │   ├── api.ts             # fetchStations, fetchDay
    │   ├── timezone.ts        # formatTimestampRome, formatDayParam, getDayRange
    │   ├── csv.ts             # buildCsv, downloadBlob, buildDayFilename, buildZipFilename
    │   ├── download-pool.ts   # coda di download con concorrenza limitata
    │   ├── groups.json        # raggruppamento centraline per area geografica
    │   └── components/
    │       ├── StationList.svelte
    │       └── StationRow.svelte
    └── routes/
        ├── +layout.svelte         # importa app.css
        ├── +page.svelte           # pagina principale
        ├── +page.server.ts        # carica la lista centraline lato server
        └── api/
            └── get_station_data/
                └── +server.ts     # proxy verso il backend esterno
```

---

## API esterna

**Base URL**: `http://37100lab.it:8101`

Il frontend non chiama mai direttamente il backend esterno per le misurazioni:
usa la route interna `/api/get_station_data` che fa da proxy (vedi sotto).
Solo `fetchStations` chiama direttamente il backend (dalla funzione `load`
di SvelteKit, lato server).

### GET `/api/campagne_map_data` — lista centraline

Risposta: GeoJSON. Le centraline si trovano in `.features[].properties`.

Campi rilevanti di ogni `.properties`:

| Campo        | Tipo          | Note                                    |
|--------------|---------------|-----------------------------------------|
| `title`      | string        | Nome della centralina                   |
| `pk`         | string        | ID numerico, arriva come stringa        |
| `created_at` | ISO 8601 UTC  | Data/ora di creazione                   |
| `ended_at`   | string o null | Data/ora di fine; null se ancora attiva |

Il campo `pk` va convertito a numero intero.

### GET `/api/get_measurements/{id}?day=YYYY-M-D` — misurazioni giornaliere

- `{id}`: ID numerico della centralina
- `day`: data in **`Europe/Rome`**, formato **`YYYY-M-D` senza zero-padding**
  - ✅ `2026-5-6`
  - ❌ `2026-05-06`

La risposta contiene una chiave `misure` con un array di oggetti, oppure un
array vuoto. Il backend può emettere `NaN`/`Infinity` come valori JSON non
standard — il proxy li sostituisce con `null` prima di parsare.

| Campo  | Tipo    | Descrizione           |
|--------|---------|-----------------------|
| `temp` | number  | Temperatura (°C)      |
| `umid` | number  | Umidità relativa (%)  |
| `pm10` | number  | PM10 (µg/m³)          |
| `time` | ISO UTC | Timestamp misurazione |

---

## Route API interna: `/api/get_station_data`

`src/routes/api/get_station_data/+server.ts`

Parametri query: `id` (numero) e `date` (formato `YYYY-MM-DD` con zero-padding).

Comportamento:
1. Converte `date` in `YYYY-M-D` senza zero-padding prima di chiamare il backend.
2. Sostituisce `NaN`/`Infinity`/`-inf` con `null` nella risposta grezza.
3. Filtra le misurazioni con `time` non valido o oggetti `null`.
4. Aggiunge header `Cache-Control`: **1 settimana** per giorni precedenti a ieri,
   **60 secondi** per ieri e oggi. In `dev`, usa `no-store`.

Il client chiama questa route passando `date` in formato `YYYY-MM-DD`; la route
si occupa della conversione al formato del backend.

---

## Formato archivio ZIP

Il download produce un file `.zip` contenente:

- **Un CSV per ogni giorno** con misurazioni, senza colonna Data:
  ```
  "Ora","Temperatura","Umidità","PM10"
  "22:00:53",13.45,89.22,16.3
  ```
  Nome file: `YYYY-MM-DD.csv`

- **Un CSV combinato** con tutte le misurazioni, con colonna Data:
  ```
  "Data","Ora","Temperatura","Umidità","PM10"
  "05/05/2026","22:00:53",13.45,89.22,16.3
  ```
  Nome file: `{NomeCentralina}_(id).csv`

Nome del file ZIP: `{NomeCentralina}_(id).zip`
Esempio: `FabLab_Mantova_(178).zip`
Sanitizzazione: spazi → `_`, caratteri non alfanumerici (eccetto `_`) rimossi.

### Caratteristiche CSV

| Caratteristica    | Valore                                                       |
|-------------------|--------------------------------------------------------------|
| Encoding          | **UTF-8 con BOM** (``) — necessario per Excel italiano |
| Separatore        | virgola                                                      |
| Intestazioni      | tra doppi apici, prima riga                                  |
| Colonna Data      | stringa tra doppi apici, formato `DD/MM/YYYY`                |
| Colonna Ora       | stringa tra doppi apici, formato `HH:MM:SS` (senza decimali) |
| Colonne numeriche | senza apici, valori originali (non arrotondare)              |
| Timestamp         | convertito da UTC a **Europe/Rome** (gestisce ora legale)    |

Libreria di compressione: `jszip` (unica dipendenza runtime).

---

## Moduli

### `lib/types.ts`

Interfacce TypeScript condivise: `Station` e `Measurement`.

### `lib/api.ts`

- **`fetchStations(fetch?)`**: carica la lista centraline dal backend esterno.
  Accetta il `fetch` di SvelteKit per il SSR. Lancia eccezione in caso di
  errore (gestita da `+page.server.ts`). Ordina per `pk` decrescente.

- **`fetchDay(id, day, signal)`**: scarica le misurazioni di un giorno
  chiamando la route interna `/api/get_station_data?id=…&date=YYYY-MM-DD`.
  Accetta un `AbortSignal`; ritenta fino a 3 volte in caso di errore; restituisce
  sempre `[]` in caso di errore o abort (non lancia mai eccezioni).

### `lib/timezone.ts`

Gestisce date e timezone senza librerie esterne.

- **`formatTimestampRome(isoString)`**: converte un timestamp ISO UTC nel formato
  `DD/MM/YYYY HH:MM:SS.s`. Usa un offset cache (per ora UTC) per evitare chiamate
  ripetute a `Intl.DateTimeFormat`. Il decimale dei secondi è troncato (non
  arrotondato): `706ms → .7`.

- **`formatDayParam(date)`**: restituisce la data locale Europe/Rome nel formato
  `YYYY-M-D` senza zero-padding, tramite `Intl.DateTimeFormat` con
  `formatToParts`.

- **`getDayRange(startIsoUtc, endIsoUtc)`**: restituisce un array di `Date`,
  uno per ogni giorno dal giorno di `startIsoUtc` al giorno di `endIsoUtc`
  (estremi inclusi) in `Europe/Rome`. Se `endIsoUtc` è `null`, il limite
  superiore è oggi. Usa **mezzogiorno UTC** (`T12:00:00Z`) come ancora giornaliera
  per non attraversare mai un cambio di data locale.

### `lib/csv.ts`

- **`buildCsv(measurements, includeDate?)`**: costruisce la stringa CSV con BOM.
  Se `includeDate` è `true` (default), include la colonna "Data"; altrimenti solo
  "Ora". L'ora è troncata ai secondi (niente decimali).

- **`downloadBlob(blob, filename)`**: crea un URL oggetto, simula il click su un
  link `<a download>`, poi revoca l'URL.

- **`buildDayFilename(date)`**: restituisce `YYYY-MM-DD.csv` in `Europe/Rome`.

- **`buildZipFilename(title, id)`**: sanitizza il nome e restituisce
  `{NomeSanitizzato}_(id).zip`.

### `lib/download-pool.ts`

Pool di concorrenza per le richieste HTTP di download. Costante
`DOWNLOAD_WORKERS = 3` (richieste parallele massime). La funzione `enqueue(fn)`
accoda un'operazione e restituisce una `Promise` che si risolve al termine.
Gestisce internamente la coda FIFO e il contatore di worker attivi.

### `lib/groups.json`

Array di oggetti `{ name, ids[] }` che mappa nomi di aree geografiche a set di
ID centralina. Usato da `StationList` per raggruppare le card. Le centraline non
presenti in nessun gruppo finiscono nella sezione "Altre".

---

## Componenti

### `routes/+page.server.ts`

Funzione `load` di SvelteKit: chiama `fetchStations` lato server al page load.
In caso di errore restituisce `{ stations: [], loadError: '…' }`.

### `routes/+page.svelte`

Pagina principale. Riceve `data` da `+page.server.ts`. Mostra il messaggio di
errore se presente, altrimenti renderizza `StationList`. Contiene header e footer.

### `StationList.svelte`

Raggruppa le centraline in sezioni usando `groups.json`. All'interno di ogni
sezione, ordina: attive prima delle terminate, poi per `created_at` decrescente.
Le centraline non in nessun gruppo vanno nella sezione "Altre". Sezioni vuote
vengono omesse.

### `StationRow.svelte`

Card di una singola centralina. Contiene tutta la logica di download:

1. Calcola il range di giorni con `getDayRange` (limite superiore: `ended_at` o
   oggi per le attive).
2. Scarica tutti i giorni **in parallelo** tramite `enqueue` dal pool
   (max 3 richieste simultanee) con `Promise.all`.
3. La cancellazione avviene tramite `AbortController`: `controller.abort()`
   interrompe le fetch in corso; `fetchDay` intercetta `AbortError` e ritorna `[]`.
4. Tiene traccia del progresso con i contatori `currentDay` / `totalDays`
   (incrementati al completamento di ogni giorno).
5. Al completamento di tutte le fetch (non cancellate), genera lo ZIP con `jszip`
   e lo scarica.
6. Il pulsante di download mostra uno spinner durante il fetch; al hover diventa
   un'icona ✕ per annullare. Al completamento mostra un segno di spunta verde per
   2 secondi.
7. La barra di progresso (3px, fondo card) si colora di verde al completamento e
   di rosso se annullata.
8. In `onDestroy`, chiama `controller?.abort()` per pulire fetch pendenti se il
   componente viene smontato.

Il tooltip sulla data di fine centralina è implementato come Svelte action
(`floatingTooltip`) che crea/rimuove un `div` nel `document.body` — necessario
perché la card ha `overflow: hidden` e non può contenere il tooltip.

---

## Edge case e comportamenti attesi

| Situazione                                    | Comportamento                                                              |
|-----------------------------------------------|----------------------------------------------------------------------------|
| Giorno senza misurazioni (`misure: []`)       | Ignorare, il giorno non contribuisce allo ZIP                              |
| Errore HTTP su un singolo giorno              | `fetchDay` restituisce `[]` dopo 3 tentativi, ignorare e continuare        |
| Download annullato dall'utente                | `AbortController` interrompe le fetch, nessun file scaricato               |
| Nessuna misurazione dopo tutti i giorni       | Non generare lo ZIP, nessun download                                       |
| Centralina attiva (`ended_at: null`)          | Range: da `created_at` a **oggi** in Europe/Rome                           |
| Centralina terminata (`ended_at` valorizzato) | Range: da `created_at` a **`ended_at`** in Europe/Rome                     |
| Nome centralina con caratteri speciali        | Sanitizzare per il nome file: spazi → `_`, resto rimosso                   |
| Errore nel caricamento della lista            | `+page.svelte` mostra un messaggio di errore                               |
| Backend emette `NaN`/`Infinity`               | Il proxy li sostituisce con `null` con regex prima del parse               |
| Timestamp non valido nella risposta           | `+server.ts` filtra le misurazioni con `time` non parsabile                |

---

## Design

Font: **Poppins** (Google Fonts, pesi 400/500/600/700).

Palette (variabili CSS in `app.css`):

| Variabile     | Valore    | Uso                              |
|---------------|-----------|----------------------------------|
| `--bg`        | `#f0f2f5` | sfondo pagina                    |
| `--surface`   | `#ffffff`  | sfondo card                      |
| `--border`    | `#dde1e7` | bordi                            |
| `--text`      | `#374151` | testo normale                    |
| `--text-dim`  | `#9ca3af` | testo secondario                 |
| `--text-hi`   | `#111827` | testo in evidenza                |
| `--accent`    | `#2563eb` | blu (link, attivo, progresso)    |

Il layout usa card arrotondate (`border-radius: 14px`) al posto di una tabella.
Le centraline attive sono in evidenza rispetto alle terminate. Il nome è un link
alla pagina della centralina sul backend (`/campagna/{pk}`).