Repository ocmis-web¶

Panoramica¶

Il repository ocmis-web contiene i moduli che acquisiscono i dati dalle macchine Ocmis installate in tutto il mondo, memorizzandoli sul database ocmis_machinedata.

Il repository ospita due versioni del servizio:

Versione	Linguaggio	Stato
Originale	PHP	Legacy, ancora in produzione
Nuova	Go	In sviluppo / migrazione

La documentazione seguente fa riferimento alla versione Go.

Vedi anche

Per una descrizione approfondita dell'architettura dei backend dei singoli tipi macchina (pivot, lineare, motopompa, rotolone, ippodromo), pattern condiviso, ciclo di vita richieste e struttura dei package, vedere Architettura backend macchine.

Struttura del progetto¶

Il progetto Go e' organizzato in una cartella principale server_go con moduli suddivisi per area funzionale.

Cartella	File	Funzione
`common`	`common.go`	Dati comuni disponibili a tutto il progetto
`main`	`db.go`	Funzioni di connessione al database
`main`	`logs.go`	Preparazione e scrittura del log
`main`	`main.go`	Attivazione del processo e messa in ascolto del servizio
`main`	`router.go`	Preparazione del router di connessione e dispatching per tipo macchina
`motopompa`	`readData.go`	Scambio dati con le macchine di tipo motopompa

Database interessati¶

farmfront_portalcfg¶

All'interno del progetto e' identificato come dbCfg.

Da questo database si legge solo la tabella machines_digital, usata per capire se il segnale arrivato appartiene a una macchina esistente nel sistema.

Tabella	Uso
machines_digital	Verifica esistenza macchina (id, tipo, azienda)
cust_digital	Dati cliente associato alla macchina (mail, fuso orario)

ocmis_machinedata¶

All'interno del progetto e' identificato come dbData.

Qui viene memorizzato lo stato dei log per ciascuna macchina e i dati ricevuti, con tabelle dedicate per tipo macchina.

Tabella	Uso
machine_log	Stato log per ciascuna macchina (1 riga per macchina)
motop_variabili	Variabili ricevute dalle motopompe (JSON + timestamp)
motop_costanti	Costanti ricevute dalle motopompe (JSON + timestamp)
motop_portale	Stato portale per ciascuna motopompa (comandi da inviare)

Ambiente di test¶

Per verificare il comportamento lato DB durante l'acquisizione dati macchine, si usa l'ambiente alpha.

Parametro	Valore
URL	https://alpha.irrigation-dataserver.com/
Utente	[email protected]
Password	Test!1234

Dal pannello laterale si vedono tutte le macchine associate all'utente (una per tipo) e si puo' verificare l'effetto della modifica dei parametri.

motopompa¶

ReadData — analisi body¶

Il body ricevuto puo' contenere una sola sezione tra:

constants
variables

Ogni sezione e' elaborata in modo indipendente.

Db interessati¶

farmfront_portalcfg

machines_digital
cust_digital

ocmis_machinedata

machine_log
motop_variabili
motop_costanti
motop_portale

Riepilogo risposte¶

aggiornamento	Situazione	Dati aggiornati	Valore
0	Risposta con problemi o nessun dato da aggiornare
1	Risposta corretta, macchina accesa	Insieme di parametri tecnici
2	Ricevuto timestamp nel futuro (ora macchina errata)	aggiornamentoOraDaCloud	Ora attuale +/- offset fuso orario
3	Risposta corretta, richiesto azzeramento allarmi da portale	Solo timestamp

variables¶

LoadVariables¶

Ricerca macchina¶

Esegue una query su machines_digital con i filtri:

Macchina = id trovato
tipo = M
Azienda = Azienda configurata

Se la macchina non e' trovata, scrive un record su machine_log ed esce.

Se e' trovata, recupera la mail dal cliente associato (da cust_digital) e il fuso orario.

Gestione email¶

Se nel JSON esiste il parametro MailRegistrata e non corrisponde alla mail del cliente associato, viene salvata l'informazione mailModificata.

Aggiornamento log¶

Dopo le operazioni precedenti viene aggiornato il record machine_log.

Richiesta futura¶

