# 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