TutorLab — Knowledge Base Completa
Documentazione Ufficiale v2.1.0 Updated: Feb 2026

TutorLab
Knowledge Base

Guida completa al plugin WordPress LMS di nuova generazione. Copre ogni modulo: dalla gerarchia dei corsi all'AI Suite con RAG, dal Builder drag-and-drop all'engine di gamification con XP e badge.

19
Blocchi Builder
13+
Shortcodes
80+
Azioni AJAX
18
Classi AI
11
Post Type
XP+
Gamification

Indice Rapido

AI Suite & RAG Engine Builder Esercizi v2 Gerarchia Corsi Gamification XP Shortcodes Reference Simulatori Ads Sistema Feedback Template Email Export PDF Sistema Licenze AJAX Reference FAQ

Quick Start in 5 Passi

Parti subito con TutorLab. Segui questi cinque passi per avere il tuo corso online e attivo.

  1. Attiva la Licenza

    Vai su Tutor Lab → Impostazioni → Licenza, inserisci la chiave ricevuta via email e clicca "Attiva". Il sistema verifica la licenza online e abilita i moduli inclusi nel tuo piano.

  2. Crea la struttura del corso

    Vai su Gestione Classi, crea un Corso (container principale) e poi una o più Classi (edizioni temporali). Assegna esercizi, lezioni e documenti alla classe.

  3. Aggiungi studenti

    Vai su Sistema → Importa Studenti per import CSV massivo, oppure approva le registrazioni dalla pagina Approvazioni. Assegna ogni studente a Corso → Classe → (Gruppo opzionale).

  4. Crea gli esercizi col Builder

    Vai su Contenuti → Builder Esercizi. Inserisci titolo e icona, trascina i blocchi dalla palette nella canvas, configura ciascuno e clicca "Pubblica".

  5. Monitora i progressi

    Dalla Dashboard Docente e dalla Matrice Progressi visualizza in tempo reale lo stato di ogni studente per ogni esercizio.

Requisiti & Licenza

Requisiti WordPress

  • WordPress 6.0+
  • PHP 8.0+
  • MySQL 5.7+ / MariaDB 10.3+
  • ACF PRO 6.0+ (obbligatorio)
  • TCPDF (incluso in /lib/tcpdf/)

Requisiti AI Suite

  • Chiave API OpenAI valida
  • Addon AI attivo nella licenza
  • PHP cURL abilitato
  • Connessione HTTPS attiva

Addons Disponibili

  • ai_coach — AI Coach studente
  • gamification_advanced — XP & badge avanzati
  • pdf_export — Export PDF esercizi
  • email_automation — Email template
  • advanced_reports — Analytics avanzate
  • multi_team — Team multipli
  • sso — Single Sign-On

TutorLab AI Suite

Un sistema AI verticale e contestuale che potenzia l'apprendimento senza mai "inventare" informazioni. Basato su RAG (Retrieval-Augmented Generation), risponde solo sui contenuti del corso.

Modulo Premium. L'AI Suite è attiva solo se l'addon ai_coach è incluso nella licenza e la chiave API OpenAI è configurata in AI → Configurazione AI.

RAG Engine — Zero Allucinazioni

A differenza dei chatbot generici, TutorLab utilizza il paradigma RAG: prima recupera i chunk rilevanti dalla Knowledge Base, poi li inietta nel prompt come contesto. Se la risposta non è nei documenti caricati, l'AI lo dice esplicitamente e suggerisce di contattare il docente umano.

Coaching Adattivo

Il tono e la complessità della risposta si adattano automaticamente al profilo dello studente (Novizio → incoraggiante, Esperto → sfidante, In Difficoltà → supportivo).

Sistema Crediti

Ogni chiamata AI consuma crediti. Il docente assegna crediti per utente o classe. Include piani in abbonamento e pacchetti one-shot con PayPal e Stripe.

Analytics AI

Dashboard con: chiamate API totali, token consumati, costi stimati, utilizzo per studente, per corso e per tipo di operazione. Export CSV disponibile.

AI Coach (Frontend Studente)

Widget di chat integrato nel frontend. Lo studente può fare domande sul corso; l'AI risponde basandosi esclusivamente sulla Knowledge Base del docente.

[tutor_lab_ai_coach]
oppure: [tutorlab_ai_coach corso="Nome Corso" modulo="Nome Modulo" show_history="yes"]

Funzionalità

  • Risposte contestuali: solo argomenti del corso
  • Storico chat: persistente tra sessioni
  • Feedback immediato: voto Utile/Non Utile
  • Fallback intelligente: se non trova risposta, rimanda al docente
  • Rate limiting: prevenzione abusi configurabile

