Procedura Sync Aziende — Database di Lavoro (Ambiente)

Guida operativa alla gestione multi-workspace: selezione, attivazione, riserve SuperAdmin e sincronizzazione dati fra ambienti.

Indice

Architettura multi-workspace
Selezione dell'ambiente attivo
Ambienti accessibili dall'utente
Riserve SuperAdmin
Sincronizzazione fra ambienti
Cosa viene sincronizzato
Motivazioni operative, legali, fiscali e privacy

1. Architettura multi-workspace

NOX gestisce più aziende contemporaneamente tramite un modello database-per-workspace: ogni workspace (azienda, studio, ramo operativo) possiede un proprio database PostgreSQL fisicamente separato. Il database principale mantiene unicamente l'anagrafica utenti, i permessi e l'elenco dei workspace con i relativi parametri di collegamento.

Isolamento dei dati

Ogni azienda ha i propri documenti, soggetti, catalogo, scadenzario, SDI, parametri. Non esiste mescolamento implicito: ciò che è sincronizzato viene copiato esplicitamente.

Ruoli coinvolti

Ruolo	Capacità
SUPERADMIN	Crea/elimina workspace, configura riserve, definisce i target di sincronizzazione, accede a workspace riservati.
ADMIN	Assegna workspace agli utenti (esclusi quelli riservati), modifica dati all'interno dei workspace accessibili.
UTENTE	Lavora negli ambienti assegnati dall'amministratore, senza accesso alla configurazione multi-workspace.

2. Selezione dell'ambiente attivo

Il campo "Ambiente attualmente in uso" definisce su quale database l'utente sta lavorando in questa sessione. Il cambio di ambiente avviene tramite il menu a tendina in alto e si riflette immediatamente su tutte le sezioni (Documenti, Soggetti, Catalogo, SDI, Scadenzario, ...).

TopBar → switch workspace │ ▼ GET /api/auth/switch-workspace/:id │ ▼ Backend aggiorna JWT.workspaceId │ ▼ Middleware apre la PrismaClient del workspace scelto │ ▼ Tutte le API successive colpiscono quel database

Attenzione

Il cambio di ambiente non sposta dati. Sposta il contesto di lavoro: quello che si vede, si legge e si salva proviene dal database dell'ambiente attivo.

3. Ambienti accessibili dall'utente

La lista "Ambienti accessibili dall'utente" definisce quali database compaiono nel menu di switch della TopBar per lo specifico utente selezionato. Ogni riga mostra:

Checkbox — attiva/disattiva l'assegnazione del workspace all'utente;
Icona — folder_open (standard), visibility_off (nascosto), lock (riservato SuperAdmin e bloccato per Admin);
Nome workspace — etichetta dell'ambiente;
Scudo (solo SuperAdmin) — shield pieno = riservato; shield_outlined = pubblico;
🔗 Sync target (solo SuperAdmin) — workspace verso cui questo ambiente propaga i dati.

Flusso di assegnazione

1. SuperAdmin o Admin seleziona un utente dal menu "Seleziona utente" 2. Il sistema carica l'elenco workspace e i workspace già assegnati 3. L'amministratore spunta/toglie i workspace che l'utente può vedere 4. Salvando, viene eseguito PUT /api/utenti/:id/workspaces con l'elenco degli ID 5. Alla successiva login l'utente trova i workspace assegnati nella TopBar

Principio di minimo privilegio

L'utente non deve vedere aziende che non lo riguardano: ogni ambiente assegnato apre l'accesso completo al relativo database, quindi le spunte vanno messe solo dove serve.

4. Riserve SuperAdmin

Un workspace può essere marcato come riservato al SuperAdmin tramite l'icona a scudo. Quando la riserva è attiva:

Il workspace non compare nel menu di switch degli utenti non-SuperAdmin;
Gli Admin non possono spuntare il workspace nella lista "Ambienti accessibili" (checkbox in stato lock);
Solo il SuperAdmin può rimuovere la riserva oppure assegnare l'ambiente ad altri utenti;
Nell'elenco workspace mostrato al SuperAdmin è visibile con l'icona shield piena.

Casi d'uso tipici delle riserve

Scenario	Motivo della riserva
Workspace di test, collaudo, staging	Evita che operatori scrivano per errore in ambienti non fiscali.
Ambiente di un'azienda dismessa o in liquidazione	Conservazione dei dati senza esposizione operativa.
Copie di backup consultabili	Garantisce integrità: solo lettura sorvegliata.
Workspace con dati particolarmente sensibili	Limita la platea di chi può accedere ai dati personali o sanitari.

5. Sincronizzazione fra ambienti

Accanto ad ogni workspace, il SuperAdmin può impostare un sync target (icona 🔗): quando un documento/fattura viene emesso in quel workspace, una copia viene automaticamente scritta nel workspace target.

Configurazione

Nella riga del workspace sorgente, il SuperAdmin clicca l'etichetta 🔗;
Appare un select con l'elenco dei possibili target (sé stesso escluso);
Alla selezione viene inviata PATCH /api/workspaces/:id/sync-target con syncTargetWorkspaceId;
Il backend aggiorna il record Workspace.syncTargetWorkspaceId sul database principale;
Selezionando "Nessun sync" la sincronizzazione viene disattivata.

Documento emesso su workspace A │ ├─► syncTargetWorkspaceId letto da GET /api/workspaces/sync-info │ ├─► POST /api/documenti/:id/sync-to-workspace { targetWorkspaceId: B } │ └─► Backend apre PrismaClient del workspace B e crea copia completa

