| 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://commdev.shakazamba.space/twiza-admin/admin-api.php?action=cron_calendar_notifications"
🧭 Panoramica prodotto
TWIZA Communication è la piattaforma multi-tenant per le agenzie di comunicazione: assistenza AI ancorata ai documenti della campagna, message house e comunicati, scrittura assistita e contenuti social. Da questo pannello si crea e si governa il ciclo di vita di ogni ambiente cliente.
Tre pezzi lavorano insieme:
- twiza-communication-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.
Qui le tipologie sono quattro: Comms Desk
(cd), Media & PR Counsel (mp),
Copydesk (co) e Media Lab
(ml). L'agenzia che ne ha più d'uno passa dall'uno all'altro dal
selettore in alto, senza rifare il login — ma solo se gli ambienti sono
legati allo stesso cliente: è quello che fa il campo
Cliente del form di creazione.
⊞ 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 —
cd,mp,cooml: decide quale interfaccia vede il cliente. - Cliente — opzionale, ma è quello che rende sibling i prodotti dello stesso cliente e fa funzionare lo switcher fra prodotti. Si può collegare anche dopo, dalla scheda cliente.
- Piano (tier) — 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 campagne 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. Valgono per gli ambienti creati da quel momento.
Il provisioning passo per passo (14 step)
Alla creazione la piattaforma esegue in sequenza, e ogni passo lascia traccia nella coda job:
config_minima— controlla che la configurazione minima del pannello sia completa; se manca qualcosa il provisioning si ferma prima di creare risorse.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 l'indicizzazione notturna. Può risultare skipped: lo scheduling a livello di KB non è sempre disponibile via API DigitalOcean, e in quel caso il reindex resta in carico alla coda. Non è un errore.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 misura dei consumi (metering) verso twiza-licenses, salvo che in Configurazione sia stata spenta di proposito.deploy_files— carica il template del sito.init_db— inizializza il database del tenant.send_welcome— manda la welcome email con le credenziali.send_access— manda all'admin del tenant un collegamento valido una volta sola con cui sceglie la propria password. Non bloccante: se non parte, l'esito resta nel registro del provisioning e il collegamento si rimanda con la rottatenant_invia_accesso.
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. 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 eventuali KB dall'agente e programma l'indicizzazione notturna. Vedi RAG & Knowledge Base. Solo se attivo e se l'ambiente ha sia KB sia agente.
- 📝 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 dei clienti è una sola per tutta la suite e vive in twiza-licenses (TWIZA Sales). Questo pannello la legge e non la duplica.
Da dove vengono le righe
- Origine «Sales» — clienti letti dall'anagrafica centrale (
GET /customers/feed). Non si modificano né si cancellano da qui: il server risponde 409 e il bottone Apri in Sales ↗ porta al pannello licenze, dove si correggono. - Origine «da riconciliare» — righe locali create in questo pannello prima dell'anagrafica centrale. Restano modificabili, ma vanno ricondotte al cliente di Sales: la fonte è Sales, non il pannello.
La sincronizzazione
- ⇣ Sincronizza ora legge subito l'anagrafica centrale: aggiunge i clienti nuovi e aggiorna quelli già letti. Al massimo un giro ogni 30 secondi: se premi troppo presto il pannello dice quanti secondi attendere.
- Lo stesso giro parte da solo ogni 10 minuti dal canale della pipeline, in sviluppo e in produzione.
- La sincronizzazione non cancella mai niente e non tocca le righe locali.
- In cima alla pagina trovi l'ora (UTC) e l'esito dell'ultimo giro.
Collegare un cliente ai suoi ambienti
Quando l'anagrafica di Sales dice che un cliente ha un ambiente Communication con un certo indirizzo, e qui esiste un ambiente con quello slug, il pannello propone il collegamento nel riquadro Collegamenti proposti da Sales. Nessun collegamento si applica da solo: premi Conferma, e il server ricontrolla che la proposta sia ancora valida prima di scrivere (se nel frattempo è cambiata, ti chiede di ricaricare la pagina).
È questo legame che fa funzionare il passaggio fra prodotti: gli ambienti collegati allo stesso cliente si raggiungono dal selettore in alto senza rifare il login. Un ambiente si collega a mano anche dal campo Cliente del form di creazione o da ✎ Modifica nel dettaglio dell'ambiente.
Eliminare un cliente locale
- Soft — lo marca come cancellato e stacca gli ambienti, che restano attivi.
- Hard — elimina il record dal database (solo per un cliente già cancellato).
- 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, modifica e disattivazione degli account superadmin.
- Ruoli e permessi del pannello.
- Autenticazione a due fattori (TOTP) per il proprio account, dal Profilo.
- Reset della password.
◈ 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, email e OCR, con test live della connessione dove previsto.
- I valori riservati sono cifrati at-rest nel database. Il pannello non li rimostra in chiaro dopo il salvataggio: quello che vedi è mascherato, e risalvarlo mascherato non sovrascrive niente.
- 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 e sessioni attive.
🧠 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 campagna, 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, e gli ambienti sono due.
- Sviluppo (DEV) —
commdev.shakazamba.space. Il merge sul branch di defaultmasterconsegna da solo e subito, dalla pipeline: copia del pannello e del template, ridistribuzione del template sui tenant esistenti (con l'allineamento dei limiti del piano) e controlli dopo la consegna. - Produzione (PROD) —
communication.twiza.ai. Si promuove con un passaggio separato e controllato: il ramorelease/prod, un tag di promozione e il repository specchio di produzione, dentro una finestra autorizzata. Un merge sumasternon arriva in produzione.
Non esiste nessuna label da mettere e non c'è niente da fare a mano sul server. La versione servita si legge
da admin-api.php?action=ping (campo version, e env dice in quale ambiente sei).
Quello che invece si può fare da qui è il redeploy del template su un ambiente esistente, quando una release cambia il sito dei tenant.
process_jobs