Catalogo Prodotti / Servizi

Il modulo Catalogo Prodotti/Servizi rappresenta l'archivio unificato di tutte le voci che possono essere inserite nei documenti commerciali e clinici di NOX Enterprise Suite. Ogni voce viene classificata in uno degli 8 tipi previsti e puo contenere informazioni specifiche in base alla propria natura (farmaco, articolo, prestazione, ecc.).

L'approccio a catalogo unico consente di gestire in un solo punto prezzi, aliquote IVA, codici, descrizioni e regole di magazzino, evitando duplicazioni e garantendo coerenza in tutti i flussi: fatturazione, ordini, DDT, ricette e prestazioni cliniche.

Il catalogo prevede 8 tipi di voce. Il tipo determina le sezioni disponibili nella scheda e il comportamento in fase di inserimento nei documenti.

Per creare una nuova voce di catalogo, seguire la procedura:

1. Accedere al menu Anagrafiche → Catalogo Prodotti/Servizi e premere il pulsante + Nuova Voce.
2. Selezionare il tipo di voce tra gli 8 disponibili (FARMACO, ARTICOLO, PRESTAZIONE, KIT, PARCELLA, SPESE, BOLLO, TESTO_LIBERO).
3. Compilare la tab Dati base: codice, descrizione, unita di misura, prezzo di vendita, aliquota IVA, eventuale sconto predefinito.
4. Compilare la tab Dettaglio (visibile per FARMACO, ARTICOLO, PRESTAZIONE) con i campi specifici del tipo selezionato (v. sezione 4).
5. Se il tipo prevede gestione magazzino (FARMACO, ARTICOLO), compilare la tab Magazzino con giacenza iniziale, scorta minima, lotto e scadenza (v. sezione 5).
6. Se il tipo e KIT, compilare la tab Kit con la distinta base dei componenti (v. sezione 6).
7. Premere Salva per confermare la registrazione nel catalogo.

Tab Dati base — campi principali

La tab Dettaglio presenta campi specifici in base al tipo di voce selezionato.

Dettaglio FARMACO

Dettaglio ARTICOLO

Dettaglio PRESTAZIONE

Disponibile per le voci di tipo FARMACO e ARTICOLO. Gestisce giacenze, scorte e tracciabilita dei lotti.

Una voce di tipo KIT e composta da una distinta base di componenti. Ogni componente e a sua volta una voce di catalogo (FARMACO, ARTICOLO, PRESTAZIONE, ecc.) con quantita, prezzo unitario, aliquota IVA e sconto specifici.

Creazione della distinta base

1. Aprire la scheda della voce KIT e selezionare la tab Kit.
2. Premere Aggiungi componente per inserire una nuova riga nella distinta base.
3. Utilizzare il pulsante Sfoglia catalogo per aprire l'overlay di ricerca: e possibile cercare per codice, descrizione o tipo e selezionare la voce desiderata.
4. Impostare la quantita del componente all'interno del KIT.
5. Verificare o modificare prezzo unitario, aliquota IVA e sconto % del componente.
6. Ripetere per ogni componente della distinta base.
7. Il totale del KIT viene calcolato automaticamente come somma dei componenti (quantita x prezzo - sconto, per ciascuna riga).

Quando si inserisce un KIT in un documento (fattura, ordine, DDT), il sistema offre 3 modalita di inserimento:

Opzione “Mantieni prezzo bundle”

Nel popup di inserimento KIT è presente la checkbox “Mantieni prezzo bundle del kit — distribuisci lo sconto sui componenti”. Quando attiva (e si sceglie una delle due modalità di esplosione), i prezzi dei componenti vengono scalati proporzionalmente in modo che la loro somma resti uguale al prezzo bundle del KIT.

Formula: fattore = prezzoBundleKit / sommaPrezziComponenti, applicato a ogni prezzoUnitario di riga esplosa.

Oltre ai dati standard, ogni voce di catalogo puo essere arricchita con contenuti extra configurabili dall'amministratore.

Configurazione

L'amministratore definisce i campi extra da Impostazioni → Configurazione Catalogo → Contenuti Extra. Per ogni campo extra e possibile specificare:

• Nome del campo e etichetta visualizzata
• Tipo di dato (testo, numero, data, lista valori, booleano)
• Obbligatorieta e valore predefinito
• Tipi di voce a cui si applica (es. solo FARMACO, oppure tutti)

Visualizzazione

I contenuti extra appaiono nella scheda della voce di catalogo in una sezione dedicata sotto le tab standard. Sono visibili anche nella griglia di lista tramite colonne configurabili e possono essere utilizzati come criteri di filtro e ricerca.

