Guida: Gestione Job Schedulati e Daily Checks

Problema: Daily Checks Non Funzionano Automaticamente

Possibili Cause

Workers non avviati - I worker BullMQ non sono in esecuzione
Scheduler non configurato - Lo scheduler cron non è stato inizializzato
Redis non raggiungibile - Problemi di connessione a Redis
Errori nel job - Il job si blocca per errori durante l’esecuzione

Soluzione 1: Verifica se i Workers sono Attivi

Metodo 1: Verifica tramite API

Chiama questo endpoint per vedere lo stato dei job schedulati:


curl http://localhost:3000/api/admin/trigger-daily-checks

Risposta attesa:


{
  "success": true,
  "scheduled": {
    "count": 1,
    "jobs": [
      {
        "name": "daily-checks-scheduled",
        "pattern": "0 4 * * *",
        "next": 1704600000000
      }
    ]
  },
  "recent": {
    "completed": [...],
    "failed": [...],
    "waiting": [...],
    "active": [...]
  }
}

Se scheduled.count è 0, i workers non sono attivi.

Metodo 2: Verifica tramite Bull Board Dashboard

Apri in browser:


http://localhost:3000/api/admin/bull-board

Cerca la coda “daily-checks” e verifica:

Se ci sono job “Repeatable” schedulati
Se ci sono job falliti recentemente
Se ci sono workers connessi

Metodo 3: Verifica Log del Server

Quando i workers si avviano correttamente, vedrai questi log:


✅ Daily checks scheduler configurato (4:00 AM ogni giorno)
📋 Job schedulati attivi: 1
✅ Workers e scheduler avviati

Soluzione 2: Avvia i Workers

I workers devono essere avviati separatamente dal server Next.js.

In Sviluppo

Apri un terminale separato e lancia:


npm run workers

Questo comando avvia i workers in modalità watch (si riavviano automaticamente quando modifichi il codice).

In Produzione


npm run workers:prod

Oppure usa PM2 per gestire i worker come processo separato (vedi ecosystem.config.js):


pm2 start ecosystem.config.js

Il file ecosystem.config.js già configura:

foodcost-web - Server Next.js sulla porta 4000
foodcost-workers - Worker BullMQ che processano i job

Verifica che Redis sia Raggiungibile

I worker hanno bisogno di connettersi a Redis. Verifica le variabili d’ambiente:


echo $REDIS_HOST
echo $REDIS_PORT

Se Redis non è configurato, aggiungi in .env.local:


REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

Soluzione 3: Esegui Daily Checks Manualmente

Opzione A: Trigger via API

Puoi forzare l’esecuzione dei daily checks senza aspettare il cron:


# Esegui per tutti i tenant
curl -X POST http://localhost:3000/api/admin/trigger-daily-checks \
  -H "Content-Type: application/json" \
  -d '{}'
 
# Esegui per un tenant specifico
curl -X POST http://localhost:3000/api/admin/trigger-daily-checks \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "YOUR_TENANT_ID"}'
 
# Esegui solo alcuni check
curl -X POST http://localhost:3000/api/admin/trigger-daily-checks \
  -H "Content-Type: application/json" \
  -d '{"checks": ["sales"]}'

Risposta attesa:


{
  "success": true,
  "jobId": "12345",
  "message": "Daily checks job avviato con successo",
  "checks": ["inventory", "foodcost", "recalculate", "sales"]
}

Opzione B: Via Bull Board Dashboard

Vai su http://localhost:3000/api/admin/bull-board
Seleziona la coda “daily-checks”
Clicca su “Add Job”

Inserisci i dati del job:


{
  "checks": ["inventory", "foodcost", "recalculate", "sales"]
}

Clicca “Add”

Cosa Fanno i Daily Checks?

Il job esegue 9 controlli automatici:

inventory - Verifica prodotti con stock basso e crea notifiche
foodcost - Analizza prodotti con food cost elevato (>40%)
recalculate - Ricalcola i food cost di tutti i prodotti
sales - Sincronizza incassi da CassaInCloud (il giorno precedente)
reconciliations - Importa riconciliazioni da CassaInCloud
priceChanges - Rileva cambiamenti di prezzo nei prodotti importati
foodcostChanges - Rileva cambiamenti significativi nel food cost
utilityBills - Sincronizza bollette utenze da fatture fornitori
bankSync - Sincronizza connessioni bancarie TrueLayer (saldi e movimenti)

