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.