Runbook Operativo MonosTech

Procedure operative quotidiane, gestione anomalie e troubleshooting — Ultimo aggiornamento: 24/03/2026

1. Operazioni Automatiche Giornaliere

Il sistema funziona in autonomia. Ogni giorno vengono eseguite automaticamente queste operazioni:

Orario	Operazione	Workflow n8n	Cosa fa
Notte	Import listini fornitori	Vari import schedulati	Aggiorna dati raw in tabella `prodotti`
04:00	Algoritmo Pricing	Algoritmo Pricing Giornaliero	Snapshot prezzi → controlli anti-errore → refresh vista → alert Telegram
04:30	Aggiornamento prezzi Amazon	Keepa - Aggiorna Prezzi Amazon	100 EAN ogni 5 min, continuo
05:00	Sync Shopify	Shopify - Sync Prezzi e Stock	Aggiorna prezzi/stock, importa nuovi, gestisce orfani
16:00	Algoritmo Pricing (2ª)	Algoritmo Pricing Giornaliero	Stessa pipeline delle 04:00
17:00	Sync Shopify (2ª)	Shopify - Sync Prezzi e Stock	Stessa sync delle 05:00

Cosa controllare ogni giorno

Report Telegram (bot @monostestacv_bot): dopo le 04:00 e le 16:00 arriva un riepilogo con numero prodotti aggiornati, alert WARNING / HOLD / CRITICAL, stato peak mode, eventuali errori.
n8n (https://n8n.srv1203683.hstgr.cloud): verificare che non ci siano workflow falliti nella sezione “Executions”.

2. Gestione Alert Telegram

Quando arriva un alert dal bot Telegram, ecco come interpretarlo e agire:

WARNING — Livello 1: Solo informativo

Codice	Significato	Azione richiesta
PS-01 WARNING	Prezzo fuori range (troppo basso o alto)	Nessuna. Fornitore escluso automaticamente per quel prodotto.
PS-03 WARNING	Prezzo troppo diverso dagli altri fornitori	Nessuna. Se il prodotto è in promo, il sistema genera solo un alert INFO (non esclude). Altrimenti verificare se il fornitore ha un listino aggiornato.
PS-05 WARNING	Prezzo Shopify cambiato >10% rispetto al giorno prima	Verificare che il cambio sia legittimo (promo, aggiornamento listino).

HOLD — Livello 2: Prezzo congelato, richiede revisione

Codice	Significato	Azione richiesta
PS-02 HOLD	Prezzo cambiato >25% rispetto alla media 30 giorni	Il prezzo Shopify è congelato. Verificare se il cambio è reale o errore fornitore.
PS-05 HOLD	Prezzo Shopify cambierebbe >20%	Il prezzo è congelato. Verificare la causa.

Come risolvere un HOLD

Verificare il prezzo corrente del fornitore (NocoDB o Supabase).
Confrontare con gli altri fornitori per lo stesso EAN.
Se il prezzo è corretto: il sistema risolve automaticamente dopo 3 giorni.
Se il prezzo è un errore: contattare il fornitore o aggiungere il fornitore a fornitori_esclusi per quell’EAN.

Nota temporanea Finché il sito non è online, la funzione fn_auto_risolvi_hold() risolve automaticamente gli HOLD dopo 3 giorni. Quando il sito sarà operativo e ci sarà un operatore, rimuovere la chiamata dal workflow e tornare a risoluzione manuale.

CRITICAL — Livello 3: Fornitore escluso o prodotto in DRAFT

Codice	Significato	Azione richiesta
PS-01 CRITICAL	Prezzo a €0 o fuori range assoluto	Fornitore escluso. Verificare il feed del fornitore.
PS-02 CRITICAL	Prezzo cambiato >40% rispetto alla media	Fornitore escluso. Probabilmente errore nel listino.
PS-03 CRITICAL	Deviazione estrema dalla mediana fornitori (solo se non in promo)	Fornitore escluso. Se è una promo legittima, aggiungere a `promo_whitelist` (il report Telegram include un link NocoDB per farlo rapidamente). Riammissione automatica quando il prezzo rientra o il prodotto entra in promo.
PS-04 CRITICAL	Margine <9% sul landed cost	Prodotto in DRAFT (non visibile su Shopify).

Come investigare un CRITICAL

Cercare l’EAN nella tabella pricing_alerts (NocoDB) per i dettagli.
Cercare l’EAN nella tabella fornitori_esclusi per vedere quali fornitori sono stati esclusi.
Verificare i prezzi raw nella tabella prodotti per tutti i fornitori di quell’EAN.
Se errore fornitore: aspettare il prossimo aggiornamento listino.
Se problema sistematico: contattare il fornitore.

3. Procedure Manuali

3.1 Forzare un refresh prezzi

Se serve aggiornare i prezzi fuori dagli orari schedulati:

Andare su n8n → workflow Algoritmo Pricing Giornaliero
Cliccare “Test workflow”
Attendere il completamento (~105 secondi)
Verificare il report Telegram

3.2 Forzare sync Shopify

Se serve sincronizzare Shopify fuori dagli orari schedulati:

Andare su n8n → workflow Shopify - Sync Prezzi e Stock
Cliccare “Test workflow”
Attendere il completamento

3.3 Import manuale di un fornitore

Se un listino non si è aggiornato:

Andare su n8n → workflow di importazione del fornitore (es. Importazione Tdsynnex SQL)
Cliccare “Test workflow”
Verificare nella tabella prodotti che i dati siano aggiornati (colonna data_aggiornamento)

3.4 Bloccare un EAN dalla pubblicazione

Aggiungere l’EAN alla tabella ean_bloccati (via NocoDB o Supabase)
Campi: ean, motivo, data_inserimento
Al prossimo ciclo pricing, il prodotto verrà messo in DRAFT

3.5 Aggiungere un’eccezione promo

Aggiungere il record alla tabella promo_whitelist (via NocoDB)
Campi necessari: ean, fornitore, sconto_max_pct, data_inizio, data_fine
Il sistema PS-06 accetterà le deviazioni entro il limite specificato

3.6 Verificare discrepanze Shopify vs Database

Andare su n8n → workflow Verifica Shopify vs DB
Cliccare “Test workflow”
Il report arriva su Telegram con le discrepanze trovate

4. Troubleshooting

4.1 Token Shopify scaduto

Sintomo: errori “Unauthorized” o “401” nei workflow Shopify.

Soluzione

Andare su n8n → workflow Shopify - Ottieni Token
Eseguire manualmente
Verificare nella tabella shopify_token che il nuovo token sia presente con scadenza futura
Rieseguire il workflow che falliva

4.2 Workflow n8n fallito

Sintomo: workflow con stato “Error” nella lista esecuzioni n8n.

Diagnosi:

Aprire l’esecuzione fallita in n8n
Individuare il nodo rosso (quello che ha generato l’errore)
Leggere il messaggio d’errore

Cause comuni:

Errore	Causa	Soluzione
`ECONNREFUSED`	Problema di rete VPS	Verificare connessione, riprovare
`timeout`	DB o API non risponde	Riprovare dopo qualche minuto
`rate limit`	Troppe richieste API	Attendere e riprovare
`relation does not exist`	Tabella mancante in Supabase	Verificare schema DB

4.3 n8n non raggiungibile

Sintomo: https://n8n.srv1203683.hstgr.cloud non risponde.

# Connettersi alla VPS
ssh root@srv1203683.hstgr.cloud

# Verificare stato container
cd /docker/n8n
docker compose ps

# Se container down, riavviare
docker compose restart

# Se non si riavvia, controllare log
docker logs n8n-n8n-1 --tail 100

4.4 Database Supabase lento o non risponde

Sintomo: workflow impiegano molto più del solito, timeout frequenti.

Dashboard Supabase → sezione “Database” → “Database Health”
Verificare utilizzo disco (il DB è ~346 MB, piano Free ha 500 MB)
Verificare connessioni attive (PgBouncer gestisce il pooling)

Nota La vista materializzata usa REFRESH MATERIALIZED VIEW (non CONCURRENTLY) perché PgBouncer in modalità transaction non lo supporta. Durante il refresh (~2-3 secondi) le query sulla vista possono fallire.

4.5 Import fornitore non aggiorna i dati

Sintomo: i dati di un fornitore nella tabella prodotti hanno data_aggiornamento vecchia.

Il workflow di import è attivo in n8n?
L’ultima esecuzione è andata a buon fine? (verificare in “Executions”)
Il server FTP del fornitore è raggiungibile?
Il file CSV del fornitore è stato aggiornato?

4.6 Prezzi Amazon non si aggiornano (Keepa)

Sintomo: la tabella amazon_prezzi ha date vecchie.

Il workflow Keepa - Aggiorna Prezzi Amazon è attivo?
Verificare se la quota API è esaurita (piano €49/mese: 20 token/min, max 28.800 prodotti/giorno)
Controllare la tabella keepa_coda: se vuota, fn_popola_keepa_coda() non è stata eseguita

5. Procedure di Recovery

5.1 Backup Database Supabase

Il backup viene gestito automaticamente da Supabase. Per un backup manuale:

Dashboard Supabase → Settings → Database → Backups
Scaricare il backup più recente

Per dump manuale via CLI:

pg_dump "postgresql://postgres.ffcrmgkbhxjcvxidjmns:[PASSWORD]@aws-1-eu-west-1.pooler.supabase.com:6543/postgres" > backup_YYYYMMDD.sql

5.2 Ripristino dopo errore pricing

Procedura

Non farsi prendere dal panico: i prezzi su Shopify vengono aggiornati solo al prossimo sync (05:00 o 17:00).
Se il sync non è ancora partito: correggere il problema e rieseguire il pricing.
Se il sync è già partito: il prossimo ciclo pricing (16:00) correggerà i prezzi.
In caso estremo: disattivare temporaneamente il workflow Shopify - Sync Prezzi e Stock da n8n.

5.3 Backup workflow n8n

I workflow n8n sono sincronizzati automaticamente nella cartella workflows/ del repository Git. In caso di problema:

I file JSON sono nella cartella workflows/ del progetto
Per reimportare: n8n → Import from File → selezionare il JSON

5.4 Recovery VPS n8n

Accedere al pannello Hostinger per verificare lo stato del server
Se il server è attivo ma n8n non risponde: ssh root@srv1203683.hstgr.cloud → docker compose restart
Se il server è down: riavviarlo dal pannello Hostinger
Dopo il riavvio, i container Docker si avviano automaticamente

6. Contatti e Escalation

Problema	Chi contattare	Come
Errore listino fornitore	Referente commerciale del fornitore	Email / telefono
Problema Supabase	Dashboard Supabase / supporto	supabase.com/dashboard
Problema VPS / Hostinger	Supporto Hostinger	Pannello Hostinger
Problema Shopify	Supporto Shopify Partner	help.shopify.com
Problema Keepa API	Supporto Keepa	keepa.com
Problema tecnico sistema	Sviluppatore (Alberto Cabas Vidani)	Telegram

MonosTech — Runbook Operativo — Ultimo aggiornamento: 24/03/2026