La lista del catalogo prodotti/servizi supporta filtri persistenti salvati nel localStorage del browser. Questo significa che i filtri impostati dall'utente vengono mantenuti tra una sessione e l'altra.

1. Nella lista catalogo, impostare i filtri desiderati: tipo di voce, stato (attivo/inattivo), categoria, testo libero.
2. I filtri vengono salvati automaticamente nel localStorage del browser al momento dell'applicazione.
3. Alla successiva apertura della pagina, i filtri vengono ripristinati automaticamente.
4. Per azzerare tutti i filtri, premere il pulsante Azzera filtri.

Per le voci di tipo FARMACO, e disponibile il flag Richiede Posologia nella tab Dettaglio.

Funzionamento

• Quando il flag e attivo, il sistema visualizza un avviso ogni volta che il farmaco viene inserito in un documento o in una ricetta, ricordando all'operatore di indicare la posologia.
• L'avviso non e bloccante: l'operatore puo proseguire anche senza compilare la posologia, ma l'avviso resta visibile fino alla compilazione.
• La posologia viene registrata come nota di riga nel documento ed e stampata nella ricetta o nel documento consegnato al paziente.

Gli articoli del catalogo con flag Gestione Magazzino attivo vengono tracciati nelle giacenze. L'integrazione prevede:

Il catalogo può essere importato ed esportato tramite Impostazioni → Import / Export → Catalogo Prodotti.

1. Selezionare il modulo Catalogo Prodotti nella griglia.
2. Premere Configura Campi per scegliere quali dei 59+ campi includere.
3. Assegnare alias personalizzati alle intestazioni se necessario.
4. Esportare in CSV o Excel, oppure importare da file con mappatura automatica.

Gli articoli possono essere organizzati in categorie gerarchiche per facilitare la navigazione e l'analisi.

1. Le categorie si gestiscono dalla sezione Parametri → Gestione Tabelle.
2. Ogni articolo può appartenere a una categoria.
3. Le categorie alimentano i filtri nella lista catalogo, l'analisi ABC per categoria in Magazzino, e il report per categoria nella Dashboard.

Sono due concetti diversi che spesso vengono confusi. Il Tipo definisce cosa è una voce e cambia il funzionamento del software; la Categoria è solo un'etichetta tua per raggrupparla.

TIPO (Tipo voce)

È una classificazione di sistema, a elenco fisso (Farmaco, Integratore, Omeopatico, Fitoterapico, Vitamina, Prodotto/Articolo, Prestazione, Parcella, Kit, Testo libero…). Definisce la natura della voce e cambia il comportamento del software:

• determina quali campi e tab compaiono nella scheda — ad esempio un Articolo ha la tab Magazzino/giacenze, un Kit ha i componenti, un Farmaco ha AIC e posologia, una Prestazione è un servizio senza magazzino;
• determina come la voce si comporta nei documenti;
• determina quali voci appaiono nel catalogo in base al profilo attività.

Non si inventa: si sceglie da una lista predefinita. È obbligatorio.

CATEGORIA

È un'etichetta libera creata dall'utente (col pulsante ⚙️ Gestisci Categorie), puramente organizzativa. Serve a raggruppare, filtrare e cercare le voci senza cambiare nulla nel funzionamento. È opzionale. Esempi: “Vitamine gruppo B”, “Antinfiammatori naturali”, “Creme viso”, “Consulenze”.

Dove si imposta la Categoria

Nella scheda della voce, tab Dati base.

Ogni articolo del catalogo supporta tre codici identificativi per l'integrazione con sistemi di scansione:

Nel modulo Magazzino, il campo scanner barcode nella toolbar cerca per tutti e tre i codici. La stampa etichette genera etichette con barcode Code 128 leggibili dagli scanner.

Aggiornamento strutturale del modulo Catalogo: validazione codici, tracciamento modifiche, statistiche di vendita automatiche, operazioni massive e cestino con soft-delete.

Validazione EAN-13 e blocco duplicati

Al salvataggio il sistema verifica:

• Codice EAN-13: 13 cifre con controllo del check-digit (mod 10). Codici a 8 o 12 cifre (EAN-8, UPC-A) sono accettati senza checksum. Codici non conformi vengono rifiutati con errore 400.
• Duplicati EAN: se esiste già un'altra voce con lo stesso codice a barre il salvataggio viene bloccato (errore 409) e il sistema indica la voce già presente.
• Duplicati codice interno: analogo blocco sul campo codice.

Audit log automatico delle modifiche

