Guida Onboarding — MonosTech

Tutto ciò che serve per essere operativi sul sistema MonosTech — Ultimo aggiornamento: 24/03/2026

1. Panoramica Veloce

MonosTech è uno store Shopify che vende stampanti, plotter, scanner e accessori. Il sistema:

Scarica i listini da 5 fornitori (IMA, Focelda, TD Synnex, Xpress, Esprinet)
Unifica ~398.000 prodotti in un database Supabase
Seleziona il miglior fornitore per ogni prodotto (~47.700 prodotti unici)
Calcola il prezzo di vendita con controlli anti-errore automatici
Pubblica su Shopify, due volte al giorno

Per approfondire: Panoramica sistema completa

2. Accessi Necessari

Sistemi principali

Sistema	URL	Cosa serve
Supabase	supabase.com/dashboard	Database PostgreSQL — dati prodotti, prezzi, configurazioni
n8n	n8n.srv1203683.hstgr.cloud	Automazioni — workflow import, pricing, sync Shopify
NocoDB	nocodb.srv1203683.hstgr.cloud	Interfaccia tabellare per consultare/modificare dati nel DB
Shopify Admin	admin.shopify.com	Gestione store, prodotti, ordini
Shopify Dev	dev.shopify.com	App personalizzata, gestione scope e token
Documentazione	docs.srv1203683.hstgr.cloud	Documentazione operativa del sistema (questa pagina)
VPS (SSH)	`ssh root@srv1203683.hstgr.cloud`	Server che ospita n8n, NocoDB e Docs
Telegram	Bot @monostestacv_bot	Alert e report automatici dal sistema

Credenziali

Le credenziali sono nel file .env nella root del progetto (non versionato su Git). Contiene:

SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_DB_PASSWORD
NOCODB_URL, NOCODB_TOKEN
KEEPA_API_KEY
TEAMSYSTEM_ID, TEAMSYSTEM_SECRET

Le credenziali n8n (FTP fornitori, Shopify, Telegram, Postgres) sono configurate direttamente dentro n8n.

3. Struttura del Progetto

docs/architecture/

Documentazione tecnica (DB, import, n8n, Shopify, pricing)

docs/funzionali/

Documenti di business (regole, controlli, panoramica)

docs/operativo/

Procedure operative (runbook, onboarding, flussi, mappa)

docs/api/

Manuali API (TS Digital, GLS, FedEx)

docs/tariffe/

Tariffari spedizione corrieri

scripts/

Script Python per verifiche e utilità

workflows/

Workflow n8n (sincronizzati automaticamente)

plans/

Piani di implementazione

Documenti chiave da leggere

Panoramica sistema — come funziona tutto, spiegato in modo semplice
Algoritmo pricing — logica di selezione fornitore e calcolo prezzo
Controlli anti-errore — i 7 controlli automatici (PS-01..PS-07)
Runbook operativo — procedure quotidiane e troubleshooting
Mappa sistema — componenti, connessioni e dipendenze
Flussi decisionali — diagrammi dei flussi principali

4. Architettura del Database

Il database Supabase contiene:

Tabella	Record	Descrizione
`prodotti`	~398.000	Tutti i prodotti di tutti i fornitori, dati grezzi
`prodotti_shopify`	~47.700	Vista materializzata: prodotti pronti per Shopify, fornitore migliore già selezionato
`fornitori_config`	5	Metadati fornitore (affidabilità, lead time, fido, trasporto)
`brand_policy`	variabile	Policy prezzo per brand (LISTINO/MSRP/QUOTAZIONE)
`pricing_config`	variabile	Parametri configurabili (soglie, margini, peak mode)
`ean_bloccati`	variabile	EAN vietati alla pubblicazione
`pricing_alerts`	variabile	Log alert anti-errore (PS-01..PS-05)
`shopify_sync_stato`	~47.700	Stato sync di ogni prodotto su Shopify

Schema completo: database.md

5. Come Funzionano i Workflow n8n

I workflow sono organizzati in 3 gruppi:

Import fornitori (schedulati, automatici)

Scaricano i CSV dai server FTP dei fornitori e li caricano nel database. Ogni fornitore ha un orchestratore + un sub-workflow di processing.

Pricing e Keepa (schedulati, automatici)

L’algoritmo pricing gira alle 04:00 e 16:00
Keepa aggiorna i prezzi Amazon ogni 5 minuti

Shopify (schedulati, automatici)

La sync gira alle 05:00 e 17:00, un’ora dopo il pricing
Aggiorna prezzi/stock, importa nuovi prodotti, gestisce orfani

Dettagli: n8n-infrastructure.md

6. Checklist Primo Giorno

Ricevere accesso a Supabase (invito al progetto)
Ricevere accesso a n8n (credenziali login)
Ricevere accesso a NocoDB (credenziali login)
Ricevere accesso SSH alla VPS (chiave SSH o password)
Ricevere accesso a Shopify Admin (invito come staff)
Ricevere il file .env con le credenziali
Essere aggiunti al bot Telegram per ricevere gli alert
Leggere la Panoramica sistema
Leggere il Runbook operativo
Verificare che n8n sia raggiungibile e i workflow siano attivi
Verificare che il report Telegram arrivi dopo il pricing delle 04:00 o 16:00

7. Strumenti di Sviluppo

Strumento	Uso
VS Code + Claude Code	Sviluppo, documentazione, gestione repository
Git	Versionamento codice e documentazione
Python 3	Script di verifica e utilità
Node.js	Script di supporto
Docker	Infrastruttura n8n (sulla VPS)

Repository Git

GitHub: github.com/albertocabasvidani/n8n-monostech
Il commit e il push avvengono a fine sessione di lavoro (hook automatico)
I workflow n8n vengono sincronizzati automaticamente nella cartella workflows/

MonosTech — Guida Onboarding — Ultimo aggiornamento: 24/03/2026