docs: pianifica stack fastapi uvicorn con api swagger

prd.md

@@ -11,7 +11,8 @@ La soluzione prevista e' un processo long-running eseguito in un container Docke
 - esegue periodicamente una query leggera di keep-alive;
 - registra esito e tempi di esecuzione;
 - salva i campioni di latenza/esito in un database RRD locale con finestra storica di 48 ore;
-- espone una webapp con vista storica in stile SmokePing;
+- espone una webapp con vista storica in stile SmokePing tramite backend FastAPI servito da Uvicorn;
+- espone API HTTP documentate automaticamente con Swagger/OpenAPI;
 - continua a funzionare finche' il container non viene fermato.
 
 ## 2. Problema
@@ -72,6 +73,12 @@ La soluzione target per questo repository e':
 - webapp per visualizzazione dello storico con UI ispirata a SmokePing;
 - configurazione tramite file `.env` e `.env.example`.
 
+Stack applicativo vincolata per la componente web:
+
+- FastAPI per endpoint API e documentazione OpenAPI;
+- Uvicorn come server ASGI runtime;
+- Swagger UI (endpoint `/docs`) e schema OpenAPI (endpoint `/openapi.json`).
+
 Alternative come GitHub Actions, `pg_cron` o cron esterni restano opzioni comparabili, ma non rappresentano la soluzione primaria di questo repository.
 
 ## 9. Assunzioni di Prodotto
@@ -191,6 +198,7 @@ Capacita' minime richieste:
 - grafico temporale con evidenza di latenza e fallimenti;
 - aggiornamento periodico automatico della vista senza riavvio del servizio;
 - accesso via porta HTTP configurabile.
+- implementazione obbligatoria con FastAPI + Uvicorn.
 
 ### RF14. API di lettura dello storico
 
@@ -202,7 +210,18 @@ Vincoli:
 - filtri minimi per finestra temporale entro il limite delle 48 ore;
 - risposta con formato stabile e documentato per supportare eventuali evoluzioni UI.
 
-### RF15. Continuita' operativa tra collector e UI
+### RF15. Documentazione API via Swagger/OpenAPI
+
+Le API devono essere auto-documentate tramite le funzionalita' native FastAPI.
+
+Capacita' minime richieste:
+
+- endpoint Swagger UI disponibile in `/docs`;
+- schema OpenAPI disponibile in `/openapi.json`;
+- descrizione chiara di parametri, risposta e codici errore degli endpoint principali;
+- coerenza tra comportamento effettivo e documentazione generata.
+
+### RF16. Continuita' operativa tra collector e UI
 
 Il collector di ping e la webapp devono convivere nello stesso servizio/container senza bloccare il loop di keep-alive.
 
@@ -240,6 +259,10 @@ Lo storage storico deve restare bounded: il database RRD deve mantenere esclusiv
 
 La webapp deve essere leggibile su desktop e mobile, con tempi di caricamento adeguati all'uso operativo (target iniziale: visualizzazione disponibile in pochi secondi su rete locale).
 
+### RNF8. Contratto API documentato
+
+La documentazione OpenAPI/Swagger deve essere sempre disponibile in ambiente runtime V1.1+ e deve riflettere fedelmente gli endpoint esposti.
+
 ## 12. Configurazione di Prodotto
 
 ### Variabili richieste
@@ -281,7 +304,8 @@ Componenti logici previsti:
 - database client: apre connessione ed esegue la query;
 - collector metriche: misura latenza/esito e normalizza i campioni;
 - storage RRD: persiste i campioni con retention circolare 48 ore;
-- API storico: espone i dati aggregati alla webapp in sola lettura;
+- API storico FastAPI: espone i dati aggregati alla webapp in sola lettura;
+- server Uvicorn: esegue l'app ASGI e pubblica endpoint API e docs Swagger;
 - web frontend: renderizza vista storica in stile SmokePing;
 - logger: stampa esiti ed errori su STDOUT/STDERR;
 - runtime Docker: mantiene il processo eseguito come container persistente.
@@ -381,7 +405,13 @@ Componenti logici previsti:
 - Esiste una webapp accessibile via HTTP che mostra andamento temporale di latenza ed errori.
 - La dashboard si aggiorna automaticamente e riflette i nuovi campioni senza riavvio.
 
