| Ambiente | Cliente | Stato | URL | Admin Email | Agente DO | Creato | Azioni | |
|---|---|---|---|---|---|---|---|---|
| Caricamento ambienti… | ||||||||
| Mese | Richieste | Pagine | Testo nativo | Tesseract | PaddleOCR / misto | Vision | ms / pagina | Job asincroni | Costo vision (€) |
|---|---|---|---|---|---|---|---|---|---|
| Caricamento… | |||||||||
| Data/Ora | Azione | Ambiente | Utente | Dettagli |
|---|---|---|---|---|
| Caricamento log… | ||||
genera-credenziali-ocr): la pipeline lo riallinea da sola quando il check ocr di system_health è KO. Al salvataggio viene propagato al config.tenant.php di tutti i tenant attivi.METER_TOKEN_SECRET. Se i due non combaciano byte per byte, la chat dei tenant con l'obbligo di misura attivo si ferma. Cifrato at-rest: dopo il salvataggio il campo mostra solo il prefisso, e un valore mascherato non viene risalvato. La sonda che dice se il gateway è a posto è /meter/health (configured: true), non questo campo.curl -sS -H "X-Cron-Secret: <secret>" "https://legaldev.shakazamba.space/twiza-admin/admin-api.php?action=cron_calendar_notifications"
🧭 Panoramica prodotto
TWIZA Legal è la piattaforma multi-tenant per gli studi legali: assistenza AI ancorata ai documenti del fascicolo, redazione di atti e calendario condiviso. Da questo pannello si crea e si governa il ciclo di vita di ogni ambiente cliente.
Tre pezzi lavorano insieme:
- twiza-legal-platform — questo pannello e il sito di ogni tenant.
- twiza-licenses — il servizio che emette e valida le licenze, manda le email (SES) e tiene il registro dei consumi.
- DigitalOcean GradientAI — gli agenti e le Knowledge Base dei tenant.
Un cliente può avere più ambienti, uno per tipologia di agente:
Case Manager (cm), Bank Legal Counsel
(bc) e Legal Drafter (ld). Lo studio che li ha
tutti e tre passa dall'uno all'altro dal selettore in alto, senza rifare il login.
⊞ Dashboard
La schermata iniziale: lo stato della piattaforma in un colpo d'occhio.
Indicatori
- Ambienti totali e attivi, con l'andamento.
- Agenti DO — quanti agenti GradientAI sono provisionati.
- Licenze attive, in scadenza, scadute.
- Attività — azioni admin nelle ultime 24 ore.
- Costo misurato del mese e TWIZA Talent consumati — misurati, non stimati: vengono dal registro dei consumi di twiza-licenses. «n/d» non è zero.
Sotto: gli ambienti più recenti, il log attività compatto e lo stato dei servizi. ＋ Nuovo Ambiente apre direttamente la creazione.
⬡ Gestione ambienti
Un ambiente è licenza + agente AI + Knowledge Base + database + sito del tenant. È l'unità operativa della piattaforma.
Creare un ambiente
Il form ＋ Nuovo Ambiente TWIZA chiede:
- Nome Ambiente e Slug URL — lo slug diventa sottocartella, nome del DB e URL del tenant (l'anteprima sotto il campo mostra l'indirizzo finale).
- Email Admin e Username Admin — a chi arriva la welcome email e con che utenza entra.
- Tipologia agente —
cm,bcold: decide quale interfaccia vede il cliente. - Piano (tier) — il menu si costruisce dal registro licenze; vedi la tabella qui sotto.
- Modello LLM dell'agente — opzionale; vuoto significa default della piattaforma. Vale solo per gli ambienti nuovi: per quelli esistenti si cambia dal dettaglio.
- License key esistente — opzionale: se la fornisci, il primo step salta l'emissione e riusa quella.
I piani
Un piano ha due numeri, e solo due: spazio e utenti. I vecchi tetti a siti web e pratiche sono stati rimossi — erano limiti che il cliente scopriva solo sbattendoci contro. Spazio e utenti si leggono dal registro licenze (pannello licenze, Listini → dotazioni dei piani); i valori qui sotto si leggono dal registro quando apri questa guida; se il registro non risponde, il pannello mostra il proprio ripiego dichiarato e lo segnala.
- Il proprietario dell'ambiente conta come utente: con un piano da 1 utente lo occupa lui, e non si aggiunge nessuno.
- Gli ambienti già esistenti si allineano al registro: il tenant rilegge il proprio limite a intervalli regolari e la ridistribuzione del template lo riscrive.
- Chi è già oltre un limite nuovo resta com'è: nessun utente viene disattivato e nessun file cancellato. Si rifiuta solo il prossimo utente o il prossimo file.
- Non ci sono limiti a pratiche, siti web o altri contenitori.
Il provisioning passo per passo (14 step)
Alla creazione la piattaforma esegue in sequenza, e ogni passo lascia traccia nella coda job:
issue_license— emette la licenza su twiza-licenses (saltato se ne hai fornita una).create_kb— crea la Knowledge Base su DigitalOcean.schedule_kb_indexing— programma la prima indicizzazione.create_agent— crea l'agente GradientAI.create_agent_key— genera la chiave dell'agente.attach_kb_to_agent— collega la KB all'agente.create_spaces_folder— crea la cartella del tenant nel bucket Spaces.attach_spaces_to_kb— collega la cartella come data source della KB.meter_default_on— accende la misurazione dei consumi.deploy_files— carica il template del sito.init_db— inizializza il database del tenant.verify_db— verifica che lo schema sia a posto.send_welcome— manda la welcome email con le credenziali.register_engine— registra l'ambiente presso il motore.
Il drawer di dettaglio
Cliccando un ambiente si apre il pannello laterale con URL, stato, utenza admin, UUID ed endpoint dell'agente, chiave dell'agente (mascherata, con Rivela e Copia), UUID della Knowledge Base, cartella Spaces e dati della licenza.
Azioni
Non compaiono tutte sempre: dipendono dallo stato dell'ambiente, ed è voluto — un bottone che non ha senso adesso è un bottone che fa danni.
- Apri Ambiente ↗ — va al sito del tenant. Sempre.
- ✎ Modifica — cambia i dati, incluso il modello LLM dell'agente e il cliente a cui l'ambiente è agganciato (serve per passare fra CM/BC/LD senza rifare il login). Sempre.
- 🔑 Aggiorna Licenza e ➕ Estendi Licenza — solo se l'ambiente ha una licenza collegata.
- ↺ Riprovisiona — rilancia gli step. Solo se lo stato è error, pending o failed.
- ⤴ Rollback risorse parziali — solo se lo stato è error o failed.
- ⚙ Rigenera config — riscrive il
config.tenant.phpdel tenant. Solo se attivo. - 🔗 Riallinea KB DO — stacca le KB dall'agente, programma l'indicizzazione notturna e recupera l'URL dell'agente. Solo se attivo e se ha sia KB sia agente. Vedi RAG & Knowledge Base.
- 📝 Aggiorna prompt agente — porta il system prompt dell'agente alla versione corrente. Solo se attivo e con agente.
- ⬇ Export GDPR — esporta i dati personali del tenant (art. 15/20). Solo se attivo.
- ✕ Elimina — distruttiva: vedi l'avvertenza sotto.
kb_reindex) che parte dal backoffice del tenant e dal tick periodico. In questo pannello la si guarda (riquadro Indicizzazione KB · tempi), non la si comanda.⌂ Clienti & licenze
L'anagrafica commerciale e il legame fra cliente e ambienti.
L'anagrafica viene da Sales
I clienti si creano e si modificano nell'anagrafica centrale di twiza-licenses (Sales). Questa pagina la legge: il bottone ⇣ Sincronizza ora scarica le novità, e lo stesso giro parte da solo ogni 10 minuti. Un giro ogni 30 secondi al massimo: se clicchi prima, il pannello ti dice quanti secondi aspettare.
- Le righe con origine Sales non si modificano né si cancellano da qui: il pannello lo rifiuta e ti porta al pannello di licenses, dove vanno cambiate.
- Le righe Locali (create qui prima dell'anagrafica centrale) restano e sono segnate «da riconciliare»: si possono ancora modificare.
- Quando in Sales un cliente indica lo slug di un ambiente Legal che esiste, qui compare una proposta di collegamento. Il collegamento non è mai automatico: lo confermi tu, e se nel frattempo la proposta non vale più il pannello ti chiede di ricaricare la pagina.
Scheda cliente
- Nome, email di contatto, email di fatturazione, telefono.
- Partita IVA, indirizzo, note, stato.
- Collegamento di uno o più ambienti al cliente.
È questo legame che fa funzionare il passaggio fra prodotti: uno studio con Case Manager e Legal Drafter salta dall'uno all'altro perché i due ambienti sono collegati allo stesso cliente.
Eliminare un cliente locale
- Soft — lo marca come cancellato e stacca gli ambienti, che restano attivi.
- Hard — elimina il record dal database.
- With envs — elimina il cliente e i suoi ambienti.
◎ Utenti admin
Chi può entrare in questo pannello. Da non confondere con gli utenti dei tenant, che si gestiscono dal backoffice di ciascun ambiente.
- Creazione ed eliminazione degli account del pannello: hanno tutti lo stesso ruolo, superadmin.
- Ognuno cambia la propria password, attiva la verifica in due passaggi (TOTP) e chiude le proprie sessioni dal Profilo.
- Ogni azione resta nel log attività col nome di chi l'ha fatta.
◈ Statistiche & utilizzo
Due sezioni diverse: Statistiche guarda la piattaforma, Utilizzo guarda quanto costa.
Utilizzo
- Costo misurato, non stimato: viene dal registro dei consumi di twiza-licenses — token REALI riportati dal motore × listino DigitalOcean. È per mese di calendario, non per il periodo scelto qui: i due numeri stanno fianco a fianco e ognuno porta la sua etichetta.
- Talent consumati per ambiente: quello che il cliente ha speso del piano che ha comprato.
- Sessioni, documenti e spazio per ambiente: sono conteggi, e servono da controprova — se divergono molto dalla misura, c'è consumo che non passa dal gateway, e quello che non si misura non si fattura.
- «n/d» non è zero: zero vuol dire «non ha consumato», n/d vuol dire che non lo sappiamo.
Indicizzazione
Il riquadro Indicizzazione KB · tempi mostra le medie a 30 giorni misurate
davvero (tabella kb_indexing_runs), non una stima: è quello che permette al
backoffice del tenant di dire «attesa stimata» con un numero che ha un senso.
◉ Monitoraggio & coda job
Lo stato dei servizi da cui la piattaforma dipende, e la coda delle operazioni lunghe.
- Monitoraggio — health check live di database, DigitalOcean, Spaces, licenze ed email.
- Job — la coda del provisioning: ogni step di ogni ambiente, con esito ed errore. È il primo posto da guardare quando un ambiente resta «in creazione».
≡ Attività & notifiche
- Log attività — chi ha fatto cosa e quando, con export CSV. È la traccia di audit del pannello.
- Notifiche — gli avvisi interni della piattaforma.
⚙ Configurazione & sicurezza
Le credenziali dei servizi e i parametri della piattaforma.
- Chiavi di DigitalOcean, Spaces, licenze ed email, con test live della connessione.
- I valori riservati sono cifrati at-rest nel database. Il pannello non li rimostra in chiaro dopo il salvataggio.
- Il controllo di stato segnala se un valore riservato risulta scritto in chiaro e lo ripara da solo.
◷ Profilo
Il tuo account: dati, cambio password, verifica in due passaggi (TOTP) e sessioni attive, che puoi chiudere tutte insieme.
🧠 RAG & Knowledge Base
Come fa l'assistente a rispondere sui documenti del cliente — e perché il controllo ce l'abbiamo noi.
Le KB dei tenant sono staccate dall'agente. Il retrieval lo facciamo noi, filtrato per pratica, e i frammenti trovati vengono iniettati nel prompt. L'agente è un puro modello che ragiona sul contesto che gli diamo.
Le scansioni e le immagini vengono lette con OCR dal servizio condiviso della suite, e il testo estratto finisce accanto al documento perché la KB lo indicizzi.
🚀 Deploy
Il rilascio non passa da questo pannello.
Il codice della piattaforma si rilascia dalla pipeline, e gli ambienti sono due:
- Sviluppo (DEV) — il merge sul branch di default aggiorna DEV, subito e da solo.
- Produzione (PROD) — si aggiorna solo con una promozione: una versione già provata in DEV passa sul ramo di produzione e viene consegnata dal repository gemello di produzione. Nessun merge in DEV arriva in PROD da solo.
In entrambi i casi non c'è niente da fare a mano sul server. Il numero di versione
servito si legge dalla risposta di ping.
Quello che invece si fa da qui è il redeploy del template sugli ambienti esistenti, quando una release cambia il sito dei tenant: prima di copiare i file, allinea anche spazio e utenti al registro licenze.
Il database di un nuovo tenant si crea con cPanel sia in DEV sia in PROD.
process_jobs