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