-### AC9. Degrado controllato
+### AC9. API e Swagger operativi
+
+- Gli endpoint API principali sono serviti da FastAPI tramite Uvicorn.
+- L'endpoint `/docs` e' accessibile e mostra la documentazione Swagger UI.
+- L'endpoint `/openapi.json` e' accessibile e coerente con le API realmente disponibili.
+
+### AC10. Degrado controllato
 
 - Se il modulo UI fallisce temporaneamente, il collector continua a registrare campioni su RRD.
 - Se una misura fallisce, la dashboard mantiene lo storico precedente e rende visibile il fallimento del nuovo campione.
@@ -400,6 +430,12 @@ Componenti logici previsti:
 
 ### V1.1
 
+- Implementazione backend web con FastAPI servito da Uvicorn.
+- API read-only per storico RRD.
+- Documentazione API Swagger/OpenAPI esposta in runtime.
+
+### V1.1
+
 - Retry con backoff configurabile.
 - Miglioramento dei messaggi di health e startup.
 - Distinzione chiara tra errori di configurazione e di rete.

progress.md

@@ -13,6 +13,12 @@ Il progetto ha oggi:
 - `.env.example` completo;
 - `Dockerfile` e `docker-compose.yml`.
 
+Aggiornamento scope post-V1:
+
+- webapp storico connessione in stile SmokePing da implementare con FastAPI + Uvicorn;
+- API read-only dedicate allo storico;
+- documentazione API via Swagger/OpenAPI.
+
 ## Obiettivo di Sviluppo
 
 Realizzare un servizio Python dockerizzato che mantenga attivo un database Supabase free tier tramite query periodiche di keep-alive, con configurazione via `.env`, processo long-running e documentazione operativa essenziale.
@@ -230,6 +236,40 @@ Stato:
 
 - completata
 
+### Fase 7. Webapp storico con FastAPI, Uvicorn e Swagger
+
+Obiettivo:
+Implementare la componente web/API per visualizzare lo storico connessione (48 ore) in stile SmokePing, usando stack FastAPI + Uvicorn con documentazione Swagger/OpenAPI.
+
+Attivita':
+
+- integrare dipendenze FastAPI/Uvicorn nel progetto Python;
+- progettare endpoint API read-only per stato corrente e storico RRD 48h;
+- implementare backend FastAPI con validazione input e codici errore chiari;
+- esporre documentazione automatica Swagger (`/docs`) e schema OpenAPI (`/openapi.json`);
+- collegare la webapp allo strato API per rendering trend e fallimenti;
+- aggiornare Dockerfile e compose per runtime Uvicorn e porta HTTP configurabile;
+- allineare README, PRD, `.env.example` e note operative.
+
+Deliverable:
+
+- app FastAPI avviabile con Uvicorn;
+- endpoint API storico funzionanti;
+- Swagger UI e OpenAPI accessibili;
+- dashboard storica collegata ai dati RRD.
+
+Verifica:
+
+- avvio container e raggiungibilita' endpoint API;
+- verifica endpoint `/docs` e `/openapi.json`;
+- chiamata API con finestra temporale valida e risposta coerente;
+- riscontro visuale dashboard con nuovi campioni;
+- controllo che il collector keep-alive continui anche in caso di errore UI.
+
+Stato:
+
+- **pianificata**
+
 ## Backlog Post-V1
 
 - retry con backoff configurabile;
@@ -239,6 +279,12 @@ Stato:
 - metriche esportabili;
 - supporto a query alternativa di keep-alive con tabella di log.
 
+## Backlog Post-V1.1
+
+- autenticazione opzionale per endpoint dashboard/API;
+- downsampling avanzato per viste storiche aggiuntive oltre 48h;
+- export CSV/JSON dello storico per analisi esterne.
+
 ## Ordine di Esecuzione Consigliato
 
 1. Fase 0
@@ -248,6 +294,7 @@ Stato:
 5. Fase 4
 6. Fase 5
 7. Fase 6
+8. Fase 7
 
 ## Definizione di Done per la V1
 
@@ -263,6 +310,6 @@ La V1 e' completata quando:
 
 ## Prossima Attivita' Operativa
 
-Fasi 0-6 completate. V1 chiusa con test operativo end-to-end su pooler Supabase IPv4.
+Fasi 0-6 completate. Prossimo step: avvio Fase 7 per implementazione FastAPI + Uvicorn + API + Swagger della dashboard storico.
 
 Nota operativa: usare host pooler (`aws-1-eu-central-1.pooler.supabase.com`) su porta `6543` con utente `postgres.<project-ref>` per ambienti senza connettivita' IPv6.