DHS Agent — Guida all'uso

Che cos'è

DHS Agent legge l'archivio di Quaderno Elettronico installato nello studio, ne ricava i dati che servono agli agenti DHS (Victoria, GaLa, Tao e Flux) e li consegna, cifrati, al server che genera le loro basi di conoscenza. Tutto in circa quindici secondi, una o più volte al giorno, senza che nessuno debba ricordarsene.

L'archivio viene aperto in sola lettura: l'agente non modifica mai i dati dello studio e non tocca i file di indice. L'unica connessione che stabilisce è quella in uscita verso il server di consegna; non resta in ascolto su alcuna porta.

1.Installazione in breve

1. Creare una cartella sul disco locale, per esempio C:\DHS-Agent.
2. Copiarvi dhs-agent.exe, dhs-agent-gui.exe, i file .bat numerati e config.example.json rinominato in config.json.
3. Avviare 09-configurazione.bat e compilare le schede come descritto qui sotto.
4. Avviare 01-prima-importazione.bat e attendere il completamento.
5. Avviare 04-esporta.bat per il primo export e la prima consegna.

La procedura completa, con prerequisiti e checklist, è nel documento INSTALLAZIONE.md fornito con il programma.

2.Scheda Studio

Qui si dice all'agente chi è lo studio e dove sono i dati. È l'unica scheda che va compilata per forza.

Codice cliente

Il codice assegnato allo studio. Finisce nel nome dell'archivio DHSE_<codice>.zip ed è la chiave con cui il server distingue i clienti: deve essere quello giusto.

Nominativo

Il nome dello studio, riportato nei file di servizio.

Cartella di lavoro

Dove l'agente tiene il proprio database e i file temporanei. In una installazione standard è C:\DHS-Agent\data.

Archivio QE (radice)

La cartella che contiene i due rami dell'archivio. Indicandola, i due campi sottostanti si compilano da soli.

Ramo L e Ramo Q

I due rami dell'archivio: L contiene l'anagrafica degli utenti, Q tutti i dati clinici. Di norma sono <radice>\L\WINDENT e <radice>\Q\WINDAT, ma se in questo studio sono su unità mappate vanno corretti a mano. Quello che conta è che dentro ciascun ramo ci sia una sottocartella DATI con i file .DBF.

3.Scheda Export

Governa cosa viene prodotto e permette di lanciare un export a mano.

Data di riferimento

Lasciare spuntato usa la data odierna. Il campo della data fissa serve unicamente a riprodurre un archivio storico.

Cartella archivio prodotto

Dove viene depositato DHSE_<codice>.zip prima dell'invio.

Tracciati da produrre

Permette di escludere gli agenti che lo studio non usa. In dubbio, lasciarli tutti attivi: è l'unica combinazione verificata a fondo.

Invia al server dopo l'export

Se spuntata, al termine dell'export l'archivio parte subito.

Esporta ora

Esegue l'export immediatamente. Richiede una quindicina di secondi e l'avanzamento compare nel registro in basso.

4.Scheda Invio

Le coordinate del server che riceve l'archivio, e la password per accedervi.

Server, porta, cartella remota, utente

Come da credenziali fornite per lo studio.

Password

Si digita qui una sola volta. Al salvataggio viene cifrata con la protezione dati di Windows e il campo si svuota. Il file che ne risulta è leggibile solo dall'utente Windows che l'ha creata e solo su quel computer: copiarlo altrove non serve a nulla.

Credenziale in uso

Indica da dove il programma sta prendendo la password in questo momento, senza mostrarla. Utile per capire se è stata salvata davvero.

Cifratura

Lasciare explicit: è FTPS, cioè trasferimento cifrato. Usare none solo se il server non supporta TLS.

Nome sul certificato

Da compilare solo se il certificato del server è emesso per un nome diverso dall'indirizzo FTP — sugli hosting condivisi succede quasi sempre. Il messaggio d'errore della prova di connessione dice qual è il nome giusto.

Prova connessione

Verifica accesso e credenziali senza trasferire nulla, ed elenca il contenuto della cartella remota. È il primo strumento da usare quando la consegna non funziona.

5.Scheda Pianificazione

Quando l'agente deve lavorare da solo.

Esegui un ciclo all'avvio

Utile sui computer che vengono spenti ogni sera: il lavoro parte all'accensione invece che a un'ora fissa.

Ogni N minuti

Cadenza regolare. Lasciare 0 per disattivarla.

Orari fissi

Uno o più orari giornalieri separati da virgola. 01:30 va bene se il computer resta acceso di notte; altrimenti conviene un orario di pausa, per esempio 13:30.

Sincronizza il database prima di esportare

Da lasciare spuntato: garantisce che l'export parta da dati aggiornati.

