Excursus Generale

Relazione Tecnica: Architettura del Processo di Protocollazione Documentale

1.0 Introduzione

La seguente sezione ha lo scopo di descrivere l'architettura e il flusso operativo del sistema di protocollazione documentale. Questo sistema è un componente strategico per l'interfacciamento della piattaforma con l'ecosistema di sistemi di gestione documentale esterni adottati dagli enti pubblici. La sfida architetturale principale risiede nella necessità di integrarsi con un panorama di soluzioni di terze parti eterogeneo e in continua evoluzione, ognuna con API e modelli dati specifici. L'architettura qui presentata è stata concepita per risolvere tale sfida, standardizzando il processo di classificazione, fascicolazione e conservazione a norma degli atti amministrativi digitali, come le pratiche inviate dai cittadini.

Al cuore di questa architettura si trova il Proxy di Protocollazione. È essenziale chiarire che questo componente non è un sistema di gestione documentale in sé, ma agisce come un intermediario specializzato e intelligente. Il suo ruolo primario è ricevere un oggetto "Documento" standardizzato dalla piattaforma, trasformarlo nel formato specifico richiesto dal sistema esterno di destinazione e gestire in modo affidabile l'intero ciclo di comunicazione per la sua registrazione ufficiale.

La sezione successiva illustrerà l'architettura generale del sistema, evidenziando i componenti chiave che rendono possibile questo flusso operativo.

2.0 Architettura Generale del Sistema

Per apprezzare appieno la scalabilità e la modularità del processo di protocollazione, è essenziale comprendere l'architettura a microservizi su cui si fonda. L'adozione di questo approccio, basato su componenti disaccoppiati che comunicano tramite canali asincroni, è una scelta architetturale mirata a superare i limiti di scalabilità e manutenibilità intrinseci nei sistemi monolitici, offrendo flessibilità e resilienza superiori.

I principali componenti logici e infrastrutturali che costituiscono il sistema sono i seguenti:

• Applicazioni di Origine (es. Gestore Pratiche): Rappresentano la fonte degli eventi che innescano il processo di protocollazione. Un esempio tipico è l'acquisizione di una pratica inviata da un cittadino, che necessita di essere registrata ufficialmente.

• Document Dispatcher: È il microservizio responsabile di intercettare gli eventi applicativi (ad esempio, dal topic delle pratiche), estrarre le informazioni pertinenti e trasformarle in un oggetto "Documento" standardizzato. Questo oggetto viene poi pubblicato sul canale di comunicazione centrale.

• Topic Documents: Funge da snodo centrale di comunicazione asincrona, basato su tecnologia Kafka. Su questo topic vengono pubblicati tutti gli eventi relativi ai documenti, permettendo ai vari microservizi di interagire in modo disaccoppiato.

• Proxy di Protocollazione: Microservizio specializzato che rimane in ascolto sul Topic Documents. Il suo compito è consumare i messaggi relativi ai documenti che deve gestire, interfacciarsi con il sistema di gestione documentale esterno configurato ed eseguire l'effettiva protocollazione.

• Document Updater: Un altro microservizio che consuma messaggi dal Topic Documents. Il suo ruolo specifico è quello di intercettare gli eventi di protocollazione avvenuta con successo per aggiornare il sistema di origine (ad esempio, la pratica) con le informazioni di protocollo ricevute (numero e data).

• Topic Retry-Dispatcher-Queue: Un topic dedicato esclusivamente alla gestione dei fallimenti. Quando un tentativo di protocollazione fallisce, il messaggio viene inviato a questa coda per essere processato da un sistema di retry che schedulerà nuovi tentativi in modo controllato.

La descrizione di questi componenti è propedeutica all'analisi del flusso operativo dettagliato, che illustra come essi interagiscono per realizzare il processo di protocollazione end-to-end.

3.0 Flusso Operativo Dettagliato del Processo di Protocollazione

In questa sezione viene analizzato il flusso end-to-end del processo di protocollazione, scomponendolo nelle sue fasi sequenziali. Questo flusso è stato progettato per garantire massima tracciabilità e resilienza, dalla configurazione iniziale del servizio fino all'aggiornamento finale della pratica di origine.

Fase 1: Configurazione del Servizio

Il processo ha inizio con una fase di configurazione amministrativa. Un amministratore di sistema, tramite API REST dedicate, configura il tenant e il servizio specifico per l'ente. Queste configurazioni forniscono al Proxy di Protocollazione tutte le informazioni necessarie per comunicare con il sistema documentale esterno, tra cui l'URL del servizio, le credenziali di autenticazione e i parametri di classificazione come fascicolo, titolario, tipo di documento, ecc.