Azioni AJAX

  • tutor_lab_ai_coach_send — invia messaggio
  • tutor_lab_ai_coach_history — recupera storico
  • tutor_lab_ai_coach_clear — cancella storico
  • tutor_lab_ai_coach_ask — query diretta

Coaching Adattivo per Profilo

Profilo StudenteTono AIEsempio risposta a "Cos'è il ROAS?"
Novizio
Pochi XP, primi accessi		Incoraggiante"Ottima domanda! Il ROAS è il ritorno sulla spesa pubblicitaria. Se spendi 1€ e guadagni 4€, il ROAS è 4. Continua così!"
Esperto
Livello Maestro		Sfidante"ROAS = Revenue / Ad Spend. Attenzione: un ROAS alto non significa profitto se i margini sono bassi. Hai considerato l'impatto del CAC?"
In Difficoltà
Molti errori recenti		Supportivo"Capisco la confusione. Facciamo un passo indietro con un esempio pratico. Non preoccuparti, ci arriveremo insieme."

RAG Engine & Knowledge Base

Il motore di ricerca semantica che alimenta le risposte dell'AI Coach. Gestione da AI → Knowledge Base nel backend.

1. Upload KB

Carica testi, FAQ, trascrizioni lezioni, PDF convertiti in testo. Ogni item ha: titolo, contenuto, tipo, corso/modulo associato.

2. Chunking

La classe TutorLab_KB_Chunker spezza i testi lunghi in chunk semantici con sovrapposizione configurabile. Ottimizzati per embedding.

3. Vettorializzazione

I chunk vengono trasformati in vettori numerici via OpenAI Embeddings API. Permette ricerca per "concetto" e non solo per parola chiave.

Azioni AJAX Knowledge Base

Azione AJAXDescrizione
tutor_lab_kb_deleteElimina un item dalla KB
tutor_lab_kb_searchRicerca semantica nella KB
tutor_lab_kb_reindexRicalcola embedding per un item
tutor_lab_kb_preview_chunksAnteprima chunking di un testo
tutor_lab_kb_get_statsStatistiche KB (count, coverage)
tutor_lab_kb_bulk_actionOperazioni bulk (reindex, delete)
tutor_lab_ai_batch_embed_kbBatch embedding dell'intera KB

AI Feedback Generator (Docente)

Quando correggi un esercizio, clicca "Genera Feedback AI". Il sistema legge la risposta dello studente e genera una bozza di correzione contestualizzata.

Payload inviato all'AI

{
  "role": "teacher",
  "student_level": "beginner",
  "exercise_context": "Analisi SWOT",
  "student_answer": "...",
  "ideal_solution": "...",
  "tone": "formale"
}

La risposta generata viene inserita come bozza nel campo "Feedback Generale" — il docente può modificarla prima di pubblicarla. Azione AJAX: tutor_lab_ai_enhance_feedback

Sistema Crediti AI

Database Crediti

Tabelle: wp_tutor_lab_ai_credits (saldo utente) e wp_tutor_lab_ai_transactions (libro mastro). Ogni operazione è tracciata.

Piani Abbonamento

Piani mensili/annuali con crediti automatici (Starter, Professional, Enterprise). Rinnovo automatico via cron WP.

Pacchetti One-Shot

Acquisto una-tantum di bundle crediti a volume fisso. Sconti volume configurabili. Integrazione PayPal e Stripe.

Notifiche Soglia

Email automatica quando i crediti scendono sotto la soglia configurata. Avviso dashboard dismissibile via AJAX.

Pagamenti AI

PayPal Integration

Gestito dalla classe TutorLab_PayPal_Handler.

  • tutor_lab_paypal_create_order
  • tutor_lab_paypal_capture_order

Stripe Integration

Gestito dalla classe TutorLab_Stripe_Handler. Checkout Session sicuro.

  • tutor_lab_stripe_create_checkout

Gerarchia Didattica

Struttura a 4 livelli per gestire organizzazioni complesse con più corsi, classi e gruppi di lavoro paralleli.

1. Corso

Il container principale (es. "Marketing Digitale 2026"). Definisce il programma globale, i materiali e le impostazioni generali. Può avere più Classi contemporaneamente.

2. Classe

Edizione temporale del Corso (es. "Classe Febbraio 2026"). Ha date di inizio/fine specifiche, docenti assegnati, esercizi e configurazioni proprie.

3. Gruppo di Lavoro

