# Curivo — Documento Pilota ### Piattaforma unificata per Call Center e Customer Relationship Management > **Versione documento:** 1.0 — Marzo 2026 > **Destinazione:** Documentazione interna · Base contenutistica per sito web --- ## Indice 1. [Cos'è Curivo](#1-cosè-curivo) 2. [A chi è rivolto](#2-a-chi-è-rivolto) 3. [Proposizione di valore](#3-proposizione-di-valore) 4. [Architettura dell'applicazione](#4-architettura-dellapplicazione) 5. [Layout e navigazione](#5-layout-e-navigazione) 6. [Mappa dell'applicazione](#6-mappa-dellapplicazione) 7. [Moduli e funzionalità dettagliate](#7-moduli-e-funzionalità-dettagliate) - 7.1 [Dashboard — Monitoraggio in tempo reale](#71-dashboard--monitoraggio-in-tempo-reale) - 7.2 [Call Center — Gestione telefonia](#72-call-center--gestione-telefonia) - 7.3 [IVR — Menu vocali interattivi](#73-ivr--menu-vocali-interattivi) - 7.4 [Callback — Richiamate automatiche](#74-callback--richiamate-automatiche) - 7.5 [CRM — Anagrafica clienti](#75-crm--anagrafica-clienti) - 7.6 [Ticket — Help Desk](#76-ticket--help-desk) - 7.7 [Prenotazioni — Agenda e appuntamenti](#77-prenotazioni--agenda-e-appuntamenti) - 7.8 [Portale di prenotazione pubblico](#78-portale-di-prenotazione-pubblico) - 7.9 [WebPhone — Barra telefonica integrata](#79-webphone--barra-telefonica-integrata) - 7.10 [Chat — Comunicazione interna](#710-chat--comunicazione-interna) - 7.11 [Report — Analytics e performance](#711-report--analytics-e-performance) - 7.12 [Impostazioni e amministrazione](#712-impostazioni-e-amministrazione) 8. [Sistema di sicurezza e accesso](#8-sistema-di-sicurezza-e-accesso) 9. [Architettura multi-tenant](#9-architettura-multi-tenant) 10. [Stack tecnologico](#10-stack-tecnologico) 11. [Glossario](#11-glossario) --- ## 1. Cos'è Curivo Curivo è una **piattaforma cloud all-in-one** progettata per centralizzare e ottimizzare la gestione delle comunicazioni aziendali con i clienti. Integra in un unico ambiente: - un **call center** completamente operativo con telefonia SIP/WebRTC - un **CRM** per la gestione dell'anagrafica clienti - un sistema di **ticketing** per l'assistenza e il supporto - un sistema di **prenotazioni** con agenda, risorse e portale pubblico online - una **chat interna** per la comunicazione tra operatori - reporting e analytics in tempo reale Curivo elimina la frammentazione degli strumenti aziendali: un agente può ricevere una chiamata, aprire la scheda del cliente, consultare lo storico dei ticket, fissare un appuntamento e inviare un messaggio al collega, tutto senza uscire dall'applicazione. --- ## 2. A chi è rivolto | Settore | Caso d'uso tipico | |---|---| | **Call Center** | Gestione code inbound/outbound, monitoraggio agenti, SLA | | **Assistenza clienti** | Ticketing, SLA, risposte predefinite, escalation | | **Servizi professionali** | Agenda appuntamenti, prenotazioni online, gestione risorse | | **PMI con reception** | Centralino SIP integrato, IVR, callback automatici | | **Healthcare / Wellness** | Prenotazioni servizi, reminder, portale online | | **Retail / B2C** | CRM clienti, storico interazioni, follow-up ticket | --- ## 3. Proposizione di valore ### Un solo strumento, tutto il contesto L'operatore che risponde a una chiamata vede istantaneamente chi sta chiamando, la sua storia, i ticket aperti e le prenotazioni future. Non deve cercare in altri sistemi. ### Nessun hardware dedicato La barra telefonica **WebPhone** funziona nel browser tramite protocollo WebRTC/SIP. Non serve installare software o acquistare telefoni fisici. Un notebook con cuffie è sufficiente. ### Portale prenotazioni incluso Ogni azienda può pubblicare una pagina di prenotazione online brandizzata (`curivo.app/prenota/nome-azienda`) dove i clienti scelgono servizio, risorsa, giorno e orario. Gli slot vengono aggiornati in tempo reale. ### Multi-tenant e multi-ruolo L'applicazione è progettata per ospitare clienti (tenant) multipli in completo isolamento. All'interno di ogni tenant, i permessi sono granulari per ruolo: admin, supervisore, agente, operatore CRM, read-only. ### Visibilità in tempo reale Dashboard live con aggiornamento WebSocket: stato degli agenti, chiamate in coda, SLA, pause — senza ricaricare la pagina. --- ## 4. Architettura dell'applicazione ``` ┌─────────────────────────────────────────────────────────┐ │ BROWSER (Vue 3 SPA) │ │ │ │ Layout (sidebar + header) │ │ ├── Dashboard (WebSocket live) │ │ ├── Call Center (Code / Interni / IVR / Callback) │ │ ├── CRM (Clienti / Ticket / Prenotazioni) │ │ ├── Report │ │ ├── Impostazioni │ │ ├── WebPhone FAB ──────── SIP/WebRTC ──────────────┐ │ │ └── Chat FAB │ │ └───────────────────────────────┬─────────────────────┼──┘ │ REST API │ │ WebSocket │ SIP ┌─────────────────▼──────────┐ │ │ Node.js / Express │ │ │ (curivo-backend) │ │ │ │ │ │ ├── authController │ │ │ ├── phoneBarController │ │ │ ├── callCenterController │ │ │ ├── ivrController │ │ │ ├── callbackController │ │ │ ├── customerController │ │ │ ├── ticketsController │ │ │ ├── bookingController │ │ │ ├── chatController │ │ │ ├── reportsController │ │ │ └── websocketService │ │ └─────────┬──────────────────┘ │ │ │ ┌─────────▼──────┐ ┌──────────────────▼──┐ │ MySQL DB │ │ Asterisk PBX │ │ (curivo_db) │ │ (AMI + SIP/PJSIP) │ └────────────────┘ └──────────────────────┘ ``` **Flusso dati real-time:** il backend mantiene una connessione AMI (Asterisk Manager Interface) verso il PBX. Gli eventi (chiamata entrante, agente che si mette in pausa, ecc.) vengono immediatamente propagati via WebSocket a tutti i client connessi. La Dashboard si aggiorna senza polling. --- ## 5. Layout e navigazione ### Struttura visiva ``` ┌─────────────────────────────────────────────────────────┐ │ SIDEBAR │ AREA CONTENUTO PRINCIPALE │ │ ┌──────────────────┐ │ │ │ │ Logo Curivo │ │ [Header pagina] │ │ ├──────────────────┤ │ [KPI / Stats bar] │ │ │ Dashboard │ │ [Filtri / Ricerca] │ │ │ ▼ Call Center │ │ [Tabella / Griglia / Form] │ │ │ ├ Code │ │ │ │ │ ├ Interni │ │ │ │ │ ├ IVR │ │ │ │ │ └ Callback │ │ │ │ │ ▼ CRM │ │ │ │ │ ├ Clienti │ │ │ │ │ ├ Ticket │ │ │ │ │ └ Prenotazioni│ │ │ │ │ Report │ │ │ │ │ Impostazioni │ │ │ │ ├──────────────────┤ │ │ │ │ [Profilo utente]│ │ │ │ └──────────────────┘ │ │ │ │ [📞 WebPhone FAB]│ │ │ [💬 Chat FAB] │ └─────────────────────────────────────────────────────────┘ ``` ### Caratteristiche del layout - **Sidebar collassabile**: si riduce a sola icona per massimizzare lo spazio di lavoro - **Gruppi espandibili**: Call Center e CRM sono sezioni pieghevoli con sottovoci visibili solo se si dispone dei permessi - **Responsive**: overlay mobile con tap per chiudere la sidebar - **FAB flottanti**: WebPhone e Chat sono accessibili da qualsiasi pagina tramite pulsanti azione galleggianti nell'angolo in basso a destra - **Badge notifiche**: Chat mostra contatore messaggi non letti in tempo reale - **Session warning**: modal automatica che avvisa l'utente 2 minuti prima del timeout di inattività (15 minuti di default), con possibilità di estendere la sessione --- ## 6. Mappa dell'applicazione ``` / (root) └── /login Login con 2FA opzionale /dashboard Dashboard live call center /extensions Gestione interni telefonici /queues Gestione code di chiamata /ivr Editor menu IVR /callbacks Gestione richieste callback /customers Lista clienti (CRM) /customers/:id Scheda cliente dettagliata └── Tab: Info / Contatti / Indirizzi / Campi Custom / Privacy / Ticket / Prenotazioni / Timeline /tickets Lista ticket (vista lista o kanban) /tickets/:id Scheda ticket con activity feed /settings/tickets Impostazioni ticket └── Tab: Categorie / Risposte predefinite / Policy SLA /bookings Agenda prenotazioni └── Tab: Agenda / Settimana / Mese / Lista /settings/bookings Configurazione prenotazioni └── Tab: Servizi / Risorse / Disponibilità / Portale online /reports Hub report disponibili /reports/:type Report dettagliato con filtri + export CSV /settings Hub impostazioni /profile Profilo personale + 2FA /users Gestione utenti del team /permissions Ruoli, permessi e visibilità menu /tenant-settings Configurazione azienda + telefonia /settings/crm-fields Campi custom CRM /logs Visualizzatore log HTTP /docs Documentazione tecnica interna /prenota/:slug Portale di prenotazione pubblico (no auth) ``` --- ## 7. Moduli e funzionalità dettagliate --- ### 7.1 Dashboard — Monitoraggio in tempo reale La Dashboard è il cuore operativo di Curivo per i supervisori e i responsabili del call center. #### Cosa mostra **Pannello code (per ogni coda attiva):** - Chiamate in attesa in coda - Tempo medio di attesa (ASA — Average Speed of Answer) - Livello di servizio (SLA): percentuale di chiamate risposte entro la soglia configurata - Chiamate abbandonate (con tasso di abbandono) - Agenti disponibili vs. totali - Agenti in pausa (con motivo) - Agenti in conversazione **Pannello agenti:** - Lista operatori con stato in tempo reale: disponibile, in chiamata, in pausa, offline - Durata dello stato corrente - Extension SIP assegnata - Chiamate gestite nella sessione corrente **Metriche storiche della giornata:** - Totale chiamate entranti - Totale chiamate gestite - Totale tempo di conversazione - Tasso di abbandono #### Funzionalità tecniche - **Aggiornamento WebSocket** senza polling: ogni evento Asterisk (chiamata, risposta, pausa, coda) viene propagato in millisecondi - **Indicatore stato connessione**: live / disconnesso con riconnessione automatica - **Indicatore AMI**: stato connessione al PBX Asterisk - **Sincronizzazione queue log**: pulsante per allineamento manuale dei log storici - **Glossario KPI**: modale di riferimento con definizione di tutti i parametri - **Impostazioni SLA**: configurazione soglie per coda direttamente dalla dashboard --- ### 7.2 Call Center — Gestione telefonia #### Code di chiamata (`/queues`) Gestione completa delle **ACD queue** Asterisk. | Funzione | Descrizione | |---|---| | Creazione coda | Nome, numero, strategia di distribuzione (ringall, leastrecent, fewestcalls, rrmemory…) | | Modifica parametri | Timeout, ringtone, annunci, musica d'attesa | | Gestione membri | Aggiunta/rimozione agenti con penalità configurabile | | Sincronizzazione Asterisk | Push immediato della configurazione al PBX via AMI | | Stato live | Indicatore agenti connessi, badge numero chiamate attive | | Mostra/nascondi inattive | Toggle per gestire code in archivio | #### Interni telefonici (`/extensions`) Registro degli **interni SIP/PJSIP** del PBX. | Funzione | Descrizione | |---|---| | Aggiunta interno | Numero, nome, password SIP, utente associato | | Associazione utente | Ogni interno può essere collegato a un account Curivo | | Device state AMI | Stato in tempo reale: INUSE, RINGINUSE, NOT_INUSE, UNAVAILABLE | | Sincronizzazione Asterisk | Applicazione configurazione PJSIP al PBX | | Mostra/nascondi disattivati | | --- ### 7.3 IVR — Menu vocali interattivi Editor visivo per la configurazione dei **menu IVR** (Interactive Voice Response) senza toccare file di configurazione Asterisk. #### Struttura di un menu IVR ``` Menu IVR ├── Tasto 1 → Coda "Supporto" ├── Tasto 2 → Sotto-menu "Commerciale" │ ├── Tasto 1 → Coda "Vendite" │ └── Tasto 0 → Esterno ├── Tasto 9 → Callback automatico └── Timeout → Coda "Default" ``` #### Funzionalità - **Creazione menu**: nome, interno DID associato, messaggio di benvenuto - **Opzioni DTMF**: configurazione per ogni tasto (0–9, *, #) - **Tipi di destinazione**: coda, interno, sotto-menu IVR, numero esterno, saluta e termina, callback - **Condizioni orarie**: routing diverso in base ad orari e festività - **Audio personalizzato**: upload file audio (WAV/MP3) per annunci custom - **Salvataggio + sync Asterisk**: scrittura diretta dei file di configurazione e reload del PBX - **Visualizzazione alberatura**: preview struttura del menu in form espandibile --- ### 7.4 Callback — Richiamate automatiche Sistema che permette ai chiamanti di **richiedere di essere richiamati** invece di attendere in coda. Il worker automatico gestisce la schedulazione e il retry. #### Flusso callback ``` Chiamante preme tasto IVR "Callback" ↓ Sistema registra: numero, orario, coda ↓ Worker scansiona le richieste pendenti ↓ Originate chiamata Asterisk verso il numero ↓ Se risposta → connette alla coda disponibile Se no risposta → retry (max tentativi configurabile) ↓ Completato / Fallito → storico aggiornato ``` #### Funzionalità del modulo | Funzione | Descrizione | |---|---| | Lista callback | Filtri per stato: in attesa, in lavorazione, completato, fallito, annullato | | KPI istantanei | In attesa, completati oggi, falliti, tasso successo | | Creazione manuale | Inserimento richiesta da operatore (nome, numero, note, orario preferito) | | Dettaglio richiesta | Tutto lo storico tentativi con timestamp | | Annullamento | Operatore può cancellare la richiesta | | Impostazioni worker | Orari lavorativi, max tentativi, ritardo tra tentativi, coda di destinazione | --- ### 7.5 CRM — Anagrafica clienti Il modulo CRM è la **base anagrafica centralizzata** dell'intera piattaforma. Ticket e prenotazioni sono sempre associati a un cliente. #### Lista clienti (`/customers`) - **Ricerca full-text**: nome, azienda, email, telefono - **Filtri**: stato (lead, attivo, inattivo), tipo (persona, azienda) - **Paginazione** con selezione righe per pagina - **Creazione rapida** da modale inline #### Scheda cliente (`/customers/:id`) La scheda è divisa in **8 tab** che si caricano progressivamente: --- **Tab Info Base** - Dati anagrafici: nome, cognome, ragione sociale, codice fiscale/P.IVA - Tag personalizzabili (sistema di etichettatura colorato) - Stato cliente e tipo (persona/azienda) - Note generali **Tab Contatti** - Telefoni, email, profili social, fax, siti web - Ciascun contatto ha tipo, valore e flag "principale" - Aggiunta/modifica/eliminazione in linea **Tab Indirizzi** - Indirizzi multipli (sede legale, operativa, spedizione…) - Campi: via, civico, CAP, città, provincia, stato **Tab Campi Custom** - Campi aggiuntivi definiti dall'amministratore (vedi §7.12) - Supporto per: testo, numero, data, checkbox, select, URL **Tab Privacy** - Gestione consensi GDPR - Flag: marketing, profilazione, comunicazioni commerciali, comunicazioni terzi - Data consenso e note privacy **Tab Ticket** - Lista ticket del cliente con stato, priorità, data - Badge con contatore ticket aperti (precaricato al mount) - Link diretto alla scheda ticket **Tab Prenotazioni** - Lista prenotazioni associate con servizio, risorsa, data, stato - Badge con contatore prenotazioni (precaricato al mount) - Link diretto all'agenda **Tab Timeline** - Vista cronologica unificata di **tutti gli eventi** riguardanti il cliente: - Modifiche alla scheda - Apertura/chiusura ticket - Creazione prenotazioni - Icona distintiva per tipo evento (scheda, ticket, prenotazione) - Numero di riferimento (TK-XXXX, BK-XXXX) e titolo - Link diretto per ticket --- ### 7.6 Ticket — Help Desk Sistema completo di **gestione richieste di supporto** con SLA, categorie, commenti e activity feed. #### Lista ticket (`/tickets`) **Due viste intercambiabili:** **Vista Lista** — tabella con colonne: #numero, titolo, stato, priorità, categoria, assegnato, cliente, SLA, data **Vista Kanban** — colonne: Aperto · In lavorazione · In attesa · Risolto · Chiuso **KPI bar (sopra la lista):** | KPI | Descrizione | |---|---| | Aperti | Ticket non ancora presi in carico | | In lavorazione | Ticket assegnati a un operatore | | In attesa | In attesa di risposta dal cliente | | Scaduti | Superato il termine di risposta/risoluzione | | SLA Breach | Violazione del livello di servizio | | Tempo risoluzione medio | Media in ore per la chiusura | **Filtri rapidi (chip):** Tutti · I miei · Non assegnati · Oggi · Questa settimana · Questa settimana non risolti **Filtri avanzati:** stato, priorità, categoria, assegnato, cliente, data apertura, SLA #### Scheda ticket (`/tickets/:id`) **Layout a due colonne:** Colonna principale (activity feed): - Descrizione originale del ticket - Feed cronologico di: commenti pubblici, note interne (in evidenza gialla), cambi di stato - Input per aggiungere commento/nota interna - Risposte predefinite (canned responses) con ricerca Colonna laterale (metadati): - Stato (aperto, in lavorazione, in attesa, risolto, chiuso) - Priorità (bassa, media, alta, critica) - Categoria (con colore) - Assegnato a (operatore) - Cliente collegato - Data apertura, ultima modifica, data risoluzione - SLA timer: countdown al breach con indicatore visivo - Tag - Watcher (utenti che seguono il ticket) - Allegati #### Impostazioni ticket (`/settings/tickets`) **Categorie**: colore, nome, descrizione — completamente personalizzabili **Risposte predefinite (Canned Responses)**: template di risposta riutilizzabili con titolo e testo, ricercabili per parola chiave durante la composizione **Policy SLA**: definizione per categoria/priorità di: - Tempo massimo primo contatto - Tempo massimo risoluzione - Notifica pre-breach (%) --- ### 7.7 Prenotazioni — Agenda e appuntamenti Sistema di gestione appuntamenti con **4 viste**, statistiche e portale online integrato. #### Vista Agenda Elenco cronologico delle prenotazioni. Per ogni voce: orario, cliente, servizio, risorsa, stato, note. #### Vista Settimana Griglia settimanale con colonne per risorsa. Slot orari configurabili. Le prenotazioni appaiono come blocchi colorati (colore del servizio). #### Vista Mese Calendario mensile con indicatore del numero di prenotazioni per giorno. Click sul giorno per vedere la lista. #### Vista Lista Tabella filtrata con ordinamento per data, stato, servizio, risorsa, cliente. #### KPI bar | KPI | Descrizione | |---|---| | Oggi | Totale prenotazioni della giornata | | Confermate | Prenotazioni confermate oggi | | Da confermare | In stato pending | | Completate | Appuntamenti conclusi oggi | | Questa settimana | Totale settimanale | #### Funzionalità operative | Funzione | Descrizione | |---|---| | Nuova prenotazione | Modale con: cliente (autocomplete), servizio, risorsa, data/ora, stato, note, note interne | | Modifica prenotazione | Modale di editing completo in visualizzazione dettaglio | | Blocco slot | Impedisce nuove prenotazioni per una risorsa in un intervallo orario | | Filtri | Per data, servizio, risorsa, stato | | Stato | Pending / Confermata / Completata / Annullata / No-show | | Allegati | Caricamento documenti alla prenotazione | | Prenotazioni ricorrenti | Serie con regola di ricorrenza | #### Impostazioni prenotazioni (`/settings/bookings`) **Servizi**: nome, durata (minuti), buffer post-appuntamento, prezzo, colore, descrizione, attivo/inattivo **Risorse**: stanze, operatori, strumenti — con servizi associati e impostazione concorrenza massima **Disponibilità**: orari di apertura per risorsa, giorno della settimana, con possibilità di eccezioni (chiusure, festività) **Portale online**: attivazione/disattivazione del portale pubblico, titolo, descrizione, logo, colore brand, URL slug personalizzato --- ### 7.8 Portale di prenotazione pubblico Pagina pubblica raggiungibile all'indirizzo `/prenota/:slug` (nessuna autenticazione richiesta). Il wizard guida il cliente in **4 passi**: ``` PASSO 1 PASSO 2 PASSO 3 PASSO 4 Scegli Scegli Scegli I tuoi servizio → risorsa → data+orario → dati (card grid) (card grid) (calendario (form nome, + slot) email, tel, note) ↓ CONFERMA (email auto) ``` - Disponibilità aggiornata in tempo reale: nessun doppio booking - Slot bloccati non appaiono - Conferma immediata con riepilogo - Brandizzabile per tenant (logo, colore, testo personalizzato) - La prenotazione entra direttamente nell'agenda interna con stato "pending" --- ### 7.9 WebPhone — Barra telefonica integrata Il WebPhone è un **softphone WebRTC/SIP integrato nel browser**, accessibile da qualsiasi pagina tramite il pulsante flottante in basso a destra. #### Stati del softphone ``` [📵 DISCONNESSO] ↓ "Inizia turno" [✅ DISPONIBILE (SIP registered)] ↓ chiamata entrante [📞 IN CHIAMATA] ↓ fine chiamata [⏸ IN PAUSA] ←→ [✅ DISPONIBILE] ↓ "Termina turno" [📵 DISCONNESSO] ``` #### Funzionalità | Funzione | Descrizione | |---|---| | Registrazione SIP | Connessione automatica al PBX con le credenziali dell'interno assegnato | | Gestione turno | Inizio/fine sessione di lavoro con tracking ore | | Pausa | Selezione motivo pausa (motivi configurabili), tracking durata | | Chiamata in uscita | Composizione numero manuale con tastierino DTMF | | Trasferimento | Blind transfer e attended transfer | | Mute | Silenziamento microfono durante la chiamata | | In attesa (hold) | Messa in attesa con musica | | Chiamata entrante | Notifica con ring, nome chiamante, tasto risposta/rifiuta | | Rubrica interni | Ricerca colleghi con stato (disponibile/occupato) e chiamata diretta | | Timer sessione | Durata turno corrente e contatore chiamate | | Riconnessione automatica | In caso di F5 o refresh pagina durante il turno, il WebPhone recupera lo stato | | Protezione da reload | Avviso se si tenta di chiudere il browser durante una chiamata | #### Heartbeat e sessioni Il WebPhone invia un heartbeat ogni 30 secondi al backend (`/api/agent/workstation/heartbeat`). Le sessioni senza heartbeat da oltre 5 minuti vengono considerate orfane e chiuse automaticamente, prevenendo il blocco all'avvio del turno successivo. --- ### 7.10 Chat — Comunicazione interna Sistema di messaggistica istantanea tra gli operatori del team, accessibile tramite FAB in basso a destra. #### Funzionalità | Funzione | Descrizione | |---|---| | Chat diretta | Conversazione 1:1 tra due utenti/interni | | Gruppi | Canali condivisi multi-utente con nome e descrizione | | Messaggi in tempo reale | Invio/ricezione via WebSocket, nessun refresh necessario | | Badge non letti | Contatore visibile sull'icona FAB, aggiornato live | | Archivio | Conversazioni archiviate accessibili da pannello dedicato | | Cerca/filtra | Ricerca tra le conversazioni attive | | Info gruppo | Elenco membri, possibilità di aggiungere/rimuovere | | Vista mobile | Layout adattivo (sidebar conversazioni → area chat) | --- ### 7.11 Report — Analytics e performance Hub report accessibile da `/reports` con drill-down dettagliato per ogni tipologia. #### Report disponibili **Performance Agenti** Analisi per operatore nel periodo selezionato: - Chiamate gestite, tempo conversazione, tempo pausa, efficienza - Comparazione tra agenti - Export CSV **Dettaglio Pause** Analisi utilizzo pause: - Distribuzione per motivo (regolamentata, operativa, personale…) - Durata media, totale minuti per agente - Trend nel periodo **Analisi Code** Performance di ogni coda: - Volume chiamate per ora del giorno / giorno della settimana - Tempo medio attesa, tasso abbandono, livello servizio - Confronto SLA configurato vs. effettivo **Chiamate Perse** - Lista chiamate abbandonate con dettaglio - Callback generati automaticamente #### Funzionalità trasversali - **Filtri avanzati**: periodo personalizzato, agenti specifici, code specifiche - **Filtri attivi**: chip removibili per filtro applicato - **Genera Report**: i dati si caricano solo al submit (lazy loading) - **Export CSV**: download del dataset completo con filtri applicati --- ### 7.12 Impostazioni e amministrazione Hub accessibile da `/settings` con card di accesso rapido a tutte le sezioni configurative. #### Profilo utente (`/profile`) - Modifica nome, email, password - Autenticazione a due fattori **(2FA)**: - Setup via QR code (TOTP compatibile con Google Authenticator, Authy, ecc.) - Abilitazione/disabilitazione con conferma OTP - Nuovo QR code ad ogni riattivazione per sicurezza #### Gestione utenti (`/users`) | Funzione | Descrizione | |---|---| | Lista utenti | Ricerca per username/nome/email, filtro per ruolo | | Creazione utente | Username, nome, email, password, ruolo, interno assegnato | | Modifica | Tutti i campi + reset password | | Disabilitazione | Revoca accesso senza eliminazione storico | | Eliminazione | Soft delete | #### Gestione permessi e ruoli (`/permissions`) **Ruoli**: creazione e configurazione di profili con set di permessi specifici. Ruoli di sistema: admin, supervisor, agent, readonly. **Permessi**: matrice granulare. Ogni permesso ha la forma `risorsa.azione` (es. `tickets.create`, `bookings.edit`, `users.view`). **Visibilità menu**: controllo separato su quali voci del menu laterale sono visibili per ogni ruolo, indipendentemente dai permessi tecnici. #### Configurazione tenant (`/tenant-settings`) | Sezione | Contenuto | |---|---| | Informazioni azienda | Nome, indirizzo, P.IVA, logo, email, sito | | Configurazione PBX | Host Asterisk, porta AMI, credenziali | | Impostazioni workstation | ACW duration, pause automatiche per inattività, motivi pausa | | Orari di apertura | Fasce orarie call center per giorno settimana | | Festività | Calendario chiusure (impatto su IVR e callback) | #### Campi custom CRM (`/settings/crm-fields`) Definizione dei **campi aggiuntivi** che compaiono nella tab "Campi Custom" di ogni scheda cliente: | Tipo campo | Esempio utilizzo | |---|---| | Testo breve | Codice interno, nickname | | Testo lungo | Note estese, indicazioni | | Numero | Limite di credito, numero contratto | | Data | Data scadenza, data anniversario | | Checkbox | Cliente VIP, newsletter attiva | | Dropdown | Segmento, categoria, regione | | URL | Profilo LinkedIn, portale self-service | Ordine di visualizzazione trascinabile, flag obbligatorio, label personalizzata. #### Log di sistema (`/logs`) Visualizzatore dei log HTTP del backend con filtri per: - File di log (data) - Metodo HTTP (GET, POST, PUT, DELETE) - Endpoint - Status code - Ricerca testo #### Documentazione tecnica (`/docs`) Viewer Markdown integrato con rendering completo di tutti i documenti tecnici del progetto (changelog, guide, architettura), scaricabili in formato .md. --- ## 8. Sistema di sicurezza e accesso ### Autenticazione - **JWT con refresh token**: token di accesso con scadenza breve + refresh token per rinnovo silenzioso - **2FA TOTP**: autenticazione a due fattori opzionale per account con Google Authenticator o compatibili - **Protezione route**: ogni route è protetta con guard che verifica autenticazione e permessi specifici ### Session management - **Timeout inattività**: 15 minuti per agenti, 20 per supervisori, 30 per admin (configurabile) - **Warning a 2 minuti**: modal di avviso prima del logout automatico - **Heartbeat client**: segnale ogni 60 secondi per aggiornare l'attività - **Auto-refresh token**: ogni 5 minuti se l'utente è attivo ### Autorizzazione granulare Sistema RBAC (Role-Based Access Control) a due livelli: 1. **Permessi tecnici**: controllano cosa le API restituiscono e cosa il frontend rende cliccabile (`v-can` directive) 2. **Visibilità menu**: controllano cosa è visibile nella sidebar, indipendentemente dai permessi Questo permette di configurare attività come "può fare ma non vede nella navigazione" per utenti di servizio. ### Sicurezza delle comunicazioni - Tutte le chiamate API trasportano il token JWT nell'header Authorization - Le credenziali SIP non vengono mai esposte nel frontend (recuperate via API autenticata) - Rate limiting sulle API pubbliche (portale prenotazioni) --- ## 9. Architettura multi-tenant Curivo è progettato per ospitare **più aziende (tenant) sulla stessa installazione** in completo isolamento: - Ogni record nel DB contiene `tenant_id` - Le query sono sempre filtrate per tenant dell'utente autenticato - Non è possibile accedere a dati di altri tenant tramite API - Configurazioni SIP, IVR, code, utenti, clienti, ticket, prenotazioni sono tutte tenant-specific - Il portale pubblico (`/prenota/:slug`) è namespaced per tenant tramite slug univoco - Il piano abbonamento può limitare le funzionalità disponibili per tenant --- ## 10. Stack tecnologico ### Frontend | Tecnologia | Versione | Ruolo | |---|---|---| | Vue 3 | 3.x | Framework UI (Composition API + Options API) | | Pinia | latest | State management | | Vue Router | 4.x | Routing SPA | | Axios | latest | HTTP client con interceptor JWT | | SIP.js | latest | WebRTC/SIP per il WebPhone | | date-fns | latest | Gestione date | | Vite | latest | Build tool + dev server con proxy | ### Backend | Tecnologia | Versione | Ruolo | |---|---|---| | Node.js | 18+ | Runtime | | Express | 4.x | HTTP framework | | MySQL 8 | 8.x | Database relazionale | | ws | latest | WebSocket server | | node-asterisk-manager | — | Integrazione AMI | | PM2 | latest | Process manager (2 processi: API + callback worker) | | Redis | — | Cache | ### Infrastruttura | Componente | Ruolo | |---|---| | Asterisk PBX | Telefonia SIP/PJSIP, code ACD, IVR | | Nginx | Reverse proxy HTTP/HTTPS + WebSocket | | MySQL | Persistenza dati | | PM2 | Supervisione processi Node.js | ### Struttura repository ``` curivo/ ├── curivo-frontend/ Vue 3 SPA │ ├── src/ │ │ ├── views/ Pagine router (20+ views) │ │ ├── components/ Componenti UI │ │ │ ├── base/ Componenti atomici (Button, Modal, Toast…) │ │ │ ├── Layout.vue Struttura sidebar + navigazione │ │ │ ├── PhoneBar.vue WebPhone (2000+ righe) │ │ │ └── FloatingChat.vue Chat flottante │ │ ├── stores/ Pinia stores (auth, users) │ │ ├── composables/ WebSocket, session timeout │ │ ├── directives/ v-can, v-role │ │ └── config/ API axios, session config │ └── vite.config.js │ ├── curivo-backend/ Node.js API │ ├── src/ │ │ ├── controllers/ Business logic (15+ controller) │ │ ├── routes/ allRoutes.js (250+ endpoint) │ │ ├── services/ AMI, WebSocket, SessionTracker │ │ └── middleware/ Auth, validazione, permessi │ ├── migrations/ SQL versionate (024 migrazioni) │ └── ecosystem.config.js PM2 configuration │ └── docs/ Documentazione tecnica ``` --- ## 11. Glossario | Termine | Definizione | |---|---| | **ACW** | After Call Work — tempo post-chiamata per sbrigare attività successive | | **AMI** | Asterisk Manager Interface — protocollo di controllo del PBX | | **ASA** | Average Speed of Answer — tempo medio di risposta alla chiamata | | **ACD** | Automatic Call Distributor — sistema di smistamento chiamate nelle code | | **Coda** | Punto di accumulo di chiamate in attesa distribuite agli agenti disponibili | | **DTMF** | Dual-Tone Multi-Frequency — segnali tono tasti telefonici | | **Extension / Interno** | Numero SIP assegnato a un operatore | | **Hold** | Messa in attesa di una chiamata attiva | | **IVR** | Interactive Voice Response — menu vocale automatico pre-risposta | | **JWT** | JSON Web Token — standard per autenticazione stateless | | **KPI** | Key Performance Indicator — metrica di performance | | **Payload** | Dati contenuti in un evento o richiesta | | **PJSIP** | Implementazione SIP moderna in Asterisk | | **RBAC** | Role-Based Access Control — controllo accessi basato su ruoli | | **SIP** | Session Initiation Protocol — protocollo VoIP | | **SLA** | Service Level Agreement — accordo su livelli di servizio | | **SLA Breach** | Violazione dei tempi previsti dall'SLA | | **Softphone** | Telefono software che usa il microfono del PC invece di hardware fisico | | **Tenant** | Azienda/organizzazione cliente che usa l'istanza Curivo | | **TOTP** | Time-based One-Time Password — standard per 2FA (Google Authenticator) | | **Transfer** | Trasferimento di una chiamata a un altro interno o coda | | **WebRTC** | Web Real-Time Communication — tecnologia browser per audio/video | | **WebSocket** | Protocollo di comunicazione bidirezionale persistente browser↔server | | **Worker** | Processo background Node.js (callback-worker) per elaborazione asincrona | --- *Documento generato internamente. Uso riservato — base per sito web e materiali commerciali.* *Curivo © 2026 — Tutti i diritti riservati*