docs: aggiungi README, PRD, progress e .gitignore con esclusione segreti

progress.md

@@ -0,0 +1,266 @@
+# Progress
+
+## Stato Attuale
+
+Data riferimento: 2026-04-24
+
+Il progetto ha oggi:
+
+- un README iniziale con obiettivo e modalita' d'uso target;
+- un PRD esteso con requisiti funzionali e non funzionali;
+- note di connessione tecniche da trattare con cautela;
+- nessuna implementazione applicativa ancora presente.
+
+## 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.
+
+## Principi di Esecuzione
+
+- tenere il perimetro minimale e focalizzato;
+- evitare dipendenze inutili;
+- non esporre segreti nel repository;
+- validare ogni fase con una verifica eseguibile;
+- rilasciare una V1 utilizzabile prima di aggiungere feature opzionali.
+
+## Roadmap di Sviluppo
+
+### Fase 0. Messa in sicurezza del repository
+
+Obiettivo:
+Ridurre subito il rischio di esposizione credenziali e allineare il repository a una baseline di sicurezza minima.
+
+Attivita':
+
+- verificare quali file contengono credenziali o connection string reali;
+- rimuovere i segreti dal contenuto versionato e sostituirli con placeholder;
+- assicurare che `.env` sia ignorato da git;
+- mantenere `.env.example` come unico riferimento versionabile;
+- rivedere la documentazione per evitare esempi che inducano a committare segreti.
+
+Deliverable:
+
+- repository senza credenziali reali in chiaro;
+- `.gitignore` corretto;
+- linee guida documentate per la gestione dei segreti.
+
+Verifica:
+
+- ricerca testuale nel repository per individuare host, password, key e DSN;
+- conferma che `.env` non sia tracciato;
+- review manuale dei file documentali.
+
+Stato:
+
+- da fare
+
+### Fase 1. Bootstrap del progetto Python
+
+Obiettivo:
+Creare la struttura minima eseguibile del servizio.
+
+Attivita':
+
+- creare `app.py` o entrypoint equivalente;
+- definire `requirements.txt` con dipendenze minime;
+- scegliere libreria di connessione PostgreSQL adatta al caso d'uso;
+- predisporre struttura semplice senza over-engineering;
+- definire convenzioni di logging e gestione errori.
+
+Deliverable:
+
+- scheletro applicativo Python avviabile;
+- dipendenze dichiarate;
+- entrypoint unico chiaro.
+
+Verifica:
+
+- avvio locale del processo Python;
+- import delle dipendenze senza errori;
+- controllo sintattico del file principale.
+
+Stato:
+
+- da fare
+
+### Fase 2. Configurazione e validazione environment
+
+Obiettivo:
+Caricare e validare in modo affidabile tutte le variabili richieste dal PRD.
+
+Attivita':
+
+- implementare lettura delle env dal runtime;
+- validare presenza di host, porta, database, user, password, query e intervallo;
+- gestire messaggi di errore chiari per configurazioni incomplete;
+- creare `.env.example` coerente con README e PRD;
+- definire default prudenti solo dove sensato.
+
+Deliverable:
+
+- loader di configurazione affidabile;
+- `.env.example` pronto all'uso;
+- error handling per startup configuration.
+
+Verifica:
+
+- avvio con configurazione completa;
+- fallimento atteso con env mancanti;
+- coerenza tra `.env.example`, README e PRD.
+
+Stato:
+
+- da fare
+
+### Fase 3. Connessione a Supabase/PostgreSQL
+
+Obiettivo:
+Stabilire la connessione al database e isolare il layer di accesso.
+
+Attivita':
+
+- implementare apertura connessione al database;
+- eseguire una query di test controllata;
+- gestire timeout, eccezioni e chiusura connessione;
+- evitare logging di segreti o DSN completi;
+- preparare una funzione dedicata al keep-alive.
+
+Deliverable:
+
+- client database funzionante;
+- funzione di ping riusabile;
+- logging tecnico minimo ma utile.
+
+Verifica:
+
+- esecuzione riuscita di `SELECT 1;`;
+- simulazione di errore credenziali o host non raggiungibile;
+- log chiari e privi di segreti.
+
+Stato:
+
+- da fare
+
+### Fase 4. Loop di keep-alive e resilienza runtime
+
+Obiettivo:
+Trasformare il ping singolo in un servizio continuo e resiliente.
+
+Attivita':
+
+- implementare loop infinito controllato;
+- usare `PING_INTERVAL_MINUTES` come scheduling applicativo;
+- loggare avvio ciclo, esito e prossima esecuzione;
+- mantenere il processo attivo anche in caso di errore operativo;
+- gestire terminazione ordinata su stop del container.
+
+Deliverable:
+
+- runtime long-running stabile;
+- gestione errori non distruttiva;
+- shutdown ordinato.
+
+Verifica:
+
+- il processo resta attivo dopo un ping riuscito;
+- il processo resta attivo dopo un ping fallito;
+- stop manuale con chiusura ordinata.
+
+Stato:
+
+- da fare
+
+### Fase 5. Containerizzazione Docker
+
+Obiettivo:
+Rendere il servizio distribuibile e persistente tramite Docker.
+
+Attivita':
+
+- scrivere `Dockerfile` minimale;
+- configurare comando di avvio del processo Python;
+- verificare passaggio variabili con `--env-file .env`;
+- definire uso raccomandato di `--restart unless-stopped`;
+- aggiungere eventuale supporto `docker compose`.
+
+Deliverable:
+
+- immagine Docker buildabile;
+- esecuzione container funzionante;
+- esempio compose essenziale.
+
+Verifica:
+
+- `docker build` completato con successo;
+- container avviato e logs leggibili;
+- persistenza del processo finche' non viene fermato.
+
+Stato:
+
+- da fare
+
+### Fase 6. Documentazione operativa e rifinitura V1
+
+Obiettivo:
+Concludere la prima versione con documentazione e uso coerente.
+
+Attivita':
+
+- allineare README, PRD, `.env.example` e struttura reale del repository;
+- documentare build, run, stop e troubleshooting base;
+- rimuovere ambiguita' su intervallo di ping raccomandato;
+- chiarire i limiti del tool rispetto ai termini del free tier;
+- aggiungere checklist rapida di avvio.
+
+Deliverable:
+
+- documentazione finale coerente con il codice;
+- repository pronto per primo utilizzo;
+- baseline V1 chiusa.
+
+Verifica:
+
+- review incrociata documentazione vs file reali;
+- onboarding test: un utente tecnico deve riuscire ad avviare il servizio dai documenti;
+- lint markdown senza errori.
+
+Stato:
+
+- da fare
+
+## Backlog Post-V1
+
+- retry con backoff configurabile;
+- healthcheck Docker dedicato;
+- endpoint o comando di self-test;
+- notifiche opzionali via webhook o Telegram;
+- metriche esportabili;
+- supporto a query alternativa di keep-alive con tabella di log.
+
+## Ordine di Esecuzione Consigliato
+
+1. Fase 0
+2. Fase 1
+3. Fase 2
+4. Fase 3
+5. Fase 4
+6. Fase 5
+7. Fase 6
+
+## Definizione di Done per la V1
+
+La V1 e' completata quando:
+
+- il repository non contiene segreti reali;
+- esiste `.env.example` completo;
+- il servizio Python si avvia con configurazione valida;
+- il servizio esegue la query di keep-alive verso Supabase;
+- il processo resta attivo nel tempo;
+- il container Docker funziona con `--env-file .env` e `--restart unless-stopped`;
+- la documentazione corrisponde ai file realmente presenti nel repository.
+
+## Prossima Attivita' Operativa
+
+Task raccomandato immediato:
+
+- eseguire la Fase 0 e poi creare lo scheletro minimo della V1 con `app.py`, `requirements.txt`, `.env.example` e `Dockerfile`.