Fase 2: Generazione e Pubblicazione del Documento

Un evento applicativo, come l'acquisizione di una pratica, viene intercettato dal microservizio Document Dispatcher. Quest'ultimo trasforma i dati della pratica in un oggetto "Documento" standardizzato, arricchendolo con tutti i metadati necessari, e lo pubblica come evento sul Topic Documents.

Fase 3: Presa in Carico e Prima Elaborazione da parte del Proxy

Il Proxy di Protocollazione, costantemente in ascolto sul Topic Documents, consuma il messaggio. La prima azione è eseguire una validazione interna e verificare la presenza di una configurazione valida per il tenant e il servizio associati al documento. Se la verifica ha esito positivo, il proxy imposta lo stato del documento a REGISTRATION_PENDING ("in attesa di protocollazione") e ripubblica l'evento aggiornato sul topic. Questa scelta di design ("commit-and-reread") garantisce atomicità e tracciabilità, creando una transizione di stato registrata e persistente prima di avviare l'interazione con l'API esterna, che è potenzialmente lunga e fallibile.

Fase 4: Interazione con il Sistema Esterno

Consumando nuovamente il messaggio dal topic—questa volta con lo stato REGISTRATION_PENDING—il proxy avvia l'interazione con il sistema esterno, eseguendo i seguenti passaggi:

1. Download dei File: Scarica il file principale (es. il PDF della pratica compilata) e tutti gli eventuali allegati associati, i cui riferimenti sono contenuti nell'oggetto "Documento".

2. Autenticazione: Esegue il processo di autenticazione, tipicamente ottenendo un token di accesso a tempo (es. Bearer token) tramite una chiamata preliminare di login.

3. Invocazione: Invoca la funzione di protocollazione del sistema esterno (es. inserisci_protocollo), trasmettendo tutti i metadati richiesti (classifica, fascicolo, direzione, etc.) e i file scaricati.

Fase 5: Gestione dell'Esito

L'esito della comunicazione con il sistema esterno determina i passi successivi.

3.5.1 Scenario di Successo

Se il sistema esterno risponde positivamente, restituisce un identificativo univoco, tipicamente un numeroProtocollo e una data. Il proxy acquisisce queste informazioni, imposta lo stato del documento a REGISTRATION_COMPLETE e pubblica l'evento finale, arricchito con i dati di protocollazione, sul Topic Documents.

3.5.2 Scenario di Fallimento e Meccanismo di Retry

Se la comunicazione fallisce o il sistema esterno restituisce un errore, il proxy imposta lo stato del documento a REGISTRATION_FAILED o PARTIAL_REGISTRATION A questo punto, il messaggio di fallimento viene inviato al Topic retry-dispatcher-queue. Un sistema dedicato consumerà questo messaggio e schedulerà nuovi tentativi di invio secondo logiche temporali predefinite, garantendo che problemi transitori non causino la perdita della richiesta di protocollazione.

Fase 6: Aggiornamento del Sistema di Origine

Il microservizio Document Updater, anch'esso in ascolto sul Topic Documents, intercetta gli eventi il cui stato è REGISTRATION_COMPLETE. Legge le informazioni di protocollazione (numero e data) dall'evento e utilizza l'identificativo della pratica di origine (remote ID) per aggiornare il sistema sorgente, rendendo così visibili al cittadino e all'operatore i dati della registrazione avvenuta.

Il fulcro di questo intero processo è l'oggetto "Documento", la cui struttura dati e ciclo di vita meritano un'analisi dedicata nella sezione successiva.

4.0 Modello Dati e Ciclo di Vita del Documento

L'intero processo di protocollazione si fonda su un oggetto dati standardizzato, il "Documento", il cui stato evolve progressivamente attraverso le fasi del flusso. La standardizzazione di questo oggetto è un elemento architetturale cruciale. Il Document Dispatcher agisce come un anti-corruption layer, traducendo eventi specifici del dominio applicativo (es. l'acquisizione di una pratica) in questo modello dati canonico. Tale disaccoppiamento garantisce l'indipendenza dell'intero processo di protocollazione sia dalle applicazioni di origine che lo generano, sia dai molteplici sistemi di destinazione con cui deve interfacciarsi.

Struttura dell'Oggetto "Documento"

L'oggetto "Documento" aggrega tutte le informazioni necessarie per la sua corretta gestione e protocollazione. I suoi attributi chiave includono:

