Add project documentation (CLAUDE.md)
Technical documentation for future reference: - App overview and access credentials - Database schema and API endpoints - VPS configuration details - Update workflow instructions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Michele
236
CLAUDE.md
Normal file
236
CLAUDE.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user