11 — Dettaglio: Monitoraggio¶

Approfondimento del capitolo 10 — Monitoraggio e Riconciliazione.

Obiettivo¶

Il monitoraggio deve consentire a T4MED di verificare:

il numero di prenotazioni di televisita ricevute da SINED;
il numero di televisite effettivamente eseguite dal reparto;
il numero di referti prodotti e firmati;
il numero di referti correttamente spediti al repository aziendale;
il numero di referti correttamente spediti a T4MED;
eventuali anomalie o perdite di sincronizzazione.

È realizzato tramite due flussi distinti, inviati entrambi da gt4medServices a T4MED ogni giorno alle 06:00:

Report Sintetico, in formato FHIR MeasureReport;
Report Analitico, in formato FHIR Parameters (o, in alternativa, Bundle di risorse Task).

Report Sintetico (MeasureReport)¶

Finalità¶

Fornisce una vista aggregata dell'intero periodo di attività. Serve a:

verificare che il flusso di monitoraggio sia attivo;
rilevare eventuali problemi di connettività;
confrontare i volumi gestiti dai due sistemi;
individuare rapidamente eventuali anomalie.

Frequenza e periodo monitorato¶

Ogni giorno alle 06:00. Il periodo coperto va sempre dalla data di avvio dell'integrazione fino alla mezzanotte del giorno precedente alla generazione.

Esempio: con avvio integrazione il 01/10/2026 e generazione il 15/03/2027 alle 06:00, il periodo è >= 2026-10-01T00:00:00 e < 2027-03-15T00:00:00 (fino al 14/03/2027 24:00:00).

Assenza del report¶

L'assenza del report è di per sé un'anomalia: indica un possibile problema di connettività, autenticazione o disponibilità (dei servizi mittenti o riceventi).

Esempio¶

Ogni indicatore porta un codice stabile (coding) oltre al testo descrittivo (text): il confronto fra i due sistemi va sempre fatto sul coding, mai sul text — un errore di battitura nel testo non comprometterebbe il riconoscimento del dato.

{
  "resourceType": "MeasureReport",
  "status": "complete",
  "type": "summary",
  "period": {
    "start": "2026-10-01T00:00:00+02:00",
    "end": "2027-03-15T00:00:00+01:00"
  },
  "group": [
    {
      "code": {
        "coding": [{ "system": "urn:t4med:monitoring:measure-group", "code": "televisite" }],
        "text": "Televisite"
      },
      "population": [
        {
          "code": {
            "coding": [{ "system": "urn:t4med:monitoring:population", "code": "appointments-received" }],
            "text": "Prenotazioni CUP televisita ricevute"
          },
          "count": 1500
        },
        {
          "code": {
            "coding": [{ "system": "urn:t4med:monitoring:population", "code": "visits-performed" }],
            "text": "Televisite eseguite"
          },
          "count": 1420
        }
      ]
    },
    {
      "code": {
        "coding": [{ "system": "urn:t4med:monitoring:measure-group", "code": "refertazione" }],
        "text": "Refertazione"
      },
      "population": [
        {
          "code": {
            "coding": [{ "system": "urn:t4med:monitoring:population", "code": "reports-signed" }],
            "text": "Referti firmati"
          },
          "count": 1390
        }
      ]
    },
    {
      "code": {
        "coding": [{ "system": "urn:t4med:monitoring:measure-group", "code": "repository" }],
        "text": "Repository"
      },
      "population": [
        {
          "code": {
            "coding": [{ "system": "urn:t4med:monitoring:population", "code": "repository-success" }],
            "text": "Referti spediti con successo"
          },
          "count": 1385
        },
        {
          "code": {
            "coding": [{ "system": "urn:t4med:monitoring:population", "code": "repository-failure" }],
            "text": "Referti spediti con failure"
          },
          "count": 5
        }
      ]
    },
    {
      "code": {
        "coding": [{ "system": "urn:t4med:monitoring:measure-group", "code": "t4med" }],
        "text": "T4MED"
      },
      "population": [
        {
          "code": {
            "coding": [{ "system": "urn:t4med:monitoring:population", "code": "t4med-success" }],
            "text": "Referti spediti con successo"
          },
          "count": 1382
        },
        {
          "code": {
            "coding": [{ "system": "urn:t4med:monitoring:population", "code": "t4med-failure" }],
            "text": "Referti spediti con failure"
          },
          "count": 3
        }
      ]
    }
  ]
}

Stesso contenuto in forma tabellare:

Periodo: dal 01/10/2026 00:00 al 15/03/2027 00:00 (ora locale italiana)