Sincronizzazione a senso unico

Il sync è unidirezionale A → B. Se serve la replica anche in senso inverso, va configurato un secondo sync target su B.

6. Cosa viene sincronizzato

Entità	Quando	Campi copiati
Documenti (fatture, ricevute, note)	Alla creazione/emissione con stato non BOZZA	Tipo, numero, serie, data, stato, soggetto (creato se mancante), righe complete, imponibile/IVA/lordo, valuta, cassa previdenza, bollo, causale.
Soggetti (clienti/fornitori)	Quando referenziati da un documento sincronizzato	Match per `codice` o `codiceFiscale`; se non presenti, il soggetto viene creato sul target con i dati anagrafici e fiscali.
Fatture SDI	Ad ogni cambio stato (IN_ATTESA, CONSEGNATA, SCARTATA, ACCETTATA, ...)	Stato, nome file XML, progressivo invio, IdSdI, messaggio errore, data invio, tipo/formato trasmissione, codice destinatario.
Catalogo (articoli/prestazioni)	Su richiesta esplicita (pulsante sincronizza)	Codice, descrizione, unità di misura, prezzo, aliquota IVA, natura IVA, conto di ricavo.

Controllo duplicati

Il backend verifica la presenza del documento sul target tramite numero + anno + tipoDocumento. Se esiste già, la sincronizzazione risponde skipped: true senza creare duplicati.

Cosa NON viene sincronizzato

Bozze (stato = BOZZA): restano locali al workspace di origine;
Utenti, ruoli, permessi: gestiti solo sul database principale;
Parametri aziendali (P.IVA, regime fiscale, sdiConfig): ogni workspace ha i propri;
Scadenzario, incassi, pagamenti: restano sul workspace dove sono stati registrati;
File allegati fisici: copiati solo se presenti nello storage condiviso.

7. Motivazioni operative, legali, fiscali e privacy

Operative

Visione consolidata — Uno studio che emette fatture su più ragioni sociali può concentrare le copie su un workspace di consultazione unico.
Continuità — La presenza della copia sul workspace target riduce il rischio di perdita dati in caso di downtime di uno specifico database.
Separazione produzione/test — Gli ambienti di prova restano isolati ma le configurazioni rilevanti possono essere propagate manualmente.

Legali e fiscali

Conservazione documenti fiscali

L'art. 39 del DPR 633/72 richiede la conservazione delle fatture emesse per almeno 10 anni. La sincronizzazione consente di mantenere una copia integrale nel workspace destinato alla conservazione, in aggiunta al backup periodico (art. 2220 c.c.).

Tracciabilità SDI — Il Provvedimento Agenzia delle Entrate del 30/04/2018 impone di poter ricostruire lo stato trasmissivo di ogni fattura elettronica: la sync dello stato SDI garantisce uniformità fra ambiente operativo e ambiente di consultazione.
Separazione societaria — Gruppi con più ragioni sociali mantengono contabilità autonome per ciascun soggetto passivo IVA (art. 21 DPR 633/72); la struttura per-workspace riflette questo obbligo.
Legge 4/2013 — Il profilo naturopata (non sanitario) richiede di evitare la confusione con prestazioni sanitarie esenti ex art. 10 DPR 633/72: tenere i workspace separati previene errori di classificazione IVA.

Privacy — GDPR (Reg. UE 2016/679)

Minimizzazione e limitazione della finalità

L'art. 5 GDPR impone che i dati personali siano trattati solo per finalità determinate e nei limiti strettamente necessari. L'architettura multi-workspace e la lista "Ambienti accessibili" sono lo strumento tecnico con cui NOX applica questo principio.

Accesso su base del bisogno — Assegnare solo i workspace necessari riduce la superficie di trattamento dei dati personali da parte del singolo operatore;
Titolari autonomi — Se due workspace appartengono a titolari del trattamento distinti, la separazione fisica del database riduce il rischio di comunicazione non autorizzata (art. 4 nn. 7 e 9 GDPR);
Riserve SuperAdmin — Ambienti contenenti dati sanitari o categorie particolari (art. 9 GDPR) restano accessibili solo al personale autorizzato con privilegio massimo;
Tracciabilità della sincronizzazione — La configurazione syncTargetWorkspaceId deve essere censita come trattamento di comunicazione dati fra database e documentata nel registro delle attività (art. 30 GDPR);
Cancellazione — Eliminando un workspace, i dati personali vengono rimossi dal relativo database; resta responsabilità dell'amministratore valutare la rimozione dei dati anche sul workspace target (art. 17 GDPR).

Best practice operative

Prima di attivare una sync, verificare che titolare del trattamento e basi giuridiche siano coerenti fra workspace sorgente e target;
Registrare nel registro dei trattamenti la finalità della copia fra ambienti;
Mantenere il principio di minimo privilegio: un Admin non deve avere accesso ad ambienti che non gestisce;
Marcare come riservati SuperAdmin i workspace di test, dismessi o contenenti dati particolarmente sensibili;
Documentare nel manuale aziendale quali workspace sono sincronizzati e con quale direzione.

Riferimenti normativi: DPR 633/72 (artt. 21, 39) · Cod. Civ. art. 2220 · Provv. Ag. Entrate 30/04/2018 · Legge 4/2013 · Regolamento UE 2016/679 (artt. 4, 5, 9, 17, 30, 32).