• Metadati: Un insieme di informazioni descrittive come Titolo, Classifica, dati sul Fascicolo (anno e numero), Tipo di documento e Direzione (in entrata, se generato dal cittadino; in uscita, se generato dall'operatore).

• Contenuti: Link sicuri per il download del File principale (tipicamente il PDF generato dalla pratica) e degli attachments, ovvero gli allegati caricati dall'utente durante la compilazione.

• Riferimenti: Un remote ID che stabilisce il collegamento univoco tra l'oggetto "Documento" e l'entità di origine che lo ha generato (es. l'ID della pratica).

• Autore: Informazioni sull'entità che ha generato il documento, distinguendo tra cittadino e operatore dell'ente.

• Stato: Un campo fondamentale che traccia l'avanzamento del documento all'interno del ciclo di vita della protocollazione.

Ciclo di Vita e Stati

Il campo Stato assume valori specifici che descrivono la fase corrente del processo. I tre stati principali del ciclo di vita della protocollazione sono illustrati nella tabella seguente.

Stato	Descrizione
REGISTRATION_PENDING	Stato iniziale assegnato dal proxy dopo la prima validazione, prima di tentare l'invio al sistema esterno. Significa "in attesa di protocollazione".
REGISTRATION_COMPLETE	Stato finale in caso di successo. Indica che il sistema esterno ha accettato il documento, lo ha registrato e ha restituito un numero di protocollo.
REGISTRATION_FAILED	Stato assegnato in caso di errore durante la comunicazione con il sistema esterno. Questo stato innesca il meccanismo di retry per tentare nuovamente la protocollazione.
PARTIAL_REGISTRATION	Stato assegnato in caso di errore durante la comunicazione con il sistema esterno. Si verifica quando il processo di protocollazione prevede più chiamate API verso il sistema di gestione documentale (es. creazione fascicolo, caricamento allegati, protocollazione) Questo stato innesca il meccanismo di retry per tentare nuovamente la protocollazione.

L'adozione di questo modello dati e di questo flusso operativo strutturato porta a significativi vantaggi architetturali, che verranno analizzati nella sezione conclusiva.

5.0 Conclusioni e Vantaggi Architetturali

La relazione ha descritto un flusso di protocollazione documentale basato su un'architettura a microservizi disaccoppiata, orchestrata tramite un sistema di messaggistica asincrona. Questa scelta progettuale non solo risolve un'esigenza funzionale complessa, ma introduce vantaggi strategici che garantiscono la robustezza e la manutenibilità della soluzione nel lungo periodo.

I benefici chiave derivanti dall'architettura presentata possono essere sintetizzati come segue:

• Scalabilità e Modularità: Il disaccoppiamento risolve direttamente il problema di scalabilità dell'architettura monolitica precedente, che rendeva lento e complesso l'onboarding di nuovi clienti con sistemi documentali diversi. Con questo approccio, ogni microservizio scala in modo indipendente e l'aggiunta di nuove integrazioni richiede solo lo sviluppo di un nuovo proxy, senza impattare il nucleo della piattaforma.

• Evoluzione Parallela: La separazione concettuale del "mondo dei documenti" crea un "treno parallelo di evoluzione". Ciò significa che il team dedicato al dominio documentale può migliorare le funzionalità (es. supportare nuovi metadati, ottimizzare la logica di retry) senza richiedere cicli di sviluppo coordinati o redeployment da parte dei team che gestiscono le applicazioni di origine (es. le pratiche), aumentando così la velocità di sviluppo e riducendo le dipendenze tra team.

• Indipendenza e Riusabilità: Il sistema è progettato per essere agnostico rispetto a chi lo invoca. Grazie all'oggetto "Documento" standard, può servire non solo le pratiche, ma qualsiasi altra entità della piattaforma che necessiti di protocollare un atto amministrativo, massimizzando il riuso del codice e delle logiche implementate.

• Resilienza: Il meccanismo di retry integrato garantisce che fallimenti temporanei del sistema esterno o problemi di rete non causino la perdita di richieste di protocollazione. Il sistema è in grado di ritentare l'operazione in modo automatico e controllato, assicurando che ogni documento venga alla fine processato correttamente.

In conclusione, l'architettura presentata non si limita a soddisfare l'esigenza funzionale della protocollazione, ma lo fa in un modo robusto, scalabile e manutenibile. Questo approccio posiziona il "mondo dei documenti" come un asset strategico e indipendente all'interno dell'ecosistema della piattaforma, pronto a supportarne l'evoluzione futura.