Il Manuale Operativo di TutorLab
Una guida completa per trasformare WordPress in un laboratorio di apprendimento pratico. Dalle configurazioni tecniche alle strategie di gamification e automazione con AI.
Ecosistema TutorLab
TutorLab non è un semplice LMS passivo. È un framework attivo progettato per il "Learning by Doing". Ecco i quattro motori che alimentano la piattaforma.
Laboratorio Pratico & Simulatori
Il cuore del sistema. Esercizi multi-step, campi strutturati e Simulatori Realistici (AdSet, Creative, ROAS) che replicano le interfacce delle vere piattaforme pubblicitarie.
Gamification Engine
Motiva gli studenti con un sistema XP calcolato in background, 5 livelli di progressione (da Novizio a Maestro), Badge sbloccabili e Classifiche in tempo reale.
AI & Feedback
Strumenti per il docente: Matrice Progressi ottimizzata, Note Private e l'innovativo AI Feedback Assistant per generare correzioni dettagliate in secondi.
Performance-First Architecture
Niente bloatware. TutorLab utilizza tabelle custom ottimizzate e una logica di caricamento dati che riduce 1200+ query potenziali a 1 singola query SQL per la matrice di classe. Include un sistema di pulizia DB automatico.
Requisiti & Installazione
TutorLab è costruito sopra l'architettura di dati di ACF Pro (versione 6.0+). Questo plugin deve essere installato e attivo per il funzionamento dei campi strutturati e dei simulatori.
Stack Tecnologico
- WordPress 6.0+
- PHP 7.4+ (Consigliato 8.1)
- MySQL 5.7+ / MariaDB 10.3+
- ACF Pro 6.0+
Quick Setup
- Carica la cartella
tutor-labin/wp-content/plugins/. - Attiva il plugin da backend.
- Le pagine Dashboard, Login, Profilo vengono create automaticamente.
- Vai su Tutor Lab > Impostazioni per la configurazione dei permessi e dei punteggi XP.
L'Esperienza Studente
Un ambiente immersivo e privo di distrazioni. Lo studente ha accesso a due interfacce principali: la Dashboard Operativa e l'Hub Personale.
Dashboard Esercitazioni
Il laboratorio pratico.
[tutor_lab_dashboard]
Visualizza tutti gli esercizi assegnati alla classe corrente, organizzati per fasi (Analisi, Strategia, Operatività). Include indicatori visivi di stato e barre di progresso.
Hub Centrale
Il centro di comando.
[tutor_lab_hub]
Aggrega dati eterogenei caricandoli in modo asincrono (AJAX) per garantire un caricamento pagina istantaneo. Include 4 widget principali:
Lezioni & Documenti
Accesso organizzato ai materiali didattici con tracking automatico delle visualizzazioni e ricompense XP.
[tutor_lab_lessons]
Lezioni Teoriche
Elenco delle lezioni assegnate alla tua classe con contenuti ricchi (testo, immagini, video embed).
- Editor Visivo: Contenuti formattati con WYSIWYG
- Tracciamento: +10 XP alla prima visualizzazione
- Badge "Visualizzato": Indica quali lezioni hai già letto
[tutor_lab_documents]
Libreria Documenti
Materiali scaricabili: PDF, dispense, template, checklist operative.
- Download Diretto: File allegati pronti da scaricare
- Tracciamento: +5 XP alla prima visualizzazione
- Organizzazione: Filtrabili per tipologia/argomento
Architettura Gamification
Il sistema di engagement è completamente automatizzato. Gli XP vengono assegnati tramite hook PHP in background. Ecco la logica di attribuzione predefinita nel codice (modificabile via filtri).
| Azione Trigger | Valore XP | Dettagli Tecnici |
|---|---|---|
| Iscrizione Newsletter | +150 XP | Trigger una tantum. Verifica campo _newsletter_xp_awarded. |
| Completamento Sondaggio/Test | +150 XP | Assegnati all'invio. (+50 XP extra per test al 100%). |
| Invio Esercizio | +50 XP | Assegnati al cambio status in "Completato". |
| Primo Salvataggio (Bozza) | +10 XP | Incentiva l'inizio del lavoro (anti-procrastinazione). |
| Lettura Lezione/Documento | +5/10 XP | Tracciato al click o al download risorsa. |
Progressione Livelli
Badge & Premi Riscattabili
Sistema Badge
Riconoscimenti visivi che si sbloccano automaticamente al raggiungimento di obiettivi specifici:
- Primo Login: Badge benvenuto
- Esercizi Completati: Trigger a 5, 10, 20 esercizi
- Custom: Il docente crea trigger personalizzati
Premi Riscattabili
Ricompense tangibili acquistabili con gli XP accumulati:
- File: Template, checklist, guide bonus
- Link: Accesso a contenuti premium
- Coupon: Codici sconto prodotti/servizi
Ogni premio può essere riscattato una sola volta per studente. Il sistema traccia automaticamente i riscatti con meta
_tutor_lab_redeemed_rewards per prevenire duplicazioni.
Classifica di Classe
[tutor_lab_class_leaderboard]
Ranking in tempo reale degli studenti della classe basato sugli XP accumulati. Promuove competizione sana e visibilità dei progressi.
Elementi Visualizzati:
Messaggistica Privata & Inbox
Un canale sicuro e diretto tra studente e docente. Elimina la confusione delle email e mantiene tutte le conversazioni organizzate per thread all'interno della piattaforma.
- Thread Context-Aware: Il docente vede da quale esercizio è partita la domanda.
- Privacy Totale: Nessun altro studente può leggere le conversazioni.
- Notifiche Real-time: Badge numerico sull'icona Inbox nell'Hub.
L'Area Docente
Strumenti di amministrazione progettati per la scalabilità. Gestisci classi numerose con performance ottimizzate e workflow rapidi.
Gestione Classi & Iscrizioni
Crea classi illimitate, imposta date di inizio/fine corso e controlla le impostazioni di visibilità.
- Lock Temporale: Accesso limitato per data.
- Toggle Moduli: Attiva/disattiva Gamification o Chat per classe.
- Iscrizione: Assegna studenti manualmente o tramite codice.
Workflow Approvazioni
Gli studenti si registrano come "Pending". Il docente ha una dashboard dedicata per approvare l'ingresso e assegnare la classe con un click.
Matrice Progressi
Ottimizzazione: 1 Query SQLA differenza dei plugin LMS classici che eseguono centinaia di query, TutorLab utilizza una query SQL custom con JOIN ottimizzati. Questo permette di caricare lo stato di 50+ studenti in frazioni di secondo.
| Studente | Es. 1: Analisi | Es. 2: AdSet Sim | Es. 3: Creative | Es. 4: ROAS |
|---|---|---|---|---|
| Mario Rossi | Completato | Completato | Da Correggere | -- |
| Luca Bianchi | Completato | In Corso (40%) | -- | -- |
Sistema di Feedback Strutturato
Un workflow professionale per correggere le risposte degli studenti con feedback granulare (generale + per sezione) e modalità draft per salvare progressi senza notificare.
Feedback Generale
Commento complessivo sull'intero esercizio visibile allo studente in cima alla risposta.
Feedback per Sezione
Commenti specifici per ogni sezione/campo compilato dallo studente con editor ricco.
Modalità Bozza (Draft)
Salva il feedback come bozza senza renderlo visibile allo studente. Utile per correzioni multi-sessione.
_tutor_lab_has_feedback_draft = true
Pubblicazione Feedback
Click su "Pubblica Feedback" rende visibile il feedback, invia email notifica allo studente e registra timestamp.
Workflow Correzione
Strumenti "Power User"
AI Feedback Assistant
Genera correzioni dettagliate in secondi. TutorLab crea un Prompt JSON strutturato con i dati dello studente. Tu lo copi in ChatGPT/Claude, e il plugin re-importa la risposta dell'AI, popolando automaticamente i campi di feedback per ogni sezione.
Post-it Interni
Un'area di annotazione privata nella sidebar di correzione, invisibile allo studente. Utile per segnare progressi soft-skill o note per altri docenti.
Database Cleanup
Utility integrata che rileva e rimuove automaticamente i record duplicati nella tabella delle risposte, mantenendo solo l'ultima versione valida.
"Vedi come Studente"
Funzione di impersonificazione rapida integrata. Permette al docente di visualizzare l'esercizio esattamente come lo vede lo studente (bypassando i lock) per debug immediato.
Import & Export Contenuti
Import Esercizi JSON
Carica esercizi predefiniti o esportati da altre installazioni. Formato JSON strutturato.
Import Badge Predefiniti
Set di badge con trigger comuni: primo login, 5/10/20 esercizi completati. Import con un click.
Export Risposte PDF
Esporta le risposte di uno studente specifico in formato PDF professionale per archiviazione.
Report Finale Classe
Genera report completo con:
- Stati completamento per studente
- XP totali e livelli raggiunti
- Badge sbloccati e premi riscattati
- Statistiche aggregate della classe
Builder & Esercizi Interattivi
Crea le tue esercitazioni con facilità, senza una riga di codice. Il Builder visuale permette di strutturare percorsi complessi in modo intuitivo, dal semplice testo ai campi strutturati dinamici.
Visual Builder Drag & Drop
Un'interfaccia intuitiva (basata su Alpine.js) per costruire esercizi complessi. Trascina sezioni, personalizza i campi, imposta gli obiettivi didattici. Tutto in tempo reale.
- Sezioni multi-blocco riordinabili.
- Editor WYSIWYG per istruzioni dettagliate.
- Preview dinamica per verificare l'output studente.
Tipologie di Risposta
Ogni sezione può avere un formato di risposta specifico:
- Textarea: Per risposte aperte.
- Campi Strutturati: Per checklist o analisi guidate (es. SWOT).
- Solo Istruzioni: Blocchi puramente informativi.
- File Upload: Per allegare documenti o immagini.
I Simulatori "Real-World"
Questi moduli non sono semplici form, ma repliche fedeli delle interfacce delle piattaforme pubblicitarie (Meta Ads). Permettono agli studenti di fare pratica "in sicurezza" prima di spendere budget reale.
Ad Set Simulator
Replica la configurazione di un gruppo di inserzioni Meta, dal budget al targeting avanzato.
- Obiettivo: Traffico, Lead, Vendite.
- Targeting: Geografico (Select2), Demografico (Età, Sesso), Interessi dinamici.
- Posizionamenti: Manuali (Feed, Stories, Reels).
- Budget & Scheduling: Controllo completo.
Ad Creative Simulator
Crea l'annuncio vero e proprio, con un'anteprima live su mockup Facebook/Instagram.
- Mockup Live: Anteprima su FB/IG.
- Copywriting: Campi per "Cervello Rettile, Limbico, Neocorticale".
- Asset: Upload immagine creativa.
- CTA: Pulsanti dinamici.
ROAS Calculator
Modulo semplificato per calcolare il Return on Ad Spend e interpretarne i risultati.
- Input Personalizzati: Spesa e Ricavi definiti dal docente per ogni studente.
- Analisi Testuale: Campo per lo studente per descrivere calcoli e strategie.
Sondaggi & Test Valutativi
Un modulo flessibile per raccogliere feedback strutturati (Sondaggi) o verificare le conoscenze acquisite (Test con scoring automatico).
Due Modalità Operative
Ogni sondaggio/test può essere configurato per lo scopo specifico:
- Sondaggio: Raccoglie opinioni, mostra risultati aggregati.
- Test: Verifica conoscenze, punteggio automatico, XP bonus per 100%.
Tipologie di Domanda
- Scelta Singola: Radio button.
- Scelta Multipla: Checkbox.
- Risposta Aperta: Textarea per testo libero.
- Risposte Corrette: Marker per i test.
Sistema Lock & Unlock Esercizi
Gli esercizi possono essere configurati per essere sequenziali, richiedendo il completamento del precedente. Gli studenti possono richiedere lo sblocco anticipato che va approvato dal docente.
Stati Lock Esercizio
Esercizio bloccato e non accedibile. Richiede completamento precedente.
Richiesta sblocco inviata, in attesa approvazione docente.
Esercizio sbloccato e completamente accessibile.
Workflow Sblocco
- Studente clicca su "Richiedi Accesso Anticipato"
- Sistema registra timestamp in meta
_tutor_lab_unlock_requested - Docente riceve email notifica con link diretto alla risposta
- Docente approva/rifiuta dalla dashboard (cella evidenziata in giallo)
- Se approvato: stato →
ok, studente può accedere immediatamente - Se rifiutato: stato rimane
blocked
Sistema Email & Notifiche
TutorLab invia notifiche email automatiche per tutti gli eventi critici, mantenendo docenti e studenti sempre aggiornati.
Template Email Disponibili
| Template | Trigger | Destinatario |
|---|---|---|
admin-notification-start.php |
Studente inizia esercizio (primo salvataggio) | Docente |
admin-notification-completion.php |
Studente completa esercizio | Docente |
student-feedback-notification.php |
Feedback pubblicato dal docente | Studente |
unlock-request-admin.php |
Richiesta sblocco esercizio | Docente |
new-content-notification.php |
Nuova lezione/documento caricato (cron) | Studenti classe |
new-user-welcome.php |
Approvazione iscrizione studente | Studente |
TutorLab utilizza
wp_mail() nativo di WordPress. Per garantire deliverability delle email (evitando spam), configura un plugin SMTP professionale come WP Mail SMTP o Post SMTP.
Configurazione BCC
Tutte le email includono un BCC automatico definito nella costante:
Utile per tracciamento centralizzato di tutte le comunicazioni.
Architettura & Estensibilità
Dettagli sotto il cofano per integrazioni custom e debugging.
Struttura Database
Il plugin registra 10 Custom Post Type per separare logicamente i dati e mantenere pulita la tabella wp_posts.
- Public: esercizio, sondaggio
- Private: lezione, documento, badge, premio
- Internal: risposta_studente, risposta_sondaggio
- System: annuncio, messaggio_privato
Ruoli & Tassonomie
Gestione granulare degli accessi tramite tassonomia gerarchica.
classe
tutor_lab_student
tutor_lab_pending
Hooks & Filters
| Hook Name | Tipo | Descrizione |
|---|---|---|
tutor_lab_after_exercise_completion |
Action | Scatta quando un esercizio passa allo stato "Completato". Utile per integrazioni CRM. |
tutor_lab_badge_unlocked |
Action | Scatta all'assegnazione di un badge. Parametri: $user_id, $badge_id. |
tutor_lab_xp_for_action |
Filter | Permette di modificare la quantità di XP assegnati per ogni specifica azione. |
tutor_lab_exercise_lock_status |
Filter | Override della logica di blocco sequenziale degli esercizi. |
Performance & Ottimizzazioni
TutorLab è progettato per essere performante anche con classi di 100+ studenti. Ecco le ottimizzazioni implementate.
Query SQL Diretta
Dashboard matrice progressi: 1 query SQL con JOIN invece di 1200+ query individuali.
Lock Atomico MySQL
Previene race condition sul primo salvataggio esercizi con GET_LOCK() nativo MySQL.
Bulk Meta Loading
Caricamento meta in batch con update_meta_cache() per eliminare query N+1.
Transient Cache
Dati frequenti cachati con scadenza intelligente:
tl_progress_matrix_class_{id}→ 1 oratl_next_ex_{user_id}→ 5 minutitl_hub_gamification_{user_id}→ 15 min
La cache viene invalidata automaticamente solo quando necessario (al salvataggio esercizio, cambio stato, feedback pubblicato). Mai invalidazione globale inutile.
Sicurezza & Best Practices
Nonce Verification
Tutti gli endpoint AJAX verificano check_ajax_referer(). Form admin verificano nonce e capabilities.
Sanitizzazione Input
Input sanitizzati con funzioni native WP:
sanitize_text_field()sanitize_textarea_field()wp_kses_post()intval()per ID numerici
Capability Check
Verifica permessi utente con current_user_can() prima di ogni azione sensibile.
Prepared Statements
Tutte le query SQL custom utilizzano $wpdb->prepare() per prevenire SQL injection.
Meta Validation
Post meta registrate con sanitize_callback e validazione enum per stati:
Shortcode Reference
Copia e incolla questi shortcode nelle tue pagine WordPress (Gutenberg, Elementor, Divi) per renderizzare i componenti di TutorLab.
| Shortcode | Descrizione | Pagina Consigliata |
|---|---|---|
[tutor_lab_dashboard] |
Dashboard principale con elenco esercizi e filtri. | /dashboard-esercitazioni/ |
[tutor_lab_hub] |
Hub centrale studente (Gamification, Notifiche). | /dashboard-studente/ |
[tutor_lab_registration_choice] |
Wizard di onboarding (Scelta piano + Registrazione). | /registrati/ |
[tutor_lab_login_form] |
Form di login personalizzato. | /login/ |
[tutor_lab_profile] |
Gestione profilo utente e cambio password. | /profilo/ |
[tutor_lab_progress_hub] |
Pagina dettagliata gamification e premi. | /i-miei-progressi/ |
[tutor_lab_class_leaderboard] |
Classifica degli studenti della classe. | /classifica/ |
Domande Frequenti (FAQ)
Funziona con Elementor o Divi?
È necessario ACF Pro per farlo funzionare?
Come gestisco i rimborsi o i ritiri?
Le email partono dal mio server?
wp_mail() di WordPress. Per garantire che le notifiche di benvenuto e di feedback arrivino correttamente (evitando lo spam), consigliamo vivamente di configurare un plugin SMTP (come WP Mail SMTP).
Come funziona il sistema Lock/Unlock degli esercizi?
_tutor_lab_unlock_requested e _tutor_lab_unlock_approved_by.
Posso creare badge personalizzati?
Il Builder Esercizi supporta quiz a scelta multipla?
Come importo esercizi da un altro sito TutorLab?
.json esportato dal sito di origine e premi "Carica & Importa". Il sistema creerà automaticamente i post type esercizio con tutte le ACF meta (sezioni, template, icona, fase). Attenzione: gli ID post cambieranno, quindi eventuali relazioni (es. classi assegnate) vanno ricostruite manualmente.
Posso dare feedback solo su alcune sezioni dell'esercizio?
La classifica è pubblica o privata?
classe). La visualizzazione include: podio top 3, lista completa con livello attuale e posizione. Utilizza lo shortcode [tutor_lab_class_leaderboard] per renderizzarla.
Quali ottimizzazioni di performance sono implementate?
Come esporto i PDF dei certificati finali?
/tmp e partono via email BCC a academy@promologica.it.
TutorLab è conforme al GDPR?
Posso personalizzare i template email?
/templates/emails/ (es. new-user-welcome.php, student-feedback-notification.php). Puoi editare HTML, stili inline e variabili dinamiche (es. $student_name, $exercise_title). Per personalizzazioni avanzate, considera l'uso di hook WordPress come wp_mail o plugin SMTP con template builder.
Quanti studenti supporta la piattaforma?
I simulatori (Ad Set, Ad Creative, ROAS) funzionano con il Builder?
Come disattivo il plugin senza perdere i dati?
studente_tutor_lab, pending_tutor_lab) ma mantiene tutti i dati (CPT, utenti, meta, taxonomy). Se vuoi eliminare completamente i dati, vai su Tutor Lab → Impostazioni, abilita "Elimina dati alla disinstallazione", poi disinstalla il plugin dal menu "Plugin" di WordPress. Lo script uninstall.php rimuoverà tutti i post type, term, meta e opzioni.
Contatta il Supporto
Hai domande tecniche o commerciali? Scrivici.
Errore: Modulo di contatto non trovato.