Ogni modifica alla scheda voce viene registrata nella tabella log_modifiche_voci_catalogo con valore precedente, valore nuovo, utente e data/ora. I campi tracciati sono 21, tra cui codice, descrizione, tipo voce, categoria, prezzi (default, acquisto, ingrosso, dettaglio), aliquota IVA, EAN, fornitore, stato, marca. La lista storica è accessibile via API GET /api/catalogo/:id/audit-log.

Statistiche di vendita automatiche

I campi di riepilogo della voce sono aggiornati automaticamente ad ogni operazione sui documenti che contengono la voce (creazione, modifica, cambio stato, duplicazione, cancellazione):

• Unità vendute anno corrente e anno precedente (esclusi BOZZA e ANNULLATO)
• Numero vendite (righe documento totali)
• Data ultimo movimento
• Prezzo medio di vendita

È possibile forzare il ricalcolo globale con POST /api/catalogo/ricalcola-stats (utile dopo importazioni massive).

Timeline cronologica della voce

L'endpoint GET /api/catalogo/:id/timeline restituisce una vista aggregata degli eventi della voce: righe documento in cui è stata usata, movimenti di magazzino e modifiche registrate nell'audit, ordinati per data decrescente. Utile per ricostruire lo storico di utilizzo e variazioni del prodotto.

Selezione multipla e azioni massive

Nella lista catalogo è ora disponibile una colonna di checkbox per la selezione multipla:

• Checkbox in intestazione: seleziona/deseleziona tutte le voci visibili nella pagina corrente.
• Checkbox per ogni riga: selezione singola; cliccare sulla spunta non apre la scheda.
• Quando almeno una voce è selezionata compare una barra azioni blu in fondo alla lista.

Azioni disponibili:

• Attiva / Disattiva: cambio massivo del flag attiva.
• Categoria…: assegnazione in blocco di una categoria (vuoto per rimuoverla).
• % IVA…: aggiornamento massivo dell'aliquota IVA di default.
• Elimina: sposta le voci nel cestino (soft-delete, reversibile).

Cestino e soft-delete

L'eliminazione di una voce (singola o massiva) è ora una cancellazione logica: la voce scompare dalla lista attiva ma resta nel database con le colonne cancellatoIl e cancellatoDa valorizzate. Le righe documento storiche non vengono toccate.

• Pulsante 🗑 Cestino nel footer della lista: entra in modalità cestino e mostra solo le voci cancellate.
• Per ogni riga del cestino sono disponibili due azioni:
  • ↺ Ripristina: annulla la cancellazione, la voce torna attiva.
  • ✗ Definitivo: eliminazione fisica irreversibile. Blocca se la voce è ancora usata in righe documento. Disponibile solo per utenti ADMIN o SUPERADMIN.
• In modalità cestino il clic sulla riga non apre la scheda; vengono mostrati data e autore della cancellazione.

A partire dalla versione 2.2, il modulo Catalogo adotta lo standard di certificazione NOX con i seguenti presidi:

Cestino e soft-delete

Gli elementi cancellati non vengono rimossi fisicamente ma spostati in un cestino interno (campi cancellatoIl / cancellatoDa). Dalla toolbar il pulsante Cestino alterna tra vista attivi e vista cestino. Dal cestino è possibile:

• Ripristinare l'elemento (riportarlo nella lista attiva) — operazione riservata ad amministratori.
• Eliminare definitivamente con motivazione obbligatoria — azione irreversibile, riservata ad amministratori, tracciata nell'audit log.

Azioni massive (bulk)

È possibile selezionare più elementi con le checkbox della prima colonna. Appare una barra inferiore con le azioni disponibili: Attiva, Disattiva, Soft-delete. Vincoli su righe documento e movimenti magazzino. La risposta indica N operazioni riuscite / M fallite; i dettagli delle fallite compaiono nella console browser (F12).

Storico modifiche (audit log)

L'icona history nelle azioni di riga apre un modal con la storia completa delle modifiche: data, campo, valore precedente, valore nuovo, operatore, eventuale motivazione. I record di audit non sono modificabili né eliminabili via UI. Conservazione: indefinita (art. 2220 c.c. — 10 anni minimo).

Mascheramento dati sensibili (GDPR art. 32)

Se i campi modificati contengono dati sensibili (IBAN, Codice Fiscale, Partita IVA, password/token), l'audit log salva il valore mascherato anziché in chiaro:

Timeline aggregata

Per ciascun elemento è disponibile una vista Timeline che aggrega in ordine cronologico audit, eventi del ciclo di vita ed eventuali entità collegate (es. documenti, movimenti, storni).

RBAC uniforme

Tutte le azioni distruttive o massive (soft-delete, ripristino, eliminazione definitiva, bulk, storno) richiedono il ruolo ADMIN o superiore. Gli operatori possono continuare a creare / modificare / consultare secondo le proprie abilitazioni.