Sotto-insieme dentro una Classe (es. "Team Alpha"). Utile per lavori di gruppo, tutoraggio specifico e progetti collaborativi differenziati.

4. Studente

L'utente finale. Può essere iscritto a più Corsi mantenendo progressi XP e badge separati per ciascuno.

La tassonomia classe è applicata a: esercizio, lezione, documento, annuncio, tutor_class_email, sondaggio. Ogni contenuto è sempre associato a una o più classi.

Gestione Classi

Lock Temporale

Imposta date di inizio e fine corso. Gli studenti non possono accedere ai materiali fuori da questa finestra. Meta term: _tutor_lab_start_date, _tutor_lab_end_date.

Toggle Moduli per Classe

Attiva/disattiva per classe specifica: Gamification (_tutor_lab_gamification_enabled), Messaggistica (_tutor_lab_messaging_enabled), Review Banner (_tutor_lab_review_banner_enabled).

Workflow Approvazioni

Gli studenti si registrano come "Pending". Dashboard dedicata per approvare l'ingresso e assegnare Corso → Classe → Gruppo in un'unica operazione.

Matrice Progressi

Vista a griglia: righe = studenti, colonne = esercizi, cella = stato (completato, in corso, non iniziato, in revisione). Carica 50×50 in <200ms.

Azioni AJAX Gestione Classi

AzioneDescrizione
tutor_lab_hierarchy_actionOperazioni gerarchia (crea, modifica, elimina nodi)
tutor_lab_add_students_to_classIscrizione studenti a una classe
tutor_lab_remove_student_from_classRimozione iscrizione
tutor_lab_update_class_exercisesAggiorna esercizi assegnati alla classe
tutor_lab_refresh_matrix_dataAggiorna la matrice progressi
tutor_lab_save_student_internal_noteSalva nota interna admin sullo studente

Ruoli & Permessi Staff

RuoloLivelloResponsabilitàAmbito (Scope)
Super AdminLv.100Accesso totale, gestione plugin, settings globali, billing e licenze.Globale
CoordinatoreLv.80Crea classi, gestisce iscrizioni, assegna Tutor, vede report globali.Per Corso
TutorLv.60Monitora progressi, sblocca esercizi, gestisce gruppi specifici.Per Classe
DocenteLv.40Valuta esercizi, invia feedback, crea contenuti didattici.Per Classe
StudenteLv.10Accede ai propri materiali, esegue esercizi, legge feedback.Propria Classe

Team & Staff

Gestisci collaboratori dalla pagina Gestione → Team & Staff. Ogni membro ha un ruolo specifico con scope limitato alla propria area di responsabilità.

L'addon multi_team nella licenza è richiesto per gestire team multipli su più corsi contemporaneamente. Senza di esso, è disponibile solo la gestione base utente WordPress.

Builder Esercizi

Editor visuale drag & drop per creare esercitazioni interattive senza scrivere codice. Accedi da Contenuti → Builder Esercizi.

Addon Richiesto. Il Builder avanzato richiede l'addon api_access nella licenza. La pagina è gestita da /admin/builder-page.php. Il salvataggio avviene via AJAX: tutor_lab_save_builder_exercise.

Drag & Drop

Trascina blocchi dalla palette a sinistra nella canvas centrale. Riordina trascinando la maniglia. Basato su Alpine.js.

Autosave

Salvataggio automatico ogni 30 secondi. Shortcut Ctrl+S / Cmd+S. Indicatore di stato in tempo reale (Salvato / Modifiche non salvate / Salvataggio in corso).

Template Esercizio

Campo ACF exercise_template: scegli tra default (builder libero), ad-set-simulator, ad-creative-simulator, roas-simulator.

Struttura Dati Esercizio (JSON)

{
  "title": "Analisi SWOT",
  "slug": "analisi-swot",
  "fase": "analisi",          // analisi | creazione | acquisizione | gestione | misurazione
  "icon": "🎯",
  "level": "apprendista",     // apprendista | praticante | specialista | maestro
  "visible": true,
  "description": "...",
  "sections": [
    {
      "id": "uuid-v4",
      "type": "textarea",     // vedi lista blocchi
      "title": "Strengths",
      "icon": "��",
      "objective": "Descrivi i punti di forza",
      "layout": "1-col",      // 1-col | 2-col | 3-col | 2-1 | 1-2
      "placeholder": "Inserisci qui..."
    }
  ]
}

Blocchi del Builder (19 tipi)

Testo & Input

