Manuale Operativo: Configurazione e Gestione Sincronizzazione Punti Vendita

Introduzione e Architettura del Sistema

Questo manuale operativo fornisce agli amministratori di sistema le procedure dettagliate per la configurazione, la gestione e la manutenzione della sincronizzazione dei dati tra il sistema gestionale centrale SIGEAdb e il software dei punti vendita (EVO). Una corretta configurazione è un prerequisito fondamentale per garantire l'integrità dei dati scambiati tra i sistemi, assicurando l'efficienza operativa dei punti vendita e la coerenza delle informazioni a livello centrale.

Componenti del Sistema


Sistema	Ruolo
SIGEAdb	Gestionale centrale che funge da "master" per tutte le anagrafiche (articoli, listini, assortimenti) e gestisce la logistica del magazzino centrale (CE.DI.).
EVO	Software gestionale installato presso le casse dei punti vendita. È responsabile della raccolta degli ordini, della gestione delle vendite al dettaglio e del magazzino locale.

Il flusso generale dei dati tra i due sistemi è bidirezionale. SIGEAdb agisce come fonte primaria per le anagrafiche, esportando informazioni critiche come articoli, codici EAN, listini e assortimenti verso tutti i punti vendita. Inoltre, esporta i documenti di consegna (DDT) per notificare ai punti vendita la merce in arrivo dal magazzino centrale. In direzione opposta, EVO genera file contenenti gli ordini di approvvigionamento dei singoli negozi, che vengono importati e processati da Sigea per avviare il ciclo logistico. La sfida architetturale di questa integrazione risiede nella necessità di tradurre costantemente le codifiche dei punti vendita, differenti tra SIGEAdb (basata sui depositi) ed EVO, per garantire che ogni transazione sia attribuita correttamente.

Per garantire il corretto funzionamento di questi flussi, è indispensabile eseguire una configurazione preliminare e rigorosa delle entità di base all'interno di SIGEAdb, come descritto nel capitolo seguente.

1. Configurazione Iniziale delle Entità Core

La corretta codifica delle entità fondamentali in SIGEAdb è il prerequisito indispensabile per qualsiasi operazione di sincronizzazione. Una configurazione accurata di depositi, clienti e delle loro associazioni garantisce che i flussi di dati vengano instradati, interpretati e processati correttamente da entrambi i sistemi. Ogni passaggio descritto di seguito è cruciale per costruire una solida architettura di integrazione.

1.1. Codifica del Deposito Punto Vendita

Il primo passo consiste nel creare un'entità logistica in SIGEAdb che rappresenti fisicamente il punto vendita. Questa operazione si esegue dal modulo Magazzino, nella maschera Anagrafica Depositi.

I campi critici da configurare per ogni nuovo deposito sono:

Codice Deposito: Per convenzione consolidata, la numerazione dei depositi destinati ai punti vendita parte da 501.
Natura: È obbligatorio impostare questo campo al valore 50 (Tipologia deposito punto vendita). Questo parametro è fondamentale, in quanto viene utilizzato dalle procedure di sincronizzazione per filtrare e riconoscere unicamente i depositi che rappresentano punti vendita, escludendo tutti gli altri magazzini.
Causale Conferma Allestimenti: Questo campo permette di pre-impostare la causale di magazzino utilizzata durante la conferma delle liste di prelievo (picking) destinate al punto vendita. La sua configurazione automatizza il processo logistico e riduce il rischio di errori di inserimento manuale da parte degli operatori.
Centro di Costo/Ricavo: Questi campi devono essere compilati solo se l'azienda gestisce la contabilità analitica e desidera associare costi e ricavi specifici a ogni punto vendita.
Codice Cliente Associato: Questo campo rappresenta il fulcro del collegamento tra l'entità logistica (il deposito) e quella commerciale/amministrativa (il cliente). Verrà compilato dopo aver creato la relativa anagrafica cliente, come descritto nel passaggio successivo.

1.2. Creazione del Cliente Associato