Gruppo	Codice gruppo	Indicatore	Codice	Conteggio
Televisite	`televisite`	Prenotazioni CUP televisita ricevute	`appointments-received`	1500
Televisite	`televisite`	Televisite eseguite	`visits-performed`	1420
Refertazione	`refertazione`	Referti firmati	`reports-signed`	1390
Repository	`repository`	Referti spediti con successo	`repository-success`	1385
Repository	`repository`	Referti spediti con failure	`repository-failure`	5
T4MED	`t4med`	Referti spediti con successo	`t4med-success`	1382
T4MED	`t4med`	Referti spediti con failure	`t4med-failure`	3

Dizionario dei codici (CodeSystem, ipotesi di lavoro)¶

Proposta di CodeSystem interno, non ancora registrata né confermata da T4MED.

System: urn:t4med:monitoring:measure-group (in MeasureReport.group.code.coding)

Codice	Significato
`televisite`	Indicatori relativi alle televisite (prenotazioni ricevute e visite eseguite)
`refertazione`	Indicatori relativi alla produzione e firma dei referti
`repository`	Indicatori relativi alla spedizione dei referti al repository documentale aziendale
`t4med`	Indicatori relativi alla spedizione dei referti a T4MED

System: urn:t4med:monitoring:population (in MeasureReport.group.population.code.coding)

Codice	Significato
`appointments-received`	Numero di prenotazioni di televisita ricevute da SINED (tramite messaggio CUP)
`visits-performed`	Numero di televisite effettivamente eseguite dal reparto
`reports-signed`	Numero di referti prodotti e firmati
`repository-success`	Numero di referti spediti con successo al repository documentale
`repository-failure`	Numero di referti la cui spedizione al repository documentale è fallita
`t4med-success`	Numero di referti spediti con successo a T4MED
`t4med-failure`	Numero di referti la cui spedizione a T4MED è fallita

Report Analitico (Parameters o Bundle di Task)¶

Finalità¶

Contiene il dettaglio delle singole televisite. Consente a T4MED di riconciliare gli appuntamenti, verificare la presenza del referto, verificare l'esito della spedizione e individuare anomalie puntuali.

Frequenza e politica di sovrapposizione¶

Ogni giorno alle 06:00, con una finestra mobile di due settimane: ogni giorno viene reinviato il dettaglio delle ultime due settimane, per tollerare problemi temporanei di comunicazione (ogni record viene quindi trasmesso più volte e va trattato come idempotente).

Esempio: generazione il 15/03/2027 → periodo [2027-03-01, 2027-03-15); generazione il 16/03/2027 → periodo [2027-03-02, 2027-03-16).

Chiave logica¶

Ogni record è identificato dalla coppia appointmentId + documentId: appointmentId è il codice CUP della prenotazione (lo stesso spedito a T4MED nei Flussi A/B), documentId è l'identificativo assegnato dal Repository documentale (REPO) al referto pubblicato — non identificativi interni di SINED.

Esempio (formato Parameters)¶

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "periodStart", "valueDateTime": "2027-03-01T00:00:00+01:00" },
    { "name": "periodEnd", "valueDateTime": "2027-03-15T00:00:00+01:00" },
    { "name": "coveragePolicy", "valueCode": "LAST_14_DAYS" },
    {
      "name": "item",
      "part": [
        { "name": "appointmentId", "valueString": "26B001956" },
        { "name": "documentId", "valueString": "REPO-481205" },
        { "name": "visitOutcome", "valueCode": "performed" },
        { "name": "reportStatus", "valueCode": "signed" },
        { "name": "repositoryOutcome", "valueCode": "success" },
        { "name": "t4medOutcome", "valueCode": "success" }
      ]
    },
    {
      "name": "item",
      "part": [
        { "name": "appointmentId", "valueString": "26B001957" },
        { "name": "documentId", "valueString": "REPO-481206" },
        { "name": "visitOutcome", "valueCode": "performed" },
        { "name": "reportStatus", "valueCode": "signed" },
        { "name": "repositoryOutcome", "valueCode": "success" },
        { "name": "t4medOutcome", "valueCode": "failure" },
        { "name": "blockingReason", "valueString": "Errore durante la spedizione a T4MED" }
      ]
    }
  ]
}

Stesso contenuto in forma tabellare:

Periodo: dal 01/03/2027 00:00 al 15/03/2027 00:00 (ora locale italiana) — Coverage policy: LAST_14_DAYS

appointmentId	documentId	visitOutcome	reportStatus	repositoryOutcome	t4medOutcome	blockingReason
`26B001956`	`REPO-481205`	`performed`	`signed`	`success`	`success`	—
`26B001957`	`REPO-481206`	`performed`	`signed`	`success`	`failure`	Errore durante la spedizione a T4MED