Textarea
Fields (Campi Strutturati)
Instructions (Istruzioni)
Quote (Citazione)
Code (Codice)

Media

Image (Immagine)
Video Embed
File Upload

Interattivi

Checklist
Accordion
Tabs / Schede NEW
Lista NEW
Timeline NEW
Tabella

Evidenziazione

Alert
Callout
Progress Bar

Layout

Row / Colonne
Divider (Separatore)
Blocchi speciali: File Upload salva i file in una directory protetta di WordPress. Tabs usa il formato titolo|contenuto separati da ---. Timeline usa il formato data|titolo|descrizione (una riga per evento).

Simulatori Ads

Moduli specializzati che replicano le interfacce delle piattaforme pubblicitarie (Meta Ads). Pratica sicura senza budget reale. Template selezionato via campo ACF exercise_template.

SimulatoreTemplate SlugFile PHPCampi Principali
Ad Set Simulatorad-set-simulatortemplate-ad-set.phpObiettivo, Budget (tipo+importo), Date, Luoghi, Età, Genere, Posizionamenti, Interessi, KPI, Messaggio chiave, Giustificazione pubblico
Ad Creative Simulatorad-creative-simulatortemplate-ad-creative-simulator.phpHook (gancio), Body (3 cervelli), Headline, CTA button, Creatività (immagine upload)
ROAS Calculatorroas-simulatortemplate-roas-simulator.phpTesto istruzioni (WYSIWYG), Calcolo e analisi ROAS (textarea libera)
Le risposte degli studenti ai simulatori sono salvate nel CPT risposta_studente con meta key specifici (es. adset_objective, hook, risposta_roas_calculation). I dati vengono inclusi nell'export PDF.

Sistema Feedback Docente

Workflow professionale per correggere gli esercizi. Supporta correzioni per sezione, feedback generale, modalità bozza e pubblicazione con notifica automatica.

Feedback Generale

Commento "macro" sull'intero elaborato. Salvato in _draft_feedback_generale_docente. Notifica via email quando pubblicato.

Feedback per Sezione

Punteggio (0–5) e commento per ogni sezione/campo. Meta: _draft_feedback_punteggi_docente (array) e _draft_feedback_sezioni_docente.

Modalità Bozza

Salva senza notificare. Meta: _tutor_lab_has_feedback_draft e _draft_last_saved_timestamp. Pubblica quando pronto con tutor_lab_publish_feedback_ajax.

Meta Keys Feedback

Meta KeyTipoDescrizione
_draft_feedback_generale_docenteString (HTML)Feedback generale bozza
_draft_feedback_sezioni_docenteArray serializzatoFeedback testo per sezione [key][feedback_text]
_draft_feedback_punteggi_docenteArray serializzatoPunteggi (0-5) per sezione [key] => int
_draft_average_scoreIntMedia calcolata dei punteggi sezione
_feedback_generale_docenteString (HTML)Feedback pubblicato (visibile allo studente)
_tutor_lab_has_feedback_draftFlag ('1')Indica bozza attiva
_draft_last_saved_timestampInt (Unix)Timestamp ultimo salvataggio bozza
_feedback_field_sourcesArray serializzatoSorgente modifica: manual | ai, con timestamp
_internal_postitStringNota interna docente (non visibile allo studente)

Export PDF

Genera PDF professionali delle risposte degli studenti. Libreria TCPDF (DejaVuSans, UTF-8 completo). File: /includes/pdf-exporter.php. Richiede addon pdf_export.

PDF Singolo Esercizio

Action URL: ?tutor_lab_action=export_student_answers_pdf&student_id=X&exercise_id=Y&_wpnonce=...

Include: intestazione, badge classe, dati studente, tutte le sezioni con risposte, feedback docente (opzionale).

PDF Tutti gli Esercizi (Aggregato)

Action: export_student_aggregate_pdf. Genera un PDF multi-pagina con cover, indice e tutte le risposte dello studente.

PDF Report Classe Finale

Generato da Genera Report Finale. Include tabella valutazioni per studente con punteggi (0-5) e note generali. Funzione: tutor_lab_generate_class_report_pdf().

Sistema Email

Template configurabili dal backend senza modificare PHP. Impostazioni in Sistema → Impostazioni → Email. File: /includes/email-handler.php.