Importazione Incassi

Il check sales è quello che importa gli incassi automaticamente:


// Importa vendite dal giorno precedente
const yesterday = new Date();
yesterday.setDate(yesterday.getDate() - 1);
 
// Per ogni tenant con CassaInCloud configurato
// Avvia sync delle vendite

Sincronizzazione Banche (TrueLayer)

Il check bankSync sincronizza automaticamente tutte le connessioni bancarie TrueLayer:


// Per ogni connessione bancaria attiva:
// 1. Refresh token se scaduto
// 2. Aggiorna saldo corrente e disponibile
// 3. Importa movimenti degli ultimi 30 giorni
// 4. Gestione duplicati tramite hash

Dati aggiornati:

Saldo corrente - Il saldo effettivo del conto
Saldo disponibile - Il saldo utilizzabile (può differire per assegni non riscossi, etc.)
Movimenti bancari - Entrate/uscite con deduplicazione automatica

Schedulazione Cron

Il job è configurato per eseguirsi ogni giorno alle 4:00 AM:


pattern: "0 4 * * *"; // Cron syntax: minuto ora giorno mese giornoSettimana

Modificare l’Orario

Modifica /src/jobs/setupScheduler.ts:


// Esempio: ogni giorno alle 2:00 AM
pattern: "0 2 * * *";
 
// Esempio: ogni 30 minuti (test)
pattern: "*/30 * * * *";
 
// Esempio: ogni lunedì alle 8:00 AM
pattern: "0 8 * * 1";

Dopo la modifica:

Riavvia i workers: npm run workers
Verifica che il nuovo schedule sia attivo via API

Debugging

Log dei Workers

I workers loggano ogni operazione:


[DailyChecksWorker] Processing job 123 for tenant: xyz
📥 Inizio sincronizzazione vendite per tenant xyz
✅ Job di sincronizzazione vendite avviato per tenant xyz (Job ID: 456)
[DailyChecksWorker] Job 123 completed successfully

Verifica Job Falliti

Via API:


curl http://localhost:3000/api/admin/trigger-daily-checks | jq '.recent.failed'

Via Bull Board:

Vai alla coda “daily-checks”
Filtra per “Failed”
Vedi il motivo dell’errore nello stacktrace

Test Rapido

Per testare subito senza aspettare le 4:00 AM:

Modifica temporaneamente il cron pattern a ogni minuto:
```
pattern: "* * * * *"; // Ogni minuto
```
Riavvia workers: npm run workers
Osserva i log - dovresti vedere il job partire ogni minuto
Quando funziona, ripristina "0 4 * * *"

Checklist Risoluzione Problemi

Workers avviati (npm run workers)
Redis raggiungibile e funzionante
Variabili d’ambiente configurate (REDIS_HOST, MONGODB_URI)
Scheduler configurato (vedi log ”✅ Daily checks scheduler configurato”)
Job schedulati presenti (GET /api/admin/trigger-daily-checks)
CassaInCloud API key configurata nelle impostazioni
Nessun job fallito recente (vedi Bull Board)

Comandi Utili


# Avvia workers in dev
npm run workers
 
# Avvia workers in produzione
npm run workers:prod
 
# Verifica stato job schedulati
curl http://localhost:3000/api/admin/trigger-daily-checks
 
# Trigger manuale
curl -X POST http://localhost:3000/api/admin/trigger-daily-checks \
  -H "Content-Type: application/json" \
  -d '{"checks": ["sales"]}'
 
# Vedi metriche di tutte le code
curl http://localhost:3000/api/admin/queues/metrics
 
# Pulisci job vecchi
curl -X POST http://localhost:3000/api/admin/queues/actions \
  -H "Content-Type: application/json" \
  -d '{"action": "clean", "queueName": "dailyChecks", "status": "completed", "grace": 86400000}'

Produzione con PM2

Il modo migliore in produzione è usare PM2:


# Installa PM2 globalmente
npm install -g pm2
 
# Avvia tutto (web + workers)
pm2 start ecosystem.config.js
 
# Verifica stato
pm2 status
 
# Log in tempo reale
pm2 logs
 
# Solo workers
pm2 logs foodcost-workers
 
# Riavvia workers
pm2 restart foodcost-workers
 
# Salva configurazione per restart automatico
pm2 save
pm2 startup