diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2cd9469 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,236 @@ +# Supabase Scheduler - Documentazione Progetto + +## Panoramica + +**Supabase Scheduler** è una web app per gestire ed eseguire automaticamente query verso database Supabase multipli. Permette di configurare più istanze Supabase, ciascuna con la propria query e frequenza di esecuzione, e le esegue in background 24/7. + +--- + +## Accesso + +### URL Live +- **Applicazione**: https://lab.mlhub.it/supabase-scheduler/ +- **Repository Git**: https://git.mlhub.it/Michele/supabase-scheduler + +### Credenziali Login (fisse, non modificabili) +- **Username**: `testlab` +- **Password**: `magarifunzione4` + +Le credenziali sono hardcoded nel file `server.js` (righe 12-13). + +--- + +## Cosa Fa + +### Funzionalità Principali + +1. **Gestione Multi-Database** + - Aggiungere configurazioni per diversi progetti Supabase + - Ogni database ha: nome, URL, anon key, query, frequenza + - CRUD completo (Create, Read, Update, Delete) + +2. **Scheduler Automatico** + - Esegue query automaticamente secondo la frequenza impostata + - Gira 24/7 sul server (anche senza utenti connessi) + - Controllo ogni minuto per verificare quali query eseguire + +3. **Log Esecuzioni** + - Registra ogni esecuzione con timestamp, status, durata + - Memorizza errori per debugging + - Ultimi 50 log per database visibili da UI + +4. **Esecuzione Manuale** + - Pulsante "Esegui Ora" per testare query on-demand + +### Formato Query Supabase + +Il campo "Query" accetta endpoint REST Supabase: + +``` +# Esempi validi: +users?select=* # Tutti gli utenti +products?select=id,name&active=eq.true # Prodotti filtrati +orders?select=*&limit=10 # Ultimi 10 ordini +rpc/my_function # Chiama RPC function +rpc/cleanup_old_data # Function di manutenzione +``` + +La query viene eseguita come GET request verso: +`{SUPABASE_URL}/rest/v1/{QUERY}` + +--- + +## Stack Tecnologico + +| Componente | Tecnologia | +|------------|------------| +| Backend | Node.js + Express | +| Database | SQLite (better-sqlite3) | +| Scheduler | node-cron | +| Frontend | HTML/CSS/JS vanilla | +| Container | Docker (node:18-alpine) | + +--- + +## Struttura File + +``` +supabase-scheduler/ +├── server.js # Backend Express + scheduler + API +├── package.json # Dipendenze Node.js +├── docker-compose.yml # Configurazione container +├── deploy.sh # Script auto-deploy (solo su VPS) +├── public/ +│ └── index.html # Frontend SPA completo +├── data/ +│ ├── .gitkeep # Mantiene directory in Git +│ └── scheduler.db # Database SQLite (gitignored, creato a runtime) +├── .env.example # Template variabili ambiente +├── .gitignore +├── .gitattributes +├── README.md # Documentazione utente +└── CLAUDE.md # Questo file - documentazione tecnica +``` + +--- + +## Database SQLite + +### Tabella `databases` +Configurazioni dei database Supabase. + +| Campo | Tipo | Descrizione | +|-------|------|-------------| +| id | INTEGER | Primary key | +| name | TEXT | Nome identificativo | +| supabase_url | TEXT | URL progetto (https://xxx.supabase.co) | +| anon_key | TEXT | Chiave anon/public | +| query | TEXT | Endpoint REST da chiamare | +| frequency_minutes | INTEGER | Intervallo esecuzione (default 5) | +| is_active | INTEGER | 0/1 toggle attivazione | +| last_run | TEXT | Timestamp ultima esecuzione | +| last_status | TEXT | 'success' o 'error' | +| last_error | TEXT | Messaggio errore (se presente) | +| created_at | TEXT | Timestamp creazione | +| updated_at | TEXT | Timestamp ultima modifica | + +### Tabella `execution_logs` +Log di tutte le esecuzioni. + +| Campo | Tipo | Descrizione | +|-------|------|-------------| +| id | INTEGER | Primary key | +| database_id | INTEGER | FK a databases.id | +| executed_at | TEXT | Timestamp esecuzione | +| status | TEXT | 'success' o 'error' | +| response | TEXT | Risposta JSON (troncata a 5000 char) | +| error | TEXT | Messaggio errore | +| duration_ms | INTEGER | Durata in millisecondi | + +--- + +## API Endpoints + +### Autenticazione +- `POST /api/login` - Login con username/password +- `POST /api/logout` - Logout (distrugge sessione) +- `GET /api/auth/status` - Verifica stato autenticazione + +### Database CRUD (richiede auth) +- `GET /api/databases` - Lista tutti i database +- `GET /api/databases/:id` - Dettaglio singolo database +- `POST /api/databases` - Crea nuovo database +- `PUT /api/databases/:id` - Modifica database +- `DELETE /api/databases/:id` - Elimina database + +### Esecuzione e Log (richiede auth) +- `POST /api/databases/:id/execute` - Esegui query manualmente +- `GET /api/databases/:id/logs` - Ultimi 50 log esecuzione + +### Utility +- `GET /api/health` - Health check +- `GET /api/scheduler/status` - Stato scheduler + +--- + +## Configurazione VPS + +### Directory +``` +/opt/lab-supabase-scheduler/ +``` + +### Container Docker +- **Nome**: `lab-supabase-scheduler-app` +- **Immagine**: `node:18-alpine` +- **Porta interna**: 3000 +- **Rete**: `proxy_net` +- **Limiti**: 300M RAM, 0.25 CPU + +### Nginx Routing +File: `/opt/lab-router/projects/supabase-scheduler.conf` +```nginx +location /supabase-scheduler/ { + proxy_pass http://lab-supabase-scheduler-app:3000/; + ... +} +``` + +--- + +## Workflow Aggiornamenti + +### Modifiche al codice +```bash +# 1. Modifica file localmente +# 2. Commit e push +cd "D:\Michele\Progetti\Claude\VPS echosystem\lab\supabase-scheduler" +git add . +git commit -m "Descrizione modifica" +git push origin main + +# 3. Deploy su VPS +ssh mic@72.62.49.98 "cd /opt/lab-supabase-scheduler && ./deploy.sh" +``` + +### Comandi utili VPS +```bash +# Log container +ssh mic@72.62.49.98 "docker logs -f lab-supabase-scheduler-app" + +# Restart container +ssh mic@72.62.49.98 "cd /opt/lab-supabase-scheduler && docker compose restart" + +# Accesso shell container +ssh mic@72.62.49.98 "docker exec -it lab-supabase-scheduler-app sh" +``` + +--- + +## Note Tecniche + +### Session Warning +All'avvio appare warning: +``` +Warning: connect.session() MemoryStore is not designed for production +``` +Per un'app lab è accettabile. In production usare Redis o database session store. + +### Scheduler Logic +- Il cron gira ogni minuto (`* * * * *`) +- Per ogni database attivo, verifica se è passato `frequency_minutes` dall'ultima esecuzione +- Se sì, esegue la query e aggiorna `last_run`, `last_status`, `last_error` + +### Sicurezza +- Le anon_key Supabase sono salvate in chiaro nel database SQLite +- Per uso production, considerare encryption at rest +- La sessione usa cookie HTTP-only ma non secure (lab environment) + +--- + +## Cronologia Progetto + +- **Creato**: 2026-01-24 +- **Autore**: Claude Opus 4.5 + Michele +- **Scopo**: Gestione automatica query periodiche verso database Supabase multipli +- **Richiesta originale**: App con login fisso, dashboard per configurare database Supabase, scheduler che esegue query automaticamente 24/7