TemplateFileDestinatarioVariabili Principali
Benvenuto nuovo utentenew-user-welcome.phpStudente{{USER_NAME}}, {{SITE_NAME}}, {{LOGIN_URL}}
Notifica admin genericaadmin-notification.phpAdminCustomizzabili
Studente ha iniziato esercizioadmin-notification-start.phpAdmin{{STUDENT_NAME}}, {{EXERCISE_TITLE}}, {{ADMIN_URL}}
Studente ha completato esercizioadmin-notification-completion.phpAdmin{{STUDENT_NAME}}, {{EXERCISE_TITLE}}
Nuovo contenuto pubblicatonew-content-notification.phpStudenti classe{{USER_NAME}}, {{CONTENT_TITLE}}, {{CONTENT_URL}}
Feedback pubblicato (singolo)student-feedback-notification.phpStudente{{USER_NAME}}, {{EXERCISE_TITLE}}, {{FEEDBACK_LINK}}
Feedback bulkstudent-feedback-bulk-notification.phpStudenti{{FEEDBACK_COUNT}}, {{EXERCISE_LIST}}
Richiesta sblocco eserciziounlock-request-admin.phpAdmin{{STUDENT_NAME}}, {{EXERCISE_TITLE}}, {{ADMIN_URL}}
Tutte le email vengono loggate nella tabella wp_tutor_lab_email_log con timestamp, destinatario, oggetto e stato (inviata/fallita). Supporto SMTP configurabile. Azione: tutor_lab_resend_notification_email per reinvio manuale.

Messaggistica Interna

Sistema di messaggistica privata tra studenti e docenti/admin. CPT: messaggio_privato. Abilitabile per classe: _tutor_lab_messaging_enabled.

Lato Studente

  • tutor_lab_get_conversations_student
  • tutor_lab_get_messages_for_thread_student
  • tutor_lab_send_reply_student
  • tutor_lab_compose_message_student
  • tutor_lab_get_valid_recipients_student

Lato Admin

  • tutor_lab_get_conversations_admin
  • tutor_lab_get_messages_for_thread_admin
  • tutor_lab_send_reply_admin
  • tutor_lab_compose_message_admin

Annunci

CPT annuncio associato alla tassonomia classe. Pubblicando un annuncio con il campo notifica attivo, viene schedulato automaticamente un invio email a tutti gli studenti della classe (via WP-Cron con ritardo di 10 secondi). Gli annunci appaiono nella hub studente.

[tutor_lab_all_updates] — Feed annunci e aggiornamenti classe per lo studente loggato

Dashboard & Hub Studente

[tutor_lab_hub]

Hub Centrale (AJAX)

Centro di comando studente. Carica dati asincroni per performance ottimale. Widget inclusi:

  • Prossima Missione (esercizio da completare)
  • Stato XP e livello corrente
  • Badge sbloccati di recente
  • Annunci docente
  • Contatore messaggi non letti
[tutor_lab_dashboard]

Lab Operativo

Lista esercizi filtrabile per stato (Da Iniziare / In Corso / Completato). Barre di progresso visive e stato feedback.

[tutor_lab_progress_hub]

Progress Hub

Statistiche dettagliate: percentuali completamento, XP guadagnati per esercizio, performance nel tempo.

Gamification & Sistema XP

Engine di gamification completo. Gli XP vengono assegnati automaticamente in background per ogni azione di valore. I badge si sbloccano al raggiungimento di trigger configurabili.

Livelli di Progressione

Novizio
Apprendista
Specialista
Maestro

Tabella Punti XP

AzioneXP AssegnatiCostante PHPAJAX Action
Primo salvataggio esercizio+10 XPTUTOR_LAB_XP_FOR_FIRST_SAVEtutor_lab_save_exercise_data
Completamento esercizio+50 XPTUTOR_LAB_XP_FOR_COMPLETIONtutor_lab_save_exercise_data
Visualizzazione documento+5 XPTUTOR_LAB_XP_FOR_RESOURCE_VIEWtutor_lab_mark_resource_as_viewed
Visualizzazione lezione+10 XPTUTOR_LAB_XP_FOR_LESSON_VIEWtutor_lab_mark_resource_as_viewed
Iscrizione newsletter+150 XPTUTOR_LAB_XP_FOR_NEWSLETTERtutor_lab_award_newsletter_xp
Completamento sondaggio+150 XPTUTOR_LAB_XP_FOR_POLLtutor_lab_submit_poll
Test con punteggio perfetto+50 XP bonusTUTOR_LAB_XP_FOR_TEST_PERFECTtutor_lab_submit_poll

Badge

CPT badge. Trigger configurabili: first_login, exercises_completed_count. Meta: badge_trigger_type, badge_trigger_value_number. Gli badge sbloccati sono salvati in _tutor_lab_unlocked_badges (array di post ID).