Dizionario dei parametri¶

Nome	Tipo valore	Significato
`periodStart`	`valueDateTime`	Inizio del periodo coperto dal report
`periodEnd`	`valueDateTime`	Fine del periodo coperto dal report
`coveragePolicy`	`valueCode`	Politica di sovrapposizione applicata
`item`	(gruppo)	Un blocco `part` per ogni televisita riportata
`appointmentId`	`valueString`	Codice CUP della prenotazione (lo stesso spedito a T4MED nei Flussi A/B), non un id interno SINED — chiave logica
`documentId`	`valueString`	Identificativo del referto assegnato dal Repository documentale (REPO), non un id interno SINED — chiave logica. Presente solo quando `repositoryOutcome = success`: negli stadi precedenti della pipeline (referto non prodotto, non firmato, non ancora spedito a REPO) REPO non ha ancora assegnato un id, e il parametro va omesso — il record resta identificato dal solo `appointmentId`
`visitOutcome`	`valueCode`	Esito della televisita
`reportStatus`	`valueCode`	Stato del referto
`repositoryOutcome`	`valueCode`	Esito della spedizione al repository documentale
`t4medOutcome`	`valueCode`	Esito della spedizione a T4MED
`blockingReason`	`valueString`	Messaggio libero, presente solo in caso di esito negativo

Dizionario dei valori codificati¶

System: urn:t4med:monitoring:coverage-policy (in coveragePolicy.valueCode)

Codice	Significato
`LAST_14_DAYS`	Finestra mobile delle ultime due settimane (politica adottata)

Per visitOutcome, reportStatus, repositoryOutcome e t4medOutcome (vocabolario condiviso anche dal Bundle di Task):

Campo	Valori possibili
`visitOutcome`	`performed` \| `not-performed`
`reportStatus`	`not-produced` \| `pending` \| `signed`
`repositoryOutcome`	`not-sent` \| `success` \| `failure`
`t4medOutcome`	`not-sent` \| `success` \| `failure`

reportStatus, repositoryOutcome e t4medOutcome rappresentano stadi successivi di una stessa pipeline (visita eseguita → referto prodotto → referto firmato → spedito a REPO → spedito a T4MED). Il valore not-sent/not-produced indica che lo stadio non è ancora stato raggiunto, distinto da failure, che indica un tentativo effettivamente fallito. Uno stadio non ha senso compiuto se quello precedente non è completato: ad es. repositoryOutcome è significativo solo se reportStatus = signed, altrimenti resta not-sent.

Esempio: stadi della pipeline del referto¶

Lo stesso item del report analitico può rappresentare un referto in un punto qualsiasi della pipeline. Quattro esempi, uno per stadio (nessuno di questi ha ancora un documentId, tranne l'ultimo, perché REPO non ha ancora assegnato l'id):

{
  "name": "item",
  "part": [
    { "name": "appointmentId", "valueString": "26B001961" },
    { "name": "visitOutcome", "valueCode": "performed" },
    { "name": "reportStatus", "valueCode": "not-produced" },
    { "name": "repositoryOutcome", "valueCode": "not-sent" },
    { "name": "t4medOutcome", "valueCode": "not-sent" }
  ]
}

appointmentId	documentId	visitOutcome	reportStatus	repositoryOutcome	t4medOutcome	Scenario
`26B001961`	—	`performed`	`not-produced`	`not-sent`	`not-sent`	Referto non prodotto
`26B001962`	—	`performed`	`pending`	`not-sent`	`not-sent`	Prodotto, non firmato
`26B001963`	—	`performed`	`signed`	`not-sent`	`not-sent`	Firmato, non spedito a REPO
`26B001964`	`REPO-481210`	`performed`	`signed`	`success`	`not-sent`	Spedito a REPO, non a T4MED

Rappresentazione alternativa: Bundle di Task¶