Per ogni punto vendita, è necessario creare una corrispondente anagrafica cliente in SIGEAdb (Anagrafica Soggetti Clienti). Questa logica offre un vantaggio strategico fondamentale: permette di utilizzare i report e le statistiche standard di Sigea (basate sul cliente) per monitorare il fatturato e la movimentazione di magazzino per singolo punto vendita.

Durante la creazione dell'anagrafica cliente, il campo chiave da configurare è Deposito Associato. In questo campo va inserito il codice del deposito creato nel passaggio precedente (es. 501). Questa operazione crea il legame inverso, dall'anagrafica cliente al deposito fisico, completando l'associazione bidirezionale tra le due entità. Con questa operazione, e con la successiva valorizzazione del campo Codice Cliente Associato sull'anagrafica del deposito, il legame logico-commerciale tra punto vendita e cliente è completo e bidirezionale.

1.3. Associazione del Fornitore Principale

All'interno dell'anagrafica cliente del punto vendita, nella sezione Altro Rapporto, è essenziale associare un fornitore principale. Questo fornitore è tipicamente il magazzino centrale (Cedi) da cui il punto vendita si approvvigiona.

Questa associazione è un parametro critico richiesto da EVO durante la sincronizzazione, in particolare per la corretta gestione dei resi e delle consegne. Permette a EVO di identificare in modo univoco la provenienza della merce e di instradare correttamente i flussi informativi relativi.

1.4. Mappatura Codici Sigea-EVO

Questo passaggio finale agisce da "traduttore" tra i due sistemi, che utilizzano codifiche interne differenti per identificare i punti vendita. Mentre Sigea usa i propri codici deposito (es. 501), EVO ha una propria codifica specifica (es. 100001).

La relazione tra questi due codici viene stabilita nella tabella procedurale situata nel modulo Amministrazione, al percorso 3.9 -> Parametri -> Punti Vendita.

Per ogni punto vendita, è necessario creare una riga in questa tabella dove si stabilisce l'associazione. Ad esempio:

Al codice punto vendita **100001** (codice usato da EVO) viene associato il deposito **501** (codice usato da Sigea).

Questa mappatura è vitale per il flusso di importazione degli ordini: quando Sigea riceve un file da EVO contenente il codice 100001, utilizza questa tabella per tradurlo nel deposito 501 e, di conseguenza, nel cliente associato, permettendo la creazione automatica dell'ordine.

Una volta definite queste entità di base, è possibile procedere con l'impostazione dei parametri tecnici che governano il processo di sincronizzazione.

2. Configurazione dei Parametri di Sincronizzazione

Questa fase riguarda la configurazione del "motore" del processo di integrazione. Qui si definiscono le regole tecniche, le connessioni ai database, i protocolli di trasferimento file e le tabelle specifiche da includere nel flusso di dati. Queste impostazioni sono centralizzate e garantiscono che la comunicazione tra Sigea ed EVO avvenga in modo standardizzato e controllato.

2.1. Parametri Generali nella Tabella Procedurale

La tabella procedurale Evo funge da pannello di controllo centrale per la comunicazione con il sistema dei punti vendita. Contiene parametri fondamentali per il corretto funzionamento di tutti i flussi.


Parametro	Descrizione e Impatto Strategico
`Gruppo DB`	Contiene le credenziali di connessione (utente, password, indirizzo IP) necessarie a Sigea per accedere e scrivere direttamente sulle "tavole di frontiera" del database di EVO (SQL Server). Questo abilita l'esportazione in tempo reale delle anagrafiche.
`Portale SFTP`	Definisce l'indirizzo del server SFTP e la cartella specifica dove EVO deposita i file degli ordini da importare in Sigea. Le procedure di import di Sigea monitorano questa locazione per acquisire i nuovi file.
`Indirizzi Email per Errori`	Elenco di indirizzi email che riceveranno notifiche automatiche in caso di anomalie o fallimenti nei processi di sincronizzazione schedulati. Permette un intervento proattivo in caso di problemi.
`Causali Movimenti`	Mappa le diverse tipologie di transazione importate da EVO (es. vendite da scontrino, resi da cliente, DDT emessi dal punto vendita) alle corrispondenti causali di magazzino in Sigea. Questa mappatura è fondamentale per la corretta registrazione contabile e logistica di ogni movimento e gestisce anche la logica di calcolo dell'IVA (scorporo per i corrispettivi).

