02 — Architettura e flussi dati¶
Schema generale¶
── FLUSSI A/B/C — Gestione prenotazioni ─────────────────────────────
CUP (HL7 OMG^O19)
└─► MIRTH (integration engine)
├──► MEDWARE (scrive in tabella prenotazioni)
└──► gt4medServices
└─► T4MED (FHIR R4)
POST {base-url} (Flusso A — Bundle transaction)
PUT {base-url}/Appointment/{id} (Flusso B)
DELETE {base-url}/Appointment/{id} (Flusso C)
── FLUSSO D — Firma referto post-visita ─────────────────────────────
MEDWARE [medico clicca pulsante "firma"]
└─► gefidServices
│ chiede il referto T4MED
└─► gt4medServices ──► T4MED (scarica PDF monitoraggio, DateFrom+DateTo+T4MedAppointmentId)
│
└─► MEDWARE (scarica referto clinico visita)
└─► merge PDF (T4MED accodato al referto MEDWARE)
[se T4MED risponde 204 No Content o errore: nessun merge, solo referto MEDWARE — si firma comunque]
│
└─► gefidServices (riceve PDF unito, lo firma digitalmente SINED)
── FLUSSI E/F/G/H — Pubblicazione e upload su T4MED ───────────────────
grepoServices [schedulato ogni ~10 minuti]
├──► REPO ──► FSE (pubblica referti firmati pendenti / sostitutivi / annullamenti)
│
└─► gt4medServices (per ogni referto pubblicato su REPO/FSE, o su richiesta di aggiornamento metadati)
└─► T4MED
POST {base-url} (Flusso E — Bundle transaction, prima pubblicazione v1)
POST {base-url} (Flusso F — Bundle transaction, sostitutivo v>1)
PUT {base-url}/DocumentReference/{id} (Flusso G — annullamento)
PUT {base-url}/DocumentReference/{id} (Flusso H — aggiornamento dei soli metadati)
Flusso A — Nuova prenotazione televisita¶
Trigger: CUP invia HL7 OMG^O19 (inserimento) al canale MIRTH.
CUP
│ HL7 OMG^O19 (ins. prenotazione 26B001956)
▼
MIRTH
├──► MEDWARE (scrive prenotazione in tabella prenotazioni)
│
│ chiama gt4medServices
▼
gt4medServices
│ POST {base-url}
│ Bundle transaction {Patient + ServiceRequest + Appointment}
├──► T4MED ──► 200 OK (Bundle transaction-response, Appointment/T00450/_history/1)
│
└──► Salva mappatura: 26B001956 → T00450
Importante: gt4medServices deve persistere la mappatura CUP Appointment ID → T4MED Appointment ID per i Flussi B e C.
Flusso B — Variazione prenotazione¶
Trigger: CUP invia HL7 OMG^O19 (variazione) al canale MIRTH.
CUP
│ HL7 OMG^O19 (var. prenotazione 26B001956)
▼
MIRTH
├──► MEDWARE (aggiorna prenotazione in tabella prenotazioni)
│
│ chiama gt4medServices
▼
gt4medServices
│ Legge mappatura: 26B001956 → T00450
│ PUT {base-url}/Appointment/T00450
└──► T4MED ──► 200 OK
Flusso C — Cancellazione prenotazione¶
Trigger: CUP invia HL7 OMG^O19 (cancellazione) al canale MIRTH.
CUP
│ HL7 OMG^O19 (canc. prenotazione 26B001956)
▼
MIRTH
├──► MEDWARE (cancella prenotazione in tabella prenotazioni)
│
│ chiama gt4medServices
▼
gt4medServices
│ Legge mappatura: 26B001956 → T00450
│ DELETE {base-url}/Appointment/T00450
├──► T4MED ──► 200 OK / 204 No Content
│
└──► Invalida mappatura: 26B001956 → T00450
Il Flusso C prevede esclusivamente la cancellazione fisica tramite
DELETE. Non è prevista alcuna modalità alternativa di cancellazione logica.
Flusso D — Firma referto post-visita (gefidServices)¶
Trigger: il medico visualizza il referto della televisita in MEDWARE e clicca il pulsante "firma" (icona penna in alto a destra). Questo innesca gefidServices.
Ruolo di gefidServices: middleware di firma digitale SINED già in esercizio. Quando attivato dal pulsante "firma" di MEDWARE, coordina il recupero e la firma del referto completo.
MEDWARE [clic pulsante "firma"]
└─► gefidServices
│ Richiesta referto T4MED (CF: RSVDMN11A41H620X, data: 2026-06-03, Appointment: T00450)
▼
gt4medServices
│ POST {base-url}/Patient/RSVDMN11A41H620X/$generate-pdf
│ Parameters: DateFrom, DateTo, T4MedAppointmentId (tutti obbligatori)
├──► T4MED ──► 200 OK (stream PDF monitoraggio)
│ ──► 204 No Content (nessun dato di telemonitoraggio nel periodo)
│ ──► 4xx/5xx (errore — es. Appointment inesistente o di altro paziente)
│
│ Download referto clinico
├──► MEDWARE ──► stream PDF referto visita
│
│ Merge PDF (T4MED accodato al referto MEDWARE) — solo se T4MED ha risposto 200 OK
│ Se 204 No Content o errore 4xx/5xx: nessun merge, si procede con il solo referto MEDWARE
└──► gefidServices (riceve PDF — unito o solo MEDWARE)
│
└──► Firma digitale SINED (PDF firmato comunque, con o senza allegato T4MED)
Parametro T4MedAppointmentId: identifica la specifica prenotazione T4MED (Flusso A) e limita il telemonitoraggio restituito a quella prenotazione, evitando di includere dati di monitoraggio di altre televisite dello stesso paziente nello stesso intervallo di date. Errori possibili: Appointment inesistente (404), Appointment associato ad altro paziente (422). Come per il caso 204 No Content, anche in questi scenari di errore il referto viene comunque firmato digitalmente, con il solo contenuto MEDWARE (senza l'allegato T4MED). Vedi samples/flusso-d-download-referto.md.
Flussi E/F/G/H — Pubblicazione e upload su T4MED (grepoServices)¶
Trigger: grepoServices è un servizio schedulato (tipicamente ogni ~10 minuti). Non viene innescato direttamente da gefidServices. Ad ogni esecuzione, grepoServices raccoglie i referti firmati pendenti (nuove pubblicazioni, sostitutivi, annullamenti, aggiornamenti di metadati), li pubblica/aggiorna su REPO/FSE e, per ognuno, chiama gt4medServices per l'operazione corrispondente su T4MED.
gefidServices
│ PDF firmato (nuovo / sostitutivo) oppure richiesta di annullamento / aggiornamento metadati
▼
grepoServices
│ Upload / annullamento / aggiornamento documento
├──► REPO ──► Pubblicato / annullato / aggiornato su REPO
│ └──► FSE ──► Pubblicato / annullato / aggiornato su FSE
│
│ (solo dopo OK da REPO/FSE)
│ Richiesta operazione su T4MED
▼
gt4medServices
│ Flusso E — prima pubblicazione (v1):
│ POST {base-url} — Bundle transaction {Binary + DocumentReference}
│ Flusso F — referto sostitutivo (v>1):
│ POST {base-url} — Bundle transaction {Binary + DocumentReference (relatesTo=replaces)}
│ Flusso G — annullamento:
│ PUT {base-url}/DocumentReference/{id} — status=entered-in-error
│ Flusso H — aggiornamento dei soli metadati:
│ PUT {base-url}/DocumentReference/{id} — status=current, stesso PDF/versione
└──► T4MED ──► 200 OK
└──► gt4medServices ──► grepoServices (operazione T4MED completata)
Vedi il dettaglio dei quattro flussi in samples/flusso-e-upload-referto-firmato.md, samples/flusso-f-referto-sostitutivo.md, samples/flusso-g-annullamento-referto.md e samples/flusso-h-aggiornamento-metadati.md.
Tabella di mappatura interna (obbligatoria)¶
gt4medServices deve persistere su DB interno le seguenti mappature:
| Chiave | Valore | Usata nei flussi |
|---|---|---|
CUP Appointment ID (es. 26B001956) |
T4MED Appointment ID (es. T00450) |
B, C |
Decisioni architetturali aperte¶
- Parser HL7 v2 per i messaggi OMG^O19 del CUP
- Modalità di integrazione con MEDWARE (API proprietaria / DB / interfaccia HL7 — non ancora documentata)
- Libreria per il merge dei PDF
- Interfaccia esposta da gt4medServices verso gefidServices (Flusso D)
- Interfaccia esposta da gt4medServices verso grepoServices (Flussi E/F/G/H)
- Ambiente di deployment e gestione della configurazione (API Key T4MED, ecc.)