Premi (Rewards)

CPT premio. Campi ACF: punti_xp_richiesti (costo in XP), tipo_premio (file/link/coupon), contenuto specifico. AJAX: tutor_lab_redeem_reward.

Classifica (Leaderboard)

[tutor_lab_class_leaderboard] — Classifica studenti della classe per XP, badge e attività recente

Mostra ranking con: nome studente, avatar, XP totali, contatore badge, livello, posizione in classifica. Dati da _tutor_lab_xp_points e _tutor_lab_unlocked_badges, filtrati per tassonomia classe.

Sistema Lock & Unlock

Gli esercizi sono sequenziali: il completamento di N sblocca N+1. Gli studenti possono richiedere lo sblocco anticipato con motivazione.

Flusso Normale

  1. Studente completa Es. 1

    Meta _tutor_lab_exercise_completed = true

  2. Es. 2 si sblocca

    Automaticamente disponibile nella dashboard

  3. Admin valuta Es. 1

    Feedback pubblicato, notifica email inviata

Sblocco Anticipato

  1. Studente richiede sblocco

    AJAX: tutor_lab_request_unlock, meta _tutor_lab_unlock_requested = true

  2. Admin riceve email

    Template: unlock-request-admin.php

  3. Admin approva dal backend

    AJAX: tutor_lab_unlock_exercise_ajax

Sondaggi & Test

CPT sondaggio con template single-sondaggio.php. Supporta scelta singola, multipla e risposta aperta. Integrato nel sistema XP (+150 XP per completamento, +50 XP bonus per punteggio perfetto).

AJAX Sondaggi

  • tutor_lab_submit_poll — Invia risposta sondaggio
  • tutor_lab_get_poll_results — Recupera risultati

CPT risposta_sondaggio

Ogni invio crea un post risposta_sondaggio con: autore = studente, meta con risposte, punteggio e timestamp.

Shortcodes Reference

ShortcodeFileDescrizione
[tutor_lab_ai_coach]
[tutorlab_ai_coach]		shortcodes/ai-coach.phpAI Coach Widget. Parametri: corso="", modulo="", show_history="yes". Richiede addon AI.
[tutor_lab_hub]shortcodes/hub.phpHub centrale studente con missioni, XP, badge, annunci.
[tutor_lab_dashboard]shortcodes/dashboard.phpDashboard esercizi con filtri per stato.
[tutor_lab_progress_hub]shortcodes/progress-hub.phpStatistiche avanzate progressi studente.
[tutor_lab_lessons]shortcodes/lessons.phpLista lezioni con stato completamento.
[tutor_lab_documents]shortcodes/documents.phpMateriali studio con download link.
[tutor_lab_all_updates]shortcodes/updates.phpFeed annunci e aggiornamenti classe.
[tutor_lab_class_leaderboard]shortcodes/leaderboard.phpClassifica studenti per XP e badge.
[tutor_lab_profile]shortcodes/profile.phpProfilo studente con badge, stats, cambio password.
[tutor_lab_login_form]shortcodes/login-form.phpForm login personalizzato con forgot password.
[tutor_lab_registration_form]shortcodes/registration-form.phpForm registrazione base.
[tutor_lab_registration_choice]shortcodes/registration-choice-form.phpRegistrazione con selezione ruolo/classe.
[tutor_lab_registration_onboarding]shortcodes/registration-full-onboarding.phpWizard onboarding multi-step completo.

Custom Post Types & Tassonomia

Slug CPTLabelTemplateNote
lezioneLezioneDefault WPAssociata a tassonomia classe
documentoDocumentoDefault WPProtezione media attiva
esercizioEserciziosingle-esercizio.phpCampi ACF builder, template ACF exercise_template
badgeBadgeDefault WPTrigger gamification configurabili via ACF
premioPremioDefault WPCosto XP e tipo contenuto via ACF
risposta_studenteRisposta StudenteNon pubblicaAutore = studente, meta feedback docente
annuncioAnnuncioDefault WPNotifica email automatica al publish
messaggio_privatoMessaggio PrivatoNon pubblicaMessaggistica interna
tutor_class_emailEmail ClasseDefault WPArchivio email inviate agli studenti
sondaggioSondaggiosingle-sondaggio.phpIntegrazione XP +150 al completamento
risposta_sondaggioRisposta SondaggioNon pubblicaCreato automaticamente all'invio

Tassonomia

SlugLabelApplicata ANote
classeClasseuser, esercizio, lezione, documento, annuncio, tutor_class_email, sondaggioGerarchica, non pubblica. Meta classe: date, status, toggle moduli.