Gli stessi record possono essere rappresentati come Bundle di risorse Task — una Task per ogni coppia appointmentId/documentId, con la chiave logica in Task.identifier. È più verboso di Parameters, ma usa una risorsa FHIR "vera", pensata per essere persistita e interrogata (a differenza di Parameters, pensata come involucro di input/output di un'operazione — vedi 12 — Dettaglio: Riconciliazione Manuale).

{
  "resourceType": "Bundle",
  "type": "collection",
  "timestamp": "2027-03-15T06:00:00+01:00",
  "entry": [
    {
      "resource": {
        "resourceType": "Task",
        "identifier": [
          { "system": "urn:local:cup:id-prenotazione", "value": "26B001956" },
          { "system": "urn:local:repo:document-id", "value": "REPO-481205" }
        ],
        "status": "completed",
        "businessStatus": {
          "coding": [{ "system": "urn:t4med:monitoring:task-business-status", "code": "sent-to-t4med" }],
          "text": "Inviato a T4MED"
        },
        "focus": { "identifier": { "system": "urn:local:cup:id-prenotazione", "value": "26B001956" } },
        "output": [
          { "type": { "coding": [{ "system": "urn:t4med:monitoring:task-output-type", "code": "visitOutcome" }], "text": "Esito della visita" }, "valueCode": "performed" },
          { "type": { "coding": [{ "system": "urn:t4med:monitoring:task-output-type", "code": "reportStatus" }], "text": "Stato del referto" }, "valueCode": "signed" },
          { "type": { "coding": [{ "system": "urn:t4med:monitoring:task-output-type", "code": "repositoryOutcome" }], "text": "Esito spedizione al repository" }, "valueCode": "success" },
          { "type": { "coding": [{ "system": "urn:t4med:monitoring:task-output-type", "code": "t4medOutcome" }], "text": "Esito spedizione a T4MED" }, "valueCode": "success" }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Task",
        "identifier": [
          { "system": "urn:local:cup:id-prenotazione", "value": "26B001957" },
          { "system": "urn:local:repo:document-id", "value": "REPO-481206" }
        ],
        "status": "failed",
        "businessStatus": {
          "coding": [{ "system": "urn:t4med:monitoring:task-business-status", "code": "permanently-failed" }],
          "text": "Fallito in modo permanente"
        },
        "focus": { "identifier": { "system": "urn:local:cup:id-prenotazione", "value": "26B001957" } },
        "output": [
          { "type": { "coding": [{ "system": "urn:t4med:monitoring:task-output-type", "code": "visitOutcome" }], "text": "Esito della visita" }, "valueCode": "performed" },
          { "type": { "coding": [{ "system": "urn:t4med:monitoring:task-output-type", "code": "reportStatus" }], "text": "Stato del referto" }, "valueCode": "signed" },
          { "type": { "coding": [{ "system": "urn:t4med:monitoring:task-output-type", "code": "repositoryOutcome" }], "text": "Esito spedizione al repository" }, "valueCode": "success" },
          { "type": { "coding": [{ "system": "urn:t4med:monitoring:task-output-type", "code": "t4medOutcome" }], "text": "Esito spedizione a T4MED" }, "valueCode": "failure" }
        ],
        "statusReason": { "text": "Errore durante la spedizione a T4MED" }
      }
    }
  ]
}

Stesso contenuto in forma tabellare:

Timestamp Bundle: 15/03/2027 06:00 (ora locale italiana)

appointmentId	documentId	status	businessStatus	visitOutcome	reportStatus	repositoryOutcome	t4medOutcome	statusReason
`26B001956`	`REPO-481205`	`completed`	`sent-to-t4med`	`performed`	`signed`	`success`	`success`	—
`26B001957`	`REPO-481206`	`failed`	`permanently-failed`	`performed`	`signed`	`success`	`failure`	Errore durante la spedizione a T4MED

Dizionario dei codici per il Task¶

Task.status (sottoinsieme rilevante del value set standard FHIR R4):

Codice	Significato
`requested`	Richiesta di invio accodata
`in-progress`	Invio in corso (es. tentativo/retry in atto)
`completed`	Invio concluso con successo
`failed`	Invio concluso con esito di fallimento

System: urn:t4med:monitoring:task-business-status (in Task.businessStatus.coding)

Codice	Significato
`queued`	In coda, non ancora inviato
`waiting-for-retry`	In attesa del prossimo tentativo dopo un errore
`sent-to-t4med`	Inviato con successo a T4MED
`sent-to-repository`	Inviato con successo al repository documentale
`notification-sent`	Notifica inviata
`notification-delivered`	Notifica consegnata
`permanently-failed`	Fallito in modo permanente dopo i retry previsti

System: urn:t4med:monitoring:task-output-type (in Task.output[].type.coding)

Codice	Significato
`visitOutcome`	Esito della televisita
`reportStatus`	Stato del referto
`repositoryOutcome`	Esito della spedizione al repository documentale
`t4medOutcome`	Esito della spedizione a T4MED

I valori (Task.output[].valueCode) condividono lo stesso vocabolario di Parameters (vedi tabella sopra).

Tutti i system, i codici e i formati di questo capitolo sono ipotesi di lavoro: vanno validati con T4MED/TESI prima dell'adozione.