Se la richiesta arriva con timestamp nel futuro:

Invio messaggio di aggiornamento con:
aggiornamento = 2
aggiornamentoOraDaCloud = ora attuale +/- offset fuso orario

Aggiornamenti (in transazione)¶

Inserimento riga in motop_variabili (contiene il JSON ricevuto e alcuni campi timestamp)
Aggiornamento riga in motop_portale
Nell'esecuzione di variables si da' per scontato che il record esista gia', perche' i dati principali arrivano dalle costanti
Aggiornamento di entrambi i log per la macchina su machine_log (sia quello di variabili sia quello di costanti)

Elaborazioni finali¶

In caso di completamento dell'operazione vengono eseguite operazioni comuni:

checkMessaggistica
inviaDati

constants¶

LoadConstants¶

Ricerca macchina¶

Esegue una query su machines_digital con i filtri:

Macchina = id trovato
tipo = M
Azienda = Azienda configurata

Se la macchina non e' trovata, scrive un record su machine_log ed esce.

Se e' trovata, recupera la mail dal cliente associato (da cust_digital) e il fuso orario.

Gestione email¶

Se nel JSON esiste il parametro MailRegistrata e non corrisponde alla mail del cliente associato, viene salvata l'informazione mailModificata.

Aggiornamento log¶

Dopo le operazioni precedenti viene aggiornato il record machine_log.

Richiesta futura¶

Se la richiesta arriva con timestamp nel futuro:

Invio messaggio di aggiornamento con:
aggiornamento = 2
aggiornamentoOraDaCloud = ora attuale +/- offset fuso orario

Aggiornamenti (in transazione)¶

Inserimento riga in motop_costanti (contiene il JSON ricevuto e alcuni campi timestamp)
Aggiornamento riga in motop_portale
I dati principali per il record motop_portale arrivano dalle costanti

Elaborazioni finali¶

In caso di completamento dell'operazione vengono eseguite operazioni comuni:

checkMessaggistica
inviaDati

checkMessaggistica¶

Sezione indipendente che controlla se, nel JSON ricevuto, i flag di allarme sono diversi rispetto a quelli memorizzati sul database. In tal caso invia una segnalazione.

Estrazione segnalazioni: tramite una query che confronta i valori di variabili e costanti per la macchina, genera campi con alias che rappresentano codici di "errore" e di "warning"
Vengono estratte le ultime due righe del confronto: serve a capire se con l'ultimo aggiornamento esiste una variazione tra gli stati precedenti e quelli appena ricevuti
Vengono segnalate solo le transizioni da "spento" ad "acceso", non il contrario

Questa elaborazione non influisce sullo stato della risposta, che resta comunque 200.

inviaDati¶

Sezione indipendente che prepara il JSON da restituire al termine della chiamata, con una serie di campi di risposta.

La logica e' la seguente:

Cerca su motop_portale se la macchina esiste e se ha mpo_aggiornato in (1, 3)
NO: esegue checkTimeAndMail (invio risposta "2" nel caso in cui il cliente abbia una mail diversa o il timestamp del messaggio sia piu' vecchio di 30 secondi)
SI:
- mpo_aggiornato = 1 (comandi da inviare): invia una serie di dati in risposta
- mpo_aggiornato = 3 (spegnimento allarme): invia solo il timestamp in risposta

rotolone¶

Test rotolone¶

I test del modulo rotolone si considerano positivi solo se l'elaborazione eseguita dalla versione PHP restituisce un risultato analogo a quella Go.

Tipo JSON	Caso	Test
costanti	Risposta da `roto_portale` con `rpo_aggiornato` = 1 (`dati_salvati` se `datiPortale` != nil)	Ok
costanti

Funzioni comuni di utilita'¶

checkTimeAndMail¶

Funzione che riceve in input:

Parametro	Descrizione
TimeZone	Fuso orario del cliente
TimeStamp	Timestamp ricevuto nel body
Email	Email del cliente

Viene eseguita dai singoli processi di ricezione dati dalle macchine quando, durante l'invio dati, non si e' in grado di recuperare i dati della macchina con aggiornamento 1 o 3.

In questo contesto la funzione restituisce una risposta al chiamante seguendo altre logiche. Sara' il chiamante a inviarla.

I casi gestiti sono:

TimeStamp del body piu' vecchio di 30 secondi
aggiornamento = 2
aggiornamentoOraDaCloud = ora del server rispetto al fuso del cliente
Mail del cliente diversa da quella indicata
Come sopra, ma aggiunge anche l'informazione mailModificata

formattaRisposta¶

Prepara un messaggio di risposta gia' formattato, utilizzabile generalmente in una risposta standard.

Parametro input	Descrizione
Messaggio di risposta	map di stringhe
MettiSpazio	Flag

Restituisce:

Una stringa (la macchina non si aspetta un vero JSON)
Un eventuale errore

replyErr¶

Risponde con un messaggio formattato nel seguente modo:

{
  "aggiornamento": n,
  "details": messaggio
}

Riceve in input:

Parametro	Descrizione
fiber.ctx	Contesto della richiesta
status	Codice HTTP (es. 400)
CodiceRisposta	Valore `aggiornamento`
messaggio	Testo di dettaglio

replyStd¶

Risponde a una richiesta eseguita con successo. Il formato della risposta e' identico a replyErr:

{
  "aggiornamento": n,
  "details": messaggio
}

Riceve in input gli stessi parametri di replyErr:

Parametro	Descrizione
fiber.ctx	Contesto della richiesta
status	Codice HTTP
CodiceRisposta	Valore `aggiornamento`
messaggio	Testo di dettaglio

prepareReply¶

Prepara un messaggio di risposta gia' formattato in caso di errore, con due soli elementi:

aggiornamento: n
details: messaggio

Internamente usa formattaRisposta per produrre la stringa "simil-JSON" necessaria alle macchine.

Service — Assist¶

Area dedicata ai servizi di assistenza. Include le procedure di pulizia ambiente e i test da eseguire in fase di validazione.

Pulizia ambiente per test¶

Elenco delle tabelle e delle query di pulizia eseguite per preparare l'ambiente di test da zero.

Tabelle anagrafiche

arpmerci
arpmeser
arplisti
arpsconti
arpgruppisconto
arpanagr
apasnmatri
arpprest
arpcontt
apcogdesti
arparmag
arpsnmag
arpslmag

Movimentazione

arpintes
arpintes2
arpintec
arpindet
arpchdet
arpindoc
arpchprp
arpscpex

Query SQL di pulizia (azienda X04398):

DELETE from arpmerci where rmer_azi = 'X04398';
DELETE from arpmeser where rmers_azi = 'X04398';
DELETE from arplisti where rlis_azi = 'X04398';
DELETE from arpsconti where a_scc_azienda = 'X04398';
DELETE from arpgruppisconto where a_gst_azienda = 'X04398';
DELETE from arpanagr where rana_azi = 'X04398';
DELETE from apasnmatri where a_amtr_azienda = 'X04398';
DELETE from arpprest where rpre_azi = 'X04398';
DELETE from arpcontt where rrif_azi = 'X04398';
DELETE from apcogdesti where a_dst_azi = 'X04398';
DELETE from arparmag where a_armag_azi = 'X04398';
DELETE from arpsnmag where a_snm_azi = 'X04398';
DELETE from arpslmag where rpmsalc_azi = 'X04398';

DELETE from arpintes where rcit_azi = 'X04398';
DELETE from arpintes2 where rcit2_azi = 'X04398';
DELETE from arpintec where rcin_azi = 'X04398';
DELETE from arpindet where rcid_azi = 'X04398';
DELETE from arpchdet where rcht_azi = 'X04398';
DELETE from arpindoc where rind_azi = 'X04398';
DELETE from arpchprp where rchp_azi = 'X04398';
DELETE from arpscpex where a_scpe_azi = 'X04398';

Test da eseguire¶

Oggetto	Tipo test	Esito
Anagrafica clienti	Import	Vengono importati solo alcuni clienti: da verificare l'import massivo
Anagrafica contatti	Import
Anagrafica destinazioni	Import
Anagrafica merci	Import
Anagrafica prestazioni	Import
Anagrafica listini + sconti	Import
Anagrafica matricole	Import