2.2. Abilitazione Tabelle per l'Export (XRTB)

La tabella XRTB, accessibile da Servizi -> Manutenzione -> XRTB, agisce come un registro centrale che determina quali tabelle di SIGEAdb (e quindi quali informazioni anagrafiche e commerciali) devono essere esportate verso EVO.

ATTENZIONE: Questa configurazione deve essere eseguita a sistema fermo, senza utenti attivi.

L'attivazione di una tabella per l'export (tramite l'apposito flag di attivazione) provoca la creazione dinamica di trigger (insert, update, delete) sul database di SIGEAdb. Questi trigger hanno il compito di intercettare ogni modifica apportata ai dati in tempo reale e di registrarla in una tabella di log specifica (MCON). Le procedure di sincronizzazione ordinaria leggeranno poi questa tabella di log per inviare a EVO solo le variazioni incrementali, ottimizzando il processo.

Il parametro "Eventi Abilitati" permette un controllo granulare, consentendo di decidere quali operazioni (inserimento, modifica, cancellazione) debbano generare un record da esportare.

Completata la configurazione dei parametri tecnici e delle tabelle da esportare, si può procedere con le operazioni di invio dei dati da Sigea verso EVO.

3. Procedure di Esportazione Dati (Sigea verso EVO)

L'esportazione dei dati da Sigea a EVO è un processo strategico che assicura che i punti vendita operino sempre con informazioni allineate al sistema centrale. Questo previene disallineamenti su anagrafiche articoli, prezzi e assortimenti, che potrebbero causare errori di vendita, di ordinazione o di gestione delle giacenze.

3.1. Architettura del Processo e Meccanismo del "Semaforo"

A differenza di altri flussi basati su file, l'export di Sigea verso EVO avviene scrivendo i dati direttamente in tabelle dedicate del database di EVO, note come "tavole di frontiera". Per gestire l'accesso concorrente a queste tabelle ed evitare conflitti, il sistema utilizza un meccanismo di locking basato su una tabella di controllo chiamata V semaforo.

Il funzionamento del semaforo è regolato da due flag e garantisce che solo un sistema alla volta (Sigea o EVO) possa operare sui dati. Lo stato del semaforo è sempre visibile nell'intestazione delle maschere di sincronizzazione.


Stato Flag `attività in corso`	Stato Flag `esporta dati`	Significato e Azione Permessa
Spento	Spento	Sistema Libero. Sigea ha il permesso di iniziare a scrivere sulle tavole di frontiera.
Acceso	Spento	Scrittura in corso da parte di Sigea. Sigea sta popolando le tavole. EVO è in attesa e non può leggere.
Spento	Acceso	Dati Pronti per la Lettura. Sigea ha terminato la scrittura. EVO può iniziare a leggere e importare i dati.
Acceso	Acceso	Lettura in corso da parte di EVO. EVO sta importando i dati. In questo stato, Sigea è in attesa e non può avviare un nuovo export.

3.2. Modalità "Prima Installazione / Refresh"

Questa modalità viene utilizzata in due scenari specifici:

Per l'attivazione di un nuovo punto vendita, al fine di inviare l'intero set di dati anagrafici per la prima volta.
Per eseguire un reinvio massivo e completo dei dati in caso di gravi disallineamenti o per forzare un riallineamento totale.

La procedura si esegue dalla maschera 2.22 Aggiornamenti Sistemi Periferici -> Export e segue questi passaggi:

È fondamentale tenere conto delle seguenti dipendenze critiche, imposte dalla logica di importazione di EVO:

Esportazione EAN (**AGM**): Richiede obbligatoriamente l'esportazione simultanea di Anagrafica Articoli (**AMG**) e Assortimento.
Esportazione Assortimento Generale: Richiede obbligatoriamente l'esportazione simultanea di Anagrafica Articoli (**AMG**).

Questa operazione può richiedere molto tempo e un notevole utilizzo di risorse, pertanto deve essere pianificata in orari di bassa attività operativa.

3.3. Modalità "Ordinaria"

Questa è la modalità standard per l'esportazione incrementale. Il suo scopo è inviare a EVO solo le modifiche (nuovi inserimenti, variazioni, cancellazioni) registrate nella tabella di log MCON dall'ultimo export eseguito.

A differenza della modalità "Refresh", questa procedura non è interattiva. Una volta avviata, processa automaticamente tutte le modifiche registrate per tutte le tabelle candidate, senza permettere una selezione manuale delle entità da sincronizzare.

Conclusa la panoramica sull'esportazione, il capitolo successivo analizzerà il flusso di dati inverso: l'importazione degli ordini dai punti vendita.

4. Procedura di Importazione Ordini (EVO verso SIGEAdb)

L'importazione automatica degli ordini generati dai punti vendita è un flusso di dati cruciale che centralizza e standardizza il processo di approvvigionamento. Questo sistema riduce drasticamente l'inserimento manuale, minimizza il rischio di errori e accelera i tempi di evasione da parte del magazzino centrale.

Il processo di importazione segue una sequenza logica ben definita:

Deposito File: Periodicamente, il sistema EVO di ciascun punto vendita genera e deposita i file degli ordini (in formato testo, es. CD ord P. ORD B) in una cartella dedicata sul portale SFTP, il cui indirizzo è configurato nella tabella procedurale Evo.
Struttura del File: Ogni file d'ordine ha una struttura predefinita che contiene le informazioni chiave utilizzate da SIGEAdb per il processamento:
- Codice Punto Vendita: Il codice identificativo del negozio secondo la codifica di EVO.
- Codice EAN: Il codice a barre dell'articolo ordinato.
- Quantità: Un valore numerico che, a seconda della configurazione concordata, può rappresentare il numero di colli o di singoli pezzi.
Processo di Elaborazione in Sigea: Le procedure schedulate di Sigea si collegano al portale SFTP, prelevano i file d'ordine e li elaborano. Per ogni riga d'ordine, il sistema:
- Legge il Codice Punto Vendita di EVO.
- Utilizza la tabella di mappatura (configurata nel capitolo 1.4) per tradurlo nel corrispondente codice deposito e, di conseguenza, nel cliente associato in Sigea.
- Identifica l'articolo tramite il codice EAN.
- Genera automaticamente una riga sull'ordine cliente, intestando il documento al cliente corretto.

Una volta gestiti i flussi standard di anagrafiche e ordini, è importante analizzare i flussi transazionali specifici, come i documenti di trasporto.

5. Gestione Flussi Transazionali Specifici

Oltre alle anagrafiche e agli ordini, il sistema sincronizza anche specifici movimenti di magazzino per mantenere perfettamente allineate le giacenze tra il magazzino centrale (Cedi) e i singoli punti vendita, garantendo una visibilità accurata e in tempo reale dello stock.

5.1. Esportazione Documenti di Consegna (DDT)

Lo scopo di questo flusso è comunicare a EVO l'avvenuta spedizione di merce dal Cedi verso un punto vendita. Quando Sigea emette un Documento di Trasporto (DDT) per un trasferimento, questo movimento deve essere notificato a EVO per permettere al software del punto vendita di eseguire il carico automatico del proprio magazzino, semplificando le operazioni di ricezione merce.

Il processo tecnico si articola nei seguenti passaggi:

Sigea genera un DDT di trasferimento merce dal magazzino centrale al deposito del punto vendita.
Una procedura schedulata, denominata Riepilogo spedizioni, elabora periodicamente tutti i DDT emessi che soddisfano i criteri di esportazione.
La procedura scrive i dettagli di ogni DDT (mittente, destinatario, articoli, quantità) sulla tavola di frontiera Vattina nel database di EVO.

Questo specifico flusso è soggetto a due vincoli fondamentali che ne governano l'esecuzione:

Vincolo sulla Causale: Vengono esportati esclusivamente i documenti la cui causale di magazzino ha il flag "Avviso Spedizione" attivo. Questa impostazione permette un controllo selettivo e granulare su quali tipologie di movimento debbano essere comunicate a EVO.
Vincolo sulla Tabella **Vattina**: Per questa tabella vige una regola unica e restrittiva. La procedura di export di Sigea non scrive alcun dato se la tabella Vattina non è completamente vuota, anche se il semaforo principale (V semaforo) è libero. Questo meccanismo di sicurezza previene la sovrascrittura di dati di consegna non ancora elaborati da EVO, garantendo che nessuna spedizione venga persa.

Il capitolo finale è dedicato alla risoluzione dei problemi più comuni che un amministratore può incontrare durante la gestione di questi flussi.

6. Manutenzione e Risoluzione Problemi (Troubleshooting)

Nonostante la robustezza del sistema di sincronizzazione, possono verificarsi anomalie dovute a problemi di rete, errori sui dati o interventi manuali imprevisti. Questo capitolo fornisce una guida pratica per diagnosticare e risolvere gli scenari problematici più frequenti.

6.1. Gestione del Semaforo di Sincronizzazione Bloccato

Scenario: L'utente tenta di avviare un'esportazione da Sigea ma riceve il messaggio di errore "Attività in corso", che impedisce di procedere.

Diagnosi e Risoluzione: Seguire questa checklist per identificare la causa e ripristinare il sistema.

Verifica Preliminare: Contattare sempre il referente del punto vendita e chiedere di verificare con il supporto EVO se sono in corso attività di manutenzione o elaborazioni sul loro sistema. In caso affermativo, è sufficiente attendere il completamento delle loro operazioni.
Analisi Stato Tabelle di Frontiera: Se EVO non sta eseguendo alcuna attività, accedere direttamente al database di EVO (SQL Server) e controllare se le tabelle di frontiera (es. quelle degli articoli o dei listini) sono piene o vuote.
Azione Correttiva (Tabelle Piene): Se le tabelle contengono dati, significa che Sigea ha completato la scrittura ma EVO non ha ancora iniziato (o completato) la lettura. Per sbloccare la situazione, è necessario forzare la condizione di 'Dati Pronti per la Lettura' (lo stato in cui Sigea si pone al termine di un export corretto) modificando manualmente la tabella V semaforo:
- Impostare il flag attività in corso a spento.
- Impostare il flag esporta dati a acceso.
Azione Correttiva (Tabelle Vuote): Se le tabelle di frontiera sono vuote ma il semaforo è bloccato, è probabile che un processo precedente (di Sigea o di EVO) si sia interrotto in modo anomalo. In questo caso, è necessario resettare completamente il semaforo per permettere a Sigea di scrivere di nuovo:
- Impostare il flag attività in corso a spento.
- Impostare il flag esporta dati a spento.

In Sigea esiste una funzione di manutenzione (Ripristina stato esportare), ma se ne consiglia l'uso con cautela. È sempre preferibile eseguire un'analisi manuale per comprendere la causa radice del blocco prima di forzare un ripristino.

6.2. Analisi di Errori Comuni in Fase di Import da Parte di EVO

Scenario: Un export da Sigea viene completato con successo, ma il cliente segnala che i dati non sono stati aggiornati su EVO perché il loro processo di importazione si è bloccato.

Causa del Problema: Il sistema EVO applica regole di integrità dei dati molto rigide. Un'anomalia nei dati inviati da Sigea può causare l'interruzione immediata dell'intero processo di importazione. Un esempio concreto è la presenza dello stesso codice EAN associato a più articoli in Sigea. Per EVO, questa è una condizione bloccante che ferma l'acquisizione di tutti i dati successivi.

Soluzione:

Correggere l'Anomalia: Identificare e correggere l'incoerenza dei dati direttamente in Sigea (es. utilizzare le utility per normalizzare gli EAN duplicati).
Eseguire un Nuovo Export Completo: Dopo aver sanato i dati, è necessario eseguire nuovamente un export in modalità "Prima Installazione / Refresh". Durante questo export, è fondamentale riesportare non solo la tabella che conteneva l'errore, ma anche tutte le tabelle dipendenti per garantire la coerenza complessiva del set di dati inviato. Ad esempio, nel caso dell'errore EAN, si dovranno riesportare simultaneamente **Articoli, EAN e Assortimento.