AJAX Reference Completa

Oltre 80 azioni AJAX registrate. Le principali per sviluppatori:

Esercizi & Studenti

AzioneFileDescrizione
tutor_lab_save_exercise_dataajax-exercise-handler.phpSalva risposte esercizio studente
tutor_lab_heartbeatajax-exercise-handler.phpKeep-alive sessione esercizio
tutor_lab_get_lock_statusajax-exercise-handler.phpVerifica stato lock esercizio
tutor_lab_request_unlockajax-exercise-handler.phpStudente richiede sblocco anticipato
tutor_lab_save_builder_exerciseajax-builder-handler.phpSalva JSON esercizio dal builder admin
tutor_lab_get_quick_correct_dataajax-admin-handler.phpRecupera dati per correzione rapida
tutor_lab_save_quick_correct_dataajax-admin-handler.phpSalva correzione rapida bozza
tutor_lab_publish_feedback_ajaxajax-admin-handler.phpPubblica feedback e notifica studente
tutor_lab_unlock_exercise_ajaxajax-admin-handler.phpAdmin sblocca esercizio manualmente

Gamification

AzioneDescrizione
tutor_lab_mark_resource_as_viewedXP per visualizzazione lezione/documento
tutor_lab_award_newsletter_xpXP per iscrizione newsletter
tutor_lab_redeem_rewardRiscatta premio con XP
tutor_lab_get_hub_gamification_dataDati XP/livello/badge per l'hub
tutor_lab_get_hub_missions_dataProssime missioni disponibili
tutor_lab_get_hub_announcement_dataAnnunci della classe
tutor_lab_get_hub_updates_dataFeed attività recente
tutor_lab_get_hub_inbox_badge_dataContatore messaggi non letti

Registrazione & Auth

AzionePrivilegioDescrizione
tutor_lab_rapid_register_wizardnoprivRegistrazione rapida wizard
tutor_lab_full_register_wizardnoprivRegistrazione onboarding completo
tutor_lab_activate_licenseadminAttivazione licenza via server
tutor_lab_send_recharge_requestadminRichiesta ricarica token AI

Amministrazione

AzioneDescrizione
tutor_lab_refresh_matrix_dataAggiorna matrice progressi
tutor_lab_get_student_activity_logLog attività studente
tutor_lab_save_report_dataSalva bozza dati report finale
tutor_lab_upload_creative_imageUpload immagine per simulatore creativo
tutor_lab_export_stats_csvExport statistiche CSV
tutor_lab_export_stats_jsonExport statistiche JSON
tutor_lab_import_ics_eventsImport calendario ICS
tutor_lab_save_class_emailSalva email classe
tutor_lab_generate_feedback_json_templateGenera template JSON feedback
tutor_lab_get_hub_aggregated_dataDati aggregati hub (ACTION admin)
tutor_lab_submit_reviewStudente invia recensione corso

WordPress Hooks

Azioni Chiave

HookPrioritàUso
admin_post_tutor_lab_generate_reportdefaultGenera PDF report finale classe
admin_post_tutor_lab_publish_feedbackdefaultPubblica feedback da form admin
admin_post_tutor_lab_publish_feedback_bulkdefaultPubblica feedback in bulk
admin_post_tutor_lab_reset_exercisedefaultAzzera risposta studente
admin_post_tutor_lab_unlock_exercisedefaultSblocca esercizio
tutor_lab_send_content_notification_cron10Cron: invia notifica contenuto pubblicato
save_post_risposta_studente10, 20Salva feedback bozza, calcola XP

Filtri Chiave

FiltroUso
theme_page_templatesRegistra template custom: page-canvas.php, template-onboarding-fullscreen.php, simulatori
template_includeCarica template custom per CPT (priorità 98, 99)
body_classAggiunge classi frontend (ruolo, classe, tema)
admin_body_classClassi admin per shell styling
wp_authenticate_userBlocca utenti pending alla login
acf/load_value/name=*Fix caricamento meta array ACF

Sistema Licenze

File: /includes/core/license-manager.php. Server di licenze: https://promologica.it/wp-json/tl-license/v1

Funzioni Principali

  • tutor_lab_is_license_valid() — boolean
  • tutor_lab_is_addon_active($addon) — boolean
  • tutor_lab_get_license_limit($key) — int|null
  • tutor_lab_is_limit_exceeded($key, $count) — boolean

