Il modello di prodotto

Questa sezione descrive le entità e i concetti su cui è costruito GovCat. I capitoli successivi del manuale approfondiscono ciascuna di queste entità dal punto di vista operativo (creazione, gestione, workflow).

Entità principali

Entità	Cos'è
Organizzazione	L'ente giuridico/anagrafico (PA o fornitore). È il contenitore di soggetti e utenti. Porta i flag referente / aderente / intermediata che ne definiscono il ruolo nel catalogo (si veda Struttura e gestione delle organizzazioni).
Soggetto	L'attore applicativo così come è registrato su GovWay (ha nome gateway, tipo gateway, URL di invocazione). È l'oggetto che il gateway riconosce come erogatore/fruitore. Appartiene a un'organizzazione.
Dominio	Raggruppamento organizzativo e di governo dei servizi. Ha una visibilità (pubblico/privato/riservato/componente) e un soggetto referente.
Servizio	L'unità pubblicata a catalogo (nome + versione), di tipo API o GENERICO. Porta stato (workflow), visibilità, immagine, tag, categorie e allegati. Può essere un package che aggrega componenti.
API	La specifica tecnica dell'interfaccia (OpenAPI/Swagger/WSDL), con configurazioni distinte per collaudo e produzione. Un servizio di tipo API espone una o più API.
Adesione	La relazione di fruizione con cui un soggetto aderente richiede e ottiene l'uso di un servizio. Porta il proprio workflow di autorizzazione e la configurazione tecnica.
Client	L'applicativo client (con tipo di autenticazione, ambiente, indirizzo IP) di proprietà di un soggetto, utilizzato nelle adesioni.
Utente	La persona/account, con stato e ruolo globale di piattaforma. Si associa a una o più organizzazioni con un ruolo per-organizzazione (si veda Struttura dei ruoli).
Gruppo	Nodo gerarchico (ad albero) per organizzare i servizi a catalogo.
Categoria / Tassonomia	Voci gerarchiche di uno schema di classificazione applicabile ai servizi.
Classe utente	Insieme di utenti usato per la visibilità/autorizzazione riservata su domini e servizi.
Notifica / Messaggio	Comunicazioni legate a un servizio o a un'adesione (cambi di stato, comunicazioni libere), anche via email.
Allegato / Documento	Contenuti binari (immagini, specifiche, documentazione) collegati a servizi e API.

Relazioni tra le entità

        erDiagram
    ORGANIZZAZIONE ||--o{ SOGGETTO : "possiede"
    ORGANIZZAZIONE ||--o{ ASSOCIAZIONE : "associa"
    UTENTE         ||--o{ ASSOCIAZIONE : "ha ruolo org."
    SOGGETTO       ||--o{ DOMINIO : "referente di"
    DOMINIO        ||--o{ SERVIZIO : "contiene"
    SOGGETTO       ||--o{ SERVIZIO : "eroga"
    SERVIZIO       }o--o{ API : "espone"
    SERVIZIO       ||--o{ ADESIONE : "riceve"
    SOGGETTO       ||--o{ ADESIONE : "aderisce con"
    ADESIONE       ||--o{ USO_CLIENT : "usa"
    CLIENT         ||--o{ USO_CLIENT : ""
    SOGGETTO       ||--o{ CLIENT : "possiede"
    GRUPPO         }o--o{ SERVIZIO : "cataloga"
    CATEGORIA      }o--o{ SERVIZIO : "classifica"

Organizzazione -> Soggetto (1:N), un'organizzazione possiede uno o più soggetti GovWay, con un soggetto di default.
Soggetto -> Dominio (1:N), il referente di un dominio è un soggetto. I referenti persona del dominio sono invece utenti (con distinzione referente / referente tecnico).
Dominio -> Servizio (1:N), un dominio contiene i servizi che ne condividono governance e visibilità.
Servizio <-> API (N:M), un servizio di tipo API espone una o più specifiche tecniche.
Servizio -> Adesione (1:N), un servizio riceve adesioni (il servizio decide se sono ammesse e se multiple).
Adesione -> Client (1:N tramite associazione), un'adesione usa uno o più client, ciascuno legato a un ambiente e a un profilo; un client può partecipare a più adesioni.
Utente <-> Organizzazione (N:M con ruolo), l'associazione porta il ruolo per-organizzazione (amministratore organizzazione / operatore API).
Gruppo/Categoria <-> Servizio (N:M), schemi gerarchici di catalogazione e classificazione.

Concetti trasversali: ambienti, stati, visibilità

Ambienti: Tutto il ciclo tecnico distingue Collaudo e Produzione. Le API hanno configurazioni separate per ambiente, i client e le adesioni sono per ambiente, e un flag skip collaudo consente di saltare la fase di test dove previsto.
Stati e workflow: Lo stato di Servizio e Adesione è una macchina a stati pilotata da configurazione esterna (non un enum cablato nel codice). Gli stati e le transizioni sono definiti in configurazione, e la cronologia dei cambi (stato, data, utente, commento) è tracciata a parte. L'adesione ha inoltre uno stato di configurazione tecnica distinto dal workflow funzionale (esito della propagazione verso GovWay: OK / KO / in coda / retry / fallita).
Visibilità: Domini e servizi condividono i livelli Pubblico, Privato, Riservato, Componente. La visibilità riservata si combina con le classi utente per limitare l'accesso.
Notifiche: I cambi di stato e le comunicazioni generano notifiche verso gli utenti coinvolti (in-app ed email), con mittente/destinatario.