Un'azienda agricola che vende, fattura e avvisa senza cambiare strumento
Felice Agricoltura è un'azienda agricola biologica di Montemurlo, in provincia di Prato, con il Frantoio della Rocca. Serviva un posto solo per vendere online, seguire gli ordini e tenere informati i clienti senza scrivere messaggi a mano.
Risultati misurati
1
monorepo: negozio, gestionale e worker
2
processi separati, per un motivo preciso
0
arrotondamenti: importi in centesimi interi
IT
email transazionali via Aruba
01 — Contesto
Vendere prodotti agricoli non è vendere magliette
Un prodotto agricolo ha stagionalità, lotti e un'IVA che cambia per categoria. Gli ordini vanno seguiti fino alla consegna e i clienti, spesso abituali, preferiscono un messaggio su WhatsApp a una email che non leggeranno.
Il punto di partenza è stato l'interfaccia disegnata nel progetto Claude Design dell'azienda, tradotta poi in un'applicazione che dovesse reggere ordini veri e contabilità vera.
02 — Approccio
Due processi, perché WhatsApp non è un'API
Gli avvisi passano da `whatsapp-web.js`, che pilota una sessione reale di WhatsApp Web dentro un Chromium e deve restare acceso con lo stato salvato su disco. Non può vivere dentro una funzione che nasce e muore a ogni richiesta.
Perciò il worker è un processo a sé: il sito accoda i messaggi su Redis e il worker li consegna. Se il worker è fermo il negozio continua a funzionare e i messaggi partono al riavvio — la vendita non si blocca mai per un avviso.
Gli importi sono numeri interi in centesimi: sui totali con IVA per categoria, i decimali in virgola mobile producono differenze di un centesimo che in contabilità non si possono spiegare.
03 — Soluzione
Cosa abbiamo costruito
Negozio e area amministrativa
Un'unica applicazione Next.js: vetrina, carrello, ordini e back-office di gestione.
Logica di dominio isolata
IVA, importi, stati dell'ordine e code stanno in un pacchetto senza dipendenze dal framework: si testano da soli.
Worker WhatsApp
Processo autonomo che consuma la coda Redis e consegna gli avvisi ai clienti.
Pagamenti ed email
Incassi online e posta transazionale via Aruba, con i modelli dei messaggi in italiano.
04 — Dentro il codice
Quattro pacchetti, e le regole più delicate fuori dal framework
Il progetto è un monorepo con quattro pacchetti: il sito e la sua area amministrativa, il worker di WhatsApp, un pacchetto di dominio e uno per il database. Delle trecento e passa sorgenti, la parte che conta davvero non è nelle pagine — è nel pacchetto `core`.
Lì stanno le regole che non possono sbagliare: come si calcolano IVA e totali, quali stati può assumere un ordine e in quale ordine, come si normalizza un numero di telefono prima di mandargli un messaggio, come funziona la coda. Nessuna di queste cose importa il framework, quindi si provano da sole, in un secondo, senza avviare un sito.
Lo schema del database vive nel suo pacchetto con le migrazioni numerate: undici passaggi che raccontano come la struttura è cambiata. È la differenza fra un database che si può far evolvere e uno che si tocca con paura.
05 — Risultato
Come si lavora adesso
L'azienda gestisce il catalogo e gli ordini dalla stessa applicazione che i clienti vedono, e gli avvisi partono da soli quando un ordine cambia stato. La separazione fra sito e worker ha un effetto concreto: un problema su WhatsApp non ferma le vendite, e i messaggi in coda vengono recapitati appena il servizio torna.