Slug Addon

  • ai / ai_coach
  • gamification
  • email / email_automation
  • analytics / advanced_reports
  • builder / api_access
  • pdf / pdf_export
  • branding / custom_branding
  • multi_team
  • video / video_lessons
  • sso

Limiti Controllabili

  • max_students
  • max_teachers
  • max_courses
  • max_exercises
  • max_storage_mb
  • max_ai_calls_month
Il token recharge manager (token-recharge-manager.php) monitora automaticamente l'uso dei token AI: avviso a 80% (TUTOR_LAB_TOKEN_WARN_PCT) e critico a 95% (TUTOR_LAB_TOKEN_CRITICAL_PCT). AJAX: tutor_lab_send_recharge_request.

Domande Frequenti

L'AI Coach può inventare informazioni sbagliate?
No. Grazie alla tecnologia RAG, l'AI risponde esclusivamente basandosi sui contenuti della Knowledge Base. Se la risposta non è presente nei documenti caricati, l'AI lo dichiara esplicitamente e suggerisce di contattare il docente umano.
Come si aggiungono studenti alla piattaforma?
Due modalità: (1) Import CSV massivo da Sistema → Importa Studenti. (2) Self-registration degli studenti tramite shortcode [tutor_lab_registration_choice] — le iscrizioni finiscono in stato "pending" e vengono approvate dalla pagina Approvazioni.
Posso gestire più corsi contemporaneamente?
Sì. La gerarchia Corso → Classe permette di gestire infiniti corsi in parallelo. Ogni studente vede solo i contenuti del corso a cui è iscritto. Con l'addon multi_team è possibile gestire team multipli con docenti diversi per corso.
Come funziona il salvataggio automatico del Builder?
Il Builder salva automaticamente ogni 30 secondi se ci sono modifiche non salvate. Lo stato è visibile nella toolbar: ✅ Salvato (verde), ⚠️ Modifiche non salvate (arancione), 🔄 Salvataggio in corso (blu). Usa Ctrl+S / Cmd+S per salvare manualmente.
Cosa succede se i crediti AI si esauriscono?
Il sistema invia email di avviso quando i crediti scendono sotto la soglia configurata. Se i crediti si azzerano, le richieste AI vengono bloccate e viene mostrato un messaggio di avviso. Il docente può acquistare crediti aggiuntivi dal backend tramite PayPal o Stripe.
Come si modifica un template email senza PHP?
Vai su Sistema → Impostazioni → Email. Ogni template ha un editor visuale con supporto HTML base, pulsanti CTA e variabili dinamiche ({{USER_NAME}}, {{EXERCISE_TITLE}}, ecc.). Puoi visualizzare un'anteprima e inviare email di test.
Il PDF del report riporta i voti assegnati?
Sì. Il report finale PDF include la tabella valutazioni con: nome studente, tipo elaborato, commento valutazione, punti (0-5) per esercizio e totale. I punteggi vengono letti da _draft_feedback_punteggi_docente con fallback su _draft_average_score. Le tabelle non vengono mai spezzate tra pagine diverse.
Come si abilita la gamification per una singola classe?
La gamification è controllata a livello di classe tramite il term meta _tutor_lab_gamification_enabled. Puoi attivarla/disattivarla dalla pagina Gestione Classi con un semplice toggle, senza dover modificare impostazioni globali.

Best Practices

Progressione Didattica

  • Inizia con esercizi semplici, aumenta gradualmente la complessità
  • Usa i blocchi "Istruzioni" per fornire contesto chiaro prima di ogni esercizio
  • Alterna teoria (lezioni) e pratica (esercizi) regolarmente
  • Non superare 5-7 sezioni per esercizio per non sovraccaricare lo studente

Ottimizzare l'AI

  • Popola la KB con materiali di qualità prima di attivare l'AI Coach
  • Monitora i consumi settimanalmente per ottimizzare i costi
  • Usa AI Profiles diversi per toni formale vs informale
  • Rivedi periodicamente i feedback AI per assicurare qualità

Gamification Efficace

  • Crea badge facili (motivazione iniziale) e difficili (obiettivi sfida)
  • Premia la consistenza (streak) oltre ai risultati puntuali
  • Mantieni la leaderboard visibile ma non invasiva
  • Usa i premi per incentivare comportamenti specifici

Sicurezza & Performance

  • Verifica sempre i nonce nelle azioni AJAX custom
  • Usa tutor_lab_is_addon_active() per feature-flag sicuri
  • Il media protection rewrite blocca accesso diretto ai file protetti
  • La matrice progressi è ottimizzata con una singola query SQL — non eseguire query aggiuntive in loop