diff --git a/prd.md b/prd.md index 5cc2cd2..5cad75e 100644 --- a/prd.md +++ b/prd.md @@ -10,6 +10,8 @@ La soluzione prevista e' un processo long-running eseguito in un container Docke - si connette al database Supabase/PostgreSQL; - 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; - continua a funzionare finche' il container non viene fermato. ## 2. Problema @@ -32,6 +34,7 @@ Garantire che Supabase rilevi attivita' reale sul database almeno una volta entr - Mantenere il processo attivo in modo continuativo tramite container Docker. - Consentire configurazione interamente tramite `.env`. - Rendere il comportamento osservabile con log chiari di successo e fallimento. +- Rendere osservabile lo storico delle misure tramite una webapp con grafico temporale in stile SmokePing. - Mantenere la soluzione minimale, portabile e facile da eseguire su qualsiasi host con Docker. ## 5. Non-Obiettivi @@ -41,6 +44,7 @@ Garantire che Supabase rilevi attivita' reale sul database almeno una volta entr - Non deve gestire provisioning, creazione schema o migrazioni Supabase. - Non deve introdurre traffico aggressivo o pattern assimilabili ad abuso del free tier. - Non deve dipendere obbligatoriamente da GitHub Actions, servizi cron esterni o infrastrutture cloud aggiuntive. +- Non e' un sistema di osservabilita' multi-tenant o con retention storica di lungo periodo oltre 48 ore in V1. ## 6. Pubblico di Riferimento @@ -64,6 +68,8 @@ La soluzione target per questo repository e': - loop applicativo continuo; - connessione diretta a PostgreSQL/Supabase; - query di keep-alive configurabile; +- persistenza campioni in database RRD locale con retention fissa a 48 ore; +- webapp per visualizzazione dello storico con UI ispirata a SmokePing; - configurazione tramite file `.env` e `.env.example`. Alternative come GitHub Actions, `pg_cron` o cron esterni restano opzioni comparabili, ma non rappresentano la soluzione primaria di questo repository. @@ -164,6 +170,44 @@ La notifica all'utente in caso di fallimento e' opzionale in prima versione. Per la V1, il requisito minimo e' il logging locale/STDOUT. In versioni successive, potranno essere introdotte integrazioni opzionali come email, webhook o Telegram. +### RF12. Persistenza storica su database RRD (48 ore) + +Il sistema deve salvare a ogni ciclo un campione di connettivita' in un database RRD locale. + +Vincoli obbligatori: + +- retention dimensionata per una finestra storica continua di 48 ore; +- granularita' coerente con l'intervallo di misura configurato; +- dati minimi per campione: timestamp, esito (ok/errore) e tempo di risposta; +- comportamento a buffer pieno di tipo circolare tipico RRD (sovrascrittura dei campioni piu' vecchi). + +### RF13. Webapp storica in stile SmokePing + +Il sistema deve esporre una webapp locale che mostri lo storico della connessione con visualizzazione ispirata a SmokePing. + +Capacita' minime richieste: + +- pagina di overview con stato corrente e trend delle ultime 48 ore; +- grafico temporale con evidenza di latenza e fallimenti; +- aggiornamento periodico automatico della vista senza riavvio del servizio; +- accesso via porta HTTP configurabile. + +### RF14. API di lettura dello storico + +La webapp deve leggere i dati dal RRD tramite un endpoint applicativo di sola lettura. + +Vincoli: + +- nessuna operazione di scrittura esposta lato web; +- 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 + +Il collector di ping e la webapp devono convivere nello stesso servizio/container senza bloccare il loop di keep-alive. + +In caso di errore della UI, la raccolta dati non deve interrompersi. In caso di errore temporaneo del collector, la UI deve continuare a mostrare l'ultimo storico disponibile. + ## 11. Requisiti Non Funzionali ### RNF1. Semplicita' @@ -188,6 +232,14 @@ I log devono essere sufficienti a diagnosticare se il job di keep-alive ha funzi Il sistema deve usare query leggere e frequenza moderata per minimizzare costo computazionale e rischio di comportamento eccessivo verso il free tier. +### RNF6. Retention e storage prevedibile + +Lo storage storico deve restare bounded: il database RRD deve mantenere esclusivamente 48 ore di dati, con uso disco stabile nel tempo. + +### RNF7. Usabilita' operativa della dashboard + +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). + ## 12. Configurazione di Prodotto ### Variabili richieste @@ -227,6 +279,10 @@ Componenti logici previsti: - loader configurazione: valida e carica le variabili ambiente; - scheduler loop: gestisce l'attesa fra i cicli; - 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; +- 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. @@ -253,6 +309,7 @@ Componenti logici previsti: - Una frequenza troppo bassa potrebbe non prevenire il parking. - Credenziali esposte in repository o log rappresentano rischio di sicurezza. - Cambiamenti futuri nelle policy Supabase potrebbero ridurre l'efficacia della soluzione. +- Corruzione o inizializzazione errata del file RRD puo' rendere incompleta la visualizzazione storica. ### Mitigazioni @@ -260,6 +317,7 @@ Componenti logici previsti: - Query molto leggere. - Segreti solo in `.env`. - Logging senza stampa delle credenziali. +- Validazione all'avvio della struttura RRD e ricreazione controllata in caso di inconsistenza. ## 17. Requisiti di Sicurezza @@ -281,6 +339,7 @@ Componenti logici previsti: - Ogni esecuzione pianificata produce un log di successo oppure un log di errore esplicito. - Il container resta in esecuzione senza terminare dopo il primo ciclo. - La configurazione puo' essere modificata senza cambiare il codice applicativo. +- La webapp mostra sempre uno storico disponibile delle ultime 48 ore, compatibilmente con il tempo trascorso dal primo avvio. ## 20. Acceptance Criteria @@ -312,6 +371,21 @@ Componenti logici previsti: - Il sistema consente una schedulazione moderata, raccomandata su 2-3 esecuzioni a settimana. +### AC7. Persistenza RRD 48 ore + +- A servizio avviato, i campioni di connessione vengono scritti su RRD a ogni ciclo. +- Dopo oltre 48 ore di funzionamento continuo, lo storico visualizzato copre solo la finestra mobile piu' recente di 48 ore. + +### AC8. Dashboard stile SmokePing + +- 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 + +- 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. + ## 21. Roadmap Evolutiva ### V1 @@ -321,6 +395,8 @@ Componenti logici previsti: - Loop continuo. - Logging base. - Container Docker con restart policy consigliata. +- Persistenza storico su RRD locale (48 ore). +- Webapp di visualizzazione storica in stile SmokePing. ### V1.1