Il programma che esegue la pianificazione si avvia con 08-scheduler.bat e va lasciato aperto. Per farlo partire da solo a ogni accesso, spuntare avvio automatico nella scheda Avanzate.

6.Scheda QUaESTio

Produce il report «Statistiche produzione» in PDF. È l'unica scheda che richiede un aggiornamento periodico, perché turni, ferie e permessi non stanno nel gestionale: li fornisce lo studio.

Periodo

Primo mese in formato AAAA-MM e numero di mesi da includere.

Medici stampati / Medici attivi

I primi ricevono un blocco dedicato nel report; i secondi partecipano al calcolo dei valori medi di studio. Sono elenchi di codici separati da virgola.

Codici prima visita

Gli onorari che vanno considerati prima visita.

Griglia turni, ferie e permessi

Una riga per medico e per mese. Si seleziona una riga per modificarla, si compilano i campi in basso e si preme Aggiungi / aggiorna; oppure si inseriscono un medico e un mese nuovi. Il medico 0 raccoglie i totali dell'intero studio.

Genera report PDF

Produce il documento nella cartella indicata in alto.

7.Scheda Avanzate

Parametri di calcolo, avvisi automatici e avvio con Windows.

Parametri di calcolo

Sono le regole con cui vengono interpretati i dati: la durata oltre la quale un appuntamento è considerato un blocco d'agenda anziché una prestazione, i giorni di preavviso sulle scadenze dei lotti, la finestra su cui si calcolano i consumi, il marcatore che identifica i pazienti fittizi e i nomi utente esclusi dalle statistiche comparative.

Notifica errori

Spuntando avvisa e quando un ciclo fallisce, e indicando un server di posta con i destinatari, il programma manda una mail ogni volta che un'esportazione automatica non va a buon fine, dicendo quale fase è fallita. Il pulsante Invia prova recapita un messaggio di verifica.

Avvio automatico

Spuntando la casella, la pianificazione parte da sola a ogni accesso a Windows. Non servono privilegi di amministratore e la voce resta visibile — e removibile — nella scheda Avvio di Gestione attività.

8.Impostazioni a distanza

Alcuni parametri si possono cambiare senza raggiungere la postazione: basta depositare un file nello spazio di consegna dello studio. L'agente lo legge all'inizio di ogni ciclo pianificato, applica ciò che è ammesso, lo annota nel registro e ricarica una ricevuta.

Come si fa

1. Si crea un file di testo chiamato settings-<codice>.json — per lo studio 1001, settings-1001.json.
2. Lo si deposita nella stessa cartella dove arrivano gli archivi dello studio.
3. Al ciclo successivo l'agente lo recepisce. Per non aspettare, sulla postazione si può lanciare dhs-agent.exe settings -config config.json.
4. L'agente ricarica applied-<codice>.json con la versione recepita, l'ora e l'elenco delle modifiche: serve a verificare a colpo d'occhio quali studi hanno applicato le impostazioni.

Esempio di file completo:

{
  "version": 3,
  "note": "spostato l'export alle 02:15",

  "schedule": {
    "at_startup": false,
    "every_minutes": 0,
    "daily_at": ["02:15"],
    "sync_before_export": true
  },
  "agents":  { "victoria": true, "gala": true, "tao": true, "flux": false },
  "calc":    { "flux_expiry_alert_days": 45 },
  "questio": { "from_month": "2026-04", "months": 3 },
  "notify":  { "on_success": true, "to": "studio@esempio.it" }
}

Che cosa si può cambiare, e che cosa no

L'elenco qui sotto non è una convenzione: è una lista bianca applicata dal programma. Qualunque altra chiave viene ignorata e segnalata nel registro.

Il programma controlla anche i valori, non solo i nomi: un orario mal scritto, un numero di mesi fuori scala o un indirizzo webhook che non sia https vengono scartati singolarmente, lasciando applicare il resto. Anche questi finiscono nel registro.

9.Che cosa succede lato server

L'agente si ferma alla consegna dell'archivio. Da lì in poi lavora uno script PHP che gira sull'hosting, cron/kb-sync.php, avviato automaticamente ogni sei ore dal pannello dell'hosting. Conoscerne il comportamento serve soprattutto a capire perché un dato appena esportato non compare subito negli agenti.

Come si comporta, passo per passo

1. Si assicura di essere solo. Scrive un file di blocco: se un'altra esecuzione è già in corso esce subito. Se il blocco è più vecchio di trenta minuti lo considera abbandonato e prosegue, così un processo morto non paralizza il sistema.
2. Cerca gli archivi. Elenca tutti i file DHSE_*.zip presenti. Ogni studio ha il proprio, distinto dal codice cliente nel nome: un'unica installazione serve tutti gli studi.
3. Salta ciò che non è cambiato. Confronta la data dell'archivio con quella dell'ultima elaborazione. Se coincidono non fa nulla: rimandare lo stesso archivio non produce lavoro inutile.
4. Verifica che l'archivio sia integro prima di aprirlo. Se risulta danneggiato — per esempio un invio interrotto — lo segnala, manda un avviso e passa oltre senza registrare l'elaborazione: al ciclo successivo riprova da solo.
5. Estrae e cerca i cinque file che gli servono in una cartella temporanea. Se ne manca anche uno solo si ferma su quel cliente, sempre senza registrare l'elaborazione.
6. Calcola. Legge i file in streaming e produce i conteggi e le somme: è qui che nascono i numeri che gli agenti riportano.
7. Scrive la knowledge base in una cartella dedicata al singolo cliente, insieme a un riepilogo con data di generazione e versione.
8. Eventuale rilettura in linguaggio naturale. Se attivata, un passaggio di intelligenza artificiale trasforma i numeri in commenti discorsivi. È facoltativo e non bloccante: se fallisce, la knowledge base resta comunque valida.
9. Pulisce la cartella temporanea — ma non cancella l'archivio, che resta a disposizione per un controllo.
10. Registra l'avvenuta elaborazione solo se tutti i passaggi obbligatori sono riusciti.

Perché i numeri li calcola il PHP e non l'intelligenza artificiale

È una scelta deliberata. I conteggi e le somme riguardano decine di migliaia di righe e devono essere esatti al centesimo: un modello linguistico non è affidabile nel contarle. Il motore PHP calcola quindi i numeri in modo deterministico e quei file sono la fonte di verità; l'intelligenza artificiale interviene solo sopra i numeri già calcolati, per scriverne un commento leggibile.

Quanto tempo passa

Nel caso peggiore sei ore fra la consegna e l'aggiornamento degli agenti, perché tanto dista un'esecuzione dall'altra. È normale: se dopo un export i dati sembrano fermi, di solito basta attendere il ciclo successivo.

Quando qualcosa non va

Lo script tiene un registro giornaliero, conservato per trenta giorni, e in caso di errore invia una mail all'indirizzo tecnico configurato. Sono due canali distinti da quelli dell'agente sulla postazione: se un export parte correttamente ma i dati non si aggiornano, il problema va cercato in quel registro, non su quello dello studio.

10.Uso quotidiano

A regime non c'è nulla da fare: la pianificazione esegue in sequenza sincronizzazione, export e consegna, e registra ogni ciclo. Per controllare come è andata, aprire la finestra di configurazione e leggere il registro in basso, oppure il file data\scheduler.log.

I comandi rapidi

Quando serve intervenire

11.Se qualcosa non va

La consegna non riesce

Premere Prova connessione nella scheda Invio: il messaggio distingue i tre casi. Se parla di certificato, va compilato il campo «Nome sul certificato» con il nome che il messaggio stesso indica. Se parla di accesso, la password è sbagliata o è stata salvata da un altro utente Windows. Se non si collega affatto, è la rete o un blocco del firewall in uscita.

«Verifica archivio» non trova i file

Il percorso indicato non è quello giusto. Dentro ciascun ramo deve esistere una sottocartella DATI contenente file con estensione .DBF. Se l'archivio è su un'unità di rete, verificare che sia effettivamente raggiungibile con l'utente in uso.

L'export è andato bene ma gli agenti non vedono i dati nuovi

Nella maggior parte dei casi non è un guasto: il server elabora gli archivi ogni sei ore, quindi fra la consegna e l'aggiornamento può passare quel tempo. Se dopo un ciclo completo la situazione non cambia, il problema è lato server e va cercato nel suo registro, non su quello della postazione.

I dati sul server sembrano vecchi

Controllare nella scheda Export che sia spuntato usa la data odierna. Se al suo posto è impostata una data fissa, ogni consegna ripubblica i dati di quel giorno.

Le impostazioni depositate non vengono applicate

Nell'ordine: controllare che il nome del file corrisponda al codice dello studio, che il numero di version sia stato aumentato rispetto all'ultimo applicato, e che le sezioni usate siano fra quelle ammesse. Il registro dell'agente elenca sempre le chiavi ignorate e i valori scartati con il motivo. Se il file c'è ma la ricevuta applied-<codice>.json non compare, l'agente non lo sta nemmeno leggendo: verificare che le impostazioni a distanza siano attive nella configurazione della postazione.

Non arriva nulla al server

Verificare che nella scheda Invio sia spuntato invia l'archivio al server remoto, e che la pianificazione sia effettivamente in esecuzione: la finestra dello scheduler deve essere aperta, oppure l'avvio automatico attivo.

Verifica rapida

• Verifica archivio trova i DBF in entrambi i rami
• Prova connessione riesce ed elenca la cartella remota
• Invia prova recapita la mail di avviso
• Nella scheda Export è spuntato «usa la data odierna»
• L'avvio automatico è attivo