# Manuale Utente Docente - ChronoQuest ## Sommario - [1. Introduzione](#1-introduzione) - [2. Installazione](#2-installazione) - [2.1 Setup iniziale della classe](#21-setup-iniziale-della-classe) - [3. Login e registrazione docente](#3-login-e-registrazione-docente) - [4. Modifica account docente](#4-modifica-account-docente) - [5. Creazione e selezione classi](#5-creazione-e-selezione-classi) - [6. Dashboard docente](#6-dashboard-docente) - [7. Inserimento studenti nella classe](#7-inserimento-studenti-nella-classe) - [8. Docenti della classe](#8-docenti-della-classe) - [9. Squadre](#9-squadre) - [10. Quest](#10-quest) - [11. Badge](#11-badge) - [12. Poteri](#12-poteri) - [13. Personaggi](#13-personaggi) - [14. Punizioni](#14-punizioni) - [15. Personalizzazioni](#15-personalizzazioni) - [16. Materiali](#16-materiali) - [17. Plugin](#17-plugin) - [18. Test Creator: home, materie e argomenti](#18-test-creator-home-materie-e-argomenti) - [19. Test Creator: domande](#19-test-creator-domande) - [20. Test Creator: quiz](#20-test-creator-quiz) - [21. Test Creator: libri e griglie di valutazione](#21-test-creator-libri-e-griglie-di-valutazione) - [22. Test Creator: template di stampa](#22-test-creator-template-di-stampa) - [23. Test Creator: importazione ed esportazione domande](#23-test-creator-importazione-ed-esportazione-domande) - [24. Test Creator: le mie classi](#24-test-creator-le-mie-classi) - [25. Test Creator: mail docenti](#25-test-creator-mail-docenti) - [26. Test Creator: amministratori](#26-test-creator-amministratori) ## 1. Introduzione ChronoQuest è una piattaforma didattica pensata per trasformare la gestione della classe in un percorso a missioni, ricompense, progressi e responsabilità. Il programma affianca il docente nella conduzione delle attività scolastiche quotidiane, offrendo strumenti per organizzare classi e studenti, proporre quest ed esercizi, seguire le consegne, assegnare badge e ricompense, gestire poteri, punizioni, materiali e personalizzazioni. Questo manuale descrive l'utilizzo del programma dal punto di vista del docente. L'obiettivo è fornire una guida pratica alle funzioni disponibili nell'area riservata, seguendo il flusso reale dell'applicazione: accesso, scelta della classe, dashboard, gestione degli studenti, creazione delle attività e controllo dei risultati. L'area docente di ChronoQuest ruota attorno alla classe selezionata. Dopo l'accesso, il docente può entrare in una delle proprie classi e amministrarne gli elementi principali: studenti, altri docenti associati, squadre, personaggi, quest, badge, poteri, punizioni, materiali e contenuti aggiuntivi tramite plugin. Molte funzioni sono quindi legate alla classe attiva: prima di lavorare sui contenuti o sui dati degli studenti è importante verificare di essere entrati nella classe corretta. Il sistema utilizza elementi tipici della gamification didattica. Gli studenti possono avere un personaggio, vite, mana, monete, livelli, badge, poteri, forzieri e personalizzazioni. Il docente mantiene il controllo di questi elementi e li usa per premiare i progressi, organizzare attività, correggere consegne e rendere più coinvolgente il lavoro svolto in classe. Il manuale è destinato ai docenti che utilizzano ChronoQuest per: - creare e selezionare le proprie classi; - gestire studenti e docenti collegati alla classe; - monitorare l'andamento degli studenti dalla dashboard; - creare quest, capitoli ed esercizi; - consultare e valutare le consegne; - assegnare ricompense, badge, poteri e punizioni; - caricare materiali didattici; - configurare personaggi, personalizzazioni e plugin. Le sezioni successive guideranno passo dopo passo nell'uso delle singole aree del programma, mantenendo un taglio operativo e orientato alle azioni che il docente deve svolgere. ## 2. Installazione L'installazione iniziale di ChronoQuest viene avviata dalla pagina `public/install.php`. Questa procedura serve a configurare il collegamento al database, impostare l'invio delle email e preparare l'account amministratore principale. La procedura può essere eseguita solo se il programma non risulta già installato. Se è già presente il file di configurazione `.env`, l'installer mostra un messaggio che indica che ChronoQuest è già installato e rimanda al login docente. ### Cartella pubblica del sito ChronoQuest è organizzato separando i file pubblici dai file interni del programma. La cartella che deve essere visibile dal browser è `public`, perché contiene i file di ingresso del sito, tra cui `index.php`, `install.php`, gli asset e le risorse raggiungibili dagli utenti. Le altre cartelle del progetto, come `src`, `config`, `routes`, `sql`, `vendor` e `var`, sono cartelle di sistema. Non devono essere esposte direttamente sul web, perché contengono codice applicativo, configurazioni, librerie, file SQL o dati interni. La configurazione consigliata è impostare la cartella iniziale del sito, detta anche document root, direttamente su `public`. In questo modo il visitatore entra già nella parte pubblica dell'applicazione e non può navigare nelle cartelle interne del progetto. Se il servizio di hosting non permette di impostare `public` come cartella iniziale, è necessario usare il file `.htaccess` nella cartella principale del progetto. Questo file ha due compiti: - impedire l'accesso diretto ai file e alle cartelle di sistema; - inoltrare automaticamente le richieste del sito verso la cartella `public`. Nel progetto è già presente una configurazione `.htaccess` che blocca l'accesso a cartelle come `config`, `routes`, `src`, `sql`, `var`, `vendor` e reindirizza le richieste verso `public`. Se dopo la pubblicazione del sito la pagina iniziale non viene aperta correttamente oppure non viene raggiunto `public/install.php`, bisogna controllare che il file `.htaccess` sia presente nella radice del progetto e che il server Apache consenta l'uso delle regole di rewrite. In breve: l'utente deve vedere il sito, non la struttura interna del programma. Se la radice del dominio non punta direttamente a `public`, il file `.htaccess` deve occuparsi della redirezione. ### Dati richiesti Nella schermata di installazione è necessario compilare questi gruppi di dati. **Pacchetto di installazione** Il campo "Initial configuration" permette di scegliere la configurazione iniziale da caricare nel database. Le opzioni disponibili sono: - "Base configuration", per installare una base vuota; - "Italian configuration", per installare la configurazione italiana; - "English configuration", per installare la configurazione inglese. La scelta determina quale pacchetto SQL iniziale viene importato durante l'installazione. **Database** Questa sezione serve a indicare dove si trova il database MySQL che userà ChronoQuest. - "Database Host": indirizzo del server database. Di solito è `localhost`, se il database si trova sullo stesso server del sito. - "Database Name": nome del database da usare per ChronoQuest. - "Database Username": nome utente autorizzato ad accedere al database. - "Database Password": password dell'utente database. Può essere vuota solo se il server database è configurato in questo modo. Il database deve esistere già ed essere raggiungibile. L'utente indicato deve avere i permessi necessari per importare le tabelle e i dati del pacchetto scelto. **Email** Questa sezione configura il server SMTP usato dal programma per inviare email, ad esempio messaggi di registrazione, notifiche o comunicazioni automatiche. - "SMTP Host": indirizzo del server di posta. - "Port": porta SMTP, ad esempio `465` per SSL o `587` per TLS, in base al provider. - "Encryption": tipo di cifratura da usare: SSL, TLS oppure None. - "SMTP Username": nome utente dell'account email. - "SMTP Password": password dell'account email. - "Sender Name": nome visualizzato come mittente, per esempio `ChronoQuest`. - "Sender Email": indirizzo email mittente. Deve essere un indirizzo valido. I valori predefiniti dell'installer propongono `smtps.aruba.it`, porta `465`, cifratura `ssl` e nome mittente `ChronoQuest`, ma possono essere modificati in base al servizio email utilizzato. **Administrator** Questa sezione imposta l'account amministratore iniziale. - "Admin Email": email dell'amministratore principale. - "Admin Password": password dell'amministratore. Deve contenere almeno 8 caratteri. - "Confirm Admin Password": ripetizione della password, per evitare errori di digitazione. Durante l'installazione, ChronoQuest aggiorna l'utente amministratore predefinito presente nel pacchetto iniziale, impostando l'email indicata e la nuova password. ### Avvio dell'installazione Dopo aver compilato tutti i campi richiesti, premere il pulsante "Install ChronoQuest". Il programma verifica i dati inseriti, importa il pacchetto scelto nel database, aggiorna la password dell'amministratore e crea il file `.env` con la configurazione. Al termine viene mostrato il messaggio "Installation Complete" e il pulsante per andare al login docente. Da quel momento l'installazione non può essere ripetuta dalla stessa pagina, per motivi di sicurezza. ## 2.1 Setup iniziale della classe Dopo l'installazione, nel sistema è disponibile una classe di riferimento chiamata `Test Class`. Tutti i docenti fanno parte della `Test Class`. Questa classe serve come ambiente di prova per visualizzare le funzionalità principali del programma e capire come sono strutturati contenuti, personaggi, quest, punizioni, poteri e altri elementi di ChronoQuest. Quando viene creata una nuova classe, la classe parte vuota. In particolare, una nuova classe non contiene: - personaggi; - quest; - punizioni; - poteri personalizzati; - alcune personalizzazioni; - altri contenuti configurati nella classe di test. Restano disponibili solo gli elementi fissi previsti dal sistema, ad esempio i poteri fissi. Per iniziare rapidamente, il docente può importare nella nuova classe gli elementi già presenti nella `Test Class`. Per farlo, entrare nella sezione specifica e usare il comando "Importa da altra classe". Esempi: - dalla sezione personaggi si possono importare personaggi da un'altra classe; - dalla sezione quest si possono importare quest da un'altra classe; - dalla sezione punizioni si possono importare punizioni da un'altra classe; - dalla sezione poteri si possono importare poteri da un'altra classe; In questo modo la nuova classe può essere preparata partendo dalla `Test Class`, senza dover ricreare manualmente ogni elemento. Dopo aver configurato la base della classe, si può procedere con l'inserimento degli studenti. ## 3. Login e registrazione docente ### Login amministratore Dopo l'installazione, il primo accesso viene effettuato dalla pagina `/loginDoc`. Credenziali iniziali: - username: `admin`; - password: quella inserita nel campo "Admin Password" durante l'installazione. Se le credenziali sono corrette, l'utente viene autenticato come amministratore e viene reindirizzato alla pagina `/docenti/classi`, da cui può selezionare o gestire le classi disponibili. ### Login docente La pagina di login docente è raggiungibile da `/loginDoc`. Campi richiesti: - "Username": nome utente del docente o dell'amministratore; - "Password": password associata all'account. In caso di errore viene mostrato il messaggio "username o password errate". Se l'accesso è valido, il sistema apre l'area docente e porta alla scelta della classe. ### Registrazione nuovo docente La registrazione di un nuovo docente è raggiungibile dalla pagina `/registrazioneDoc`, oppure dal link "Registrati!" presente nella schermata di login docente. Campi richiesti: - "Nome"; - "Cognome"; - "Username"; - "Email"; - "Password"; - "Conferma password"; - accettazione della dichiarazione privacy/GDPR. Controlli effettuati: - il nome e il cognome non possono essere vuoti; - lo username deve essere disponibile; - l'email deve avere un formato valido; - l'email non deve essere già usata da un altro utente; - l'email deve essere presente nella lista delle email abilitate alla registrazione, le mail vengono abilitate dall'amministratore nella sezione Test Creator. Questo per sicurezza: solo i docenti abilitati possono iscriversi al sito (non gli studenti o altri esterni); - password e conferma password devono coincidere; - la conferma privacy/GDPR è obbligatoria. Durante la compilazione, username ed email vengono controllati anche tramite validazione automatica. Se lo username è già usato o l'email non è abilitata, il form segnala l'errore prima dell'invio. Dopo l'invio corretto, il sistema crea l'utente docente con stato non ancora validato e invia una mail di convalida all'indirizzo indicato. Il docente può accedere solo dopo aver aperto il link di validazione ricevuto via email. ## 4. Modifica account docente La modifica dell'account docente è disponibile dopo il login, dal menu utente in alto a destra, voce "Profilo". La pagina corrispondente è `/docenti/profilo`. ### Campi visualizzati La pagina mostra: - "Nome e cognome": campo non modificabile; - "Username": campo non modificabile; - "Email": campo modificabile; - "Vuoi ricevere mail dal sito?": scelta "Sì" / "No"; - "API key Gemini": campo opzionale per usare le funzioni di suggerimento con Gemini; - "Lingua": scelta tra inglese predefinito e italiano; - "Nuova password"; - "Conferma nuova password". ### Regole di modifica Il docente può aggiornare email, preferenze email, chiave Gemini, lingua e password. Nome, cognome e username non sono modificabili da questa schermata. ### Ottenere una API key Gemini Per usare le funzioni basate su Gemini, il docente deve inserire nel profilo una chiave API personale. Procedura sintetica: - accedere con un account Google a `https://aistudio.google.com/apikey`; - accettare, se richiesto, i termini di servizio di Google AI Studio; - creare o selezionare un progetto Google Cloud; - premere "Create API key"; - copiare la chiave generata; - incollare la chiave nel campo "API key Gemini" del profilo docente; - salvare le modifiche. La chiave API deve essere trattata come una password: non va pubblicata, condivisa o inserita in file accessibili da altri utenti. Se si sospetta che la chiave sia stata esposta, è necessario generarne una nuova e disattivare quella precedente. La password viene cambiata solo se viene compilato il campo "Nuova password". Se il docente non vuole modificarla, deve lasciare vuoti sia "Nuova password" sia "Conferma nuova password". Controlli applicati al salvataggio: - l'email deve essere valida; - l'email non deve essere già usata da un altro utente; - se viene inserita una nuova password, i due campi password devono coincidere; - la lingua viene salvata solo se il valore è `en` o `it`. Per confermare le modifiche premere "Salva modifiche". In caso di esito positivo viene mostrato il messaggio di profilo aggiornato correttamente. ## 5. Creazione e selezione classi La gestione delle classi è disponibile dalla voce "Le mie classi" del menu laterale, oppure dalla pagina `/docenti/classi`. Questa pagina serve a scegliere la classe su cui lavorare. La classe selezionata determina i dati mostrati nelle sezioni successive, inclusa la Dashboard docente, gli studenti, le quest, i badge, i poteri, le punizioni e le personalizzazioni. ### Elenco classi La pagina mostra le classi associate al docente, raggruppate per anno scolastico. Per ogni classe sono visibili: - anno scolastico; - nome classe; - icona; - colore associato; - indicazione "Selezionata", se è la classe attualmente attiva; - pulsante "Entra nella classe"; - pulsante di modifica. Premendo "Entra nella classe", la classe viene salvata come classe attiva nella sessione e il sistema apre la Dashboard docente. ### Creazione nuova classe Per creare una nuova classe premere "Inserisci nuova classe". Campi richiesti: - "Nome classe"; - "Anno scolastico"; - "Icona classe"; - "Colore classe". Al salvataggio, il sistema: - crea la classe; - la associa al docente corrente; - la seleziona automaticamente; - reindirizza alla Dashboard docente. Se il nome classe è vuoto o l'anno scolastico non è valido, la classe non viene creata. ### Modifica classe Dal pulsante di modifica presente nella scheda della classe è possibile aggiornare: - nome classe; - icona; - colore. L'anno scolastico non viene modificato da questa schermata. Se la classe modificata è quella attiva, i nuovi dati vengono aggiornati anche nella sessione corrente. ### Note operative Molte pagine dell'area docente richiedono una classe selezionata. Se non è presente una classe attiva, il sistema rimanda alla pagina `/docenti/classi`. Un docente può entrare solo nelle classi a cui è associato. Se tenta di aprire una classe non collegata al proprio account, la selezione viene rifiutata. ## 6. Dashboard docente La Dashboard docente è raggiungibile da `/docenti/dashboard` dopo aver selezionato una classe. Serve ad avere una panoramica rapida dello stato degli studenti della classe: vite, scudi, mana, monete, livello, avanzamento verso il livello successivo e personaggio scelto. È la pagina di controllo principale per verificare l'andamento generale della classe e intervenire velocemente sui singoli alunni. ### Dati visualizzati La tabella mostra, per ogni studente: - cognome e nome; - vite e scudi disponibili; - mana disponibile; - monete possedute; - livello; - progresso verso il livello successivo; - personaggio associato; - pulsante per togliere un cuore; - pulsante per morte istantanea. Se uno studente non ha ancora scelto il personaggio, i dati collegati al personaggio non sono disponibili e la tabella mostra valori provvisori. ### Azioni sui singoli studenti Per ogni riga sono disponibili azioni dirette: - "Togli Cuore": rimuove un cuore allo studente selezionato. È richiesta una motivazione. - "Morte istantanea": azzera lo stato vitale dello studente e avvia la procedura di assegnazione punizione. Quando uno studente perde tutte le vite, il sistema chiede di assegnare una punizione. È possibile: - assegnare una punizione casuale tra quelle disponibili; - scegliere una punizione esistente; - creare una nuova punizione indicando descrizione, giorni per la consegna ed eventuale immagine. ### Azioni su studenti selezionati La tabella permette la selezione multipla degli studenti. Dopo aver selezionato una o più righe, si attivano i pulsanti in alto: - "Invia Mail": apre la composizione di un messaggio rivolto agli studenti selezionati. - "Togli Cuore": rimuove un cuore agli studenti selezionati. È richiesta una motivazione. - "Dai Ricompensa": assegna punti esperienza e/o monete agli studenti selezionati. È richiesta una motivazione. Per assegnare una ricompensa è necessario indicare almeno un valore tra XP e monete. La motivazione viene usata per comunicare agli studenti il motivo della ricompensa. ### Note operative La Dashboard lavora sempre sulla classe attualmente selezionata. Se non è stata selezionata alcuna classe, il sistema rimanda alla pagina di scelta classe. Le modifiche effettuate dalla Dashboard aggiornano i dati degli studenti e possono generare notifiche o messaggi visibili nell'area studente. ## 7. Inserimento studenti nella classe La gestione degli studenti è disponibile dal menu "Studenti e Docenti" > "Lista Studenti", oppure dalla pagina `/docenti/studenti`. La pagina lavora sulla classe attualmente selezionata. Se non è stata selezionata una classe, il sistema rimanda alla pagina `/docenti/classi`. ### Elenco studenti La tabella mostra gli studenti associati alla classe attiva. Campi visualizzati: - cognome; - nome; - email; - username; - sesso; - indicazione PEI; - pulsante di modifica; - pulsante di eliminazione dalla classe. Gli studenti con PEI vengono evidenziati nella tabella. ### Inserimento manuale Per inserire un singolo studente premere "Aggiungi studente". Campi richiesti: - "Nome studente"; - "Cognome studente"; - "Email studente"; - "Sesso studente"; - "Studente con PEI"; - "Password studente". Durante l'inserimento, lo username viene generato automaticamente a partire da nome e cognome. In caso di omonimie, il sistema genera uno username progressivo per evitare duplicati. Per un nuovo studente inserito manualmente, la password iniziale viene impostata sullo username generato. Il campo password è invece utile in modifica, per cambiare la password di uno studente già esistente. Controlli applicati: - nome e cognome obbligatori; - email obbligatoria e valida per i nuovi studenti; - sesso valido: `M` o `F`; - lo studente non deve essere già presente nella classe selezionata. ### Modifica studente Il pulsante "Modifica" apre la scheda dello studente. In modifica è possibile aggiornare: - nome; - cognome; - sesso; - indicazione PEI; - password. L'email non viene modificata da questa schermata. Se il campo password resta vuoto, la password corrente non viene cambiata. ### Import studenti da CSV Il pulsante "Importa studenti da CSV" consente di caricare più studenti insieme. Formato richiesto: ```text nome;cognome;email;sesso;l104 ``` Il file deve: - essere in formato `.csv`; - usare il punto e virgola come separatore; - avere la prima riga di intestazione; - contenere al massimo 50 KB; - indicare il sesso come `M` o `F`; - indicare `l104` con valori riconosciuti come `1`, `true`, `si`, `sì`, `yes`, `y` oppure `0`/vuoto per valore negativo. Durante l'import: - se lo studente non esiste, viene creato e associato alla classe; - se lo studente esiste già come studente, viene associato alla classe se non è già presente; - se l'email appartiene a un docente o amministratore, la riga viene saltata per sicurezza; - viene generata una password casuale composta da un nome di animale in inglese e tre cifre; - il sistema prova a inviare allo studente una email con username e password. Al termine viene mostrato un riepilogo con studenti creati, associati, già presenti, email inviate, email non inviate ed eventuali righe non valide. ### Import studenti da altra classe Il pulsante "Importa studenti da altra classe" permette di associare alla classe corrente studenti già presenti in un'altra classe. Procedura: - aprire la finestra di import; - selezionare la classe di origine; - confermare con "Importa classe". Non è possibile importare dalla stessa classe attualmente selezionata. Gli studenti importati mantengono il proprio account e i dati già collegati, inclusi i personaggi eventualmente associati. ### Rimozione dalla classe Il pulsante "Elimina" rimuove lo studente dalla classe selezionata. La rimozione elimina il collegamento tra studente e classe corrente. Non elimina necessariamente l'account utente dello studente dal sistema. ## 8. Docenti della classe La gestione dei docenti della classe è disponibile dal menu "Studenti e Docenti" > "Aggiungi Docenti", oppure dalla pagina `/docenti/docenti`. La pagina lavora sulla classe attualmente selezionata. Se non è presente una classe attiva, il sistema rimanda alla selezione classe. ### Scopo della pagina Questa pagina serve ad associare altri docenti alla classe corrente. Non crea nuovi account docente. Gli account devono essere già registrati, validati e avere ruolo docente. ### Docenti già associati La prima tabella mostra i docenti già collegati alla classe. Campi visualizzati: - cognome; - nome; - email; - username. Questi docenti possono accedere alla classe e lavorare sui relativi dati, secondo i permessi previsti dall'area docente. ### Docenti disponibili per l'aggiunta La seconda tabella mostra i docenti validati che non sono ancora associati alla classe corrente. Campi visualizzati: - cognome; - nome; - email; - username; - pulsante "Aggiungi". Premendo "Aggiungi" viene richiesta una conferma. Se confermata, il docente selezionato viene associato alla classe corrente. ### Controlli applicati Il sistema verifica che: - l'utente selezionato esista; - l'utente abbia ruolo docente; - l'utente non sia già associato alla classe; - il docente che esegue l'operazione abbia accesso alla classe selezionata. Se l'operazione va a buon fine, viene mostrato il messaggio di docente aggiunto correttamente alla classe. ## 9. Squadre La gestione delle squadre è disponibile dal menu laterale "Squadre", oppure dalla pagina `/docenti/squadre`. La pagina lavora sulla classe attualmente selezionata e serve a creare, controllare e approvare le squadre degli studenti. ### Elenco squadre La tabella mostra le squadre della classe, sia approvate sia in attesa. Campi visualizzati: - nome squadra; - tipologia; - creatore; - emblema; - membri e invitati; - stato; - azioni disponibili. Lo stato può essere: - "Approvata"; - "In attesa". Le squadre in attesa sono quelle create dagli studenti e non ancora approvate dal docente. ### Tipologie di squadra Le tipologie disponibili sono: - Mercanti; - Maghi; - Guerrieri; - Saggi. La tipologia viene scelta durante la creazione o modifica della squadra e può essere usata dal sistema per differenziare bonus o comportamenti di gioco. In particolare si differenzia il potere di squadra: i mercanti generano oro, i maghi ricaricano completamente il mana, i guerrieri ricaricano completamente la vita, i saggi ottengono xp. ### Creazione squadra Per creare una squadra premere "Aggiungi squadra". Campi richiesti: - nome squadra; - tipologia; - emblema; - studenti della squadra. L'emblema può essere: - caricato come nuova immagine; - scelto tra gli emblemi di default. Per una nuova squadra è obbligatorio selezionare un emblema. Ogni squadra può avere al massimo 4 studenti. Uno studente già assegnato a un'altra squadra della stessa classe non viene proposto come disponibile. Le squadre create dal docente risultano già approvate. ### Modifica squadra Le squadre approvate possono essere modificate dal pulsante "Modifica". È possibile aggiornare: - nome; - tipologia; - emblema; - membri. Per l'emblema si può mantenere quello attuale, caricare una nuova immagine o scegliere un emblema di default. ### Eliminazione squadra Il pulsante "Elimina" rimuove una squadra approvata. L'eliminazione cancella: - la squadra; - i collegamenti con i membri; - eventuali inviti collegati. ### Approvazione o rifiuto squadre create dagli studenti Gli studenti possono proporre la creazione di una squadra. In questo caso la squadra appare con stato "In attesa". Le squadre vanno approvate per non incorrere in nomi o immagini sconvenienti inseriti dagli studenti. Azioni disponibili: - "Approva": approva la squadra e invia notifiche agli studenti coinvolti; - "Rifiuta": elimina la squadra proposta e gli inviti collegati. Quando una squadra viene approvata, il creatore riceve una notifica di approvazione e gli studenti invitati ricevono l'invito a entrare nella squadra. Quando una squadra viene rifiutata, il creatore riceve una notifica di mancata approvazione. ## 10. Quest La gestione delle quest e disponibile dal menu laterale "Quest", oppure dalla pagina `/docenti/quest`. La quest e un percorso didattico strutturato in: - quest principale; - piantina della quest; - capitoli posizionati sulla piantina; - esercizi collegati ai capitoli; - consegne e valutazioni degli studenti. La pagina lavora sempre sulla classe attualmente selezionata. ### Elenco quest La pagina iniziale mostra l'elenco delle quest disponibili per la classe. Per ogni quest sono presenti: - nome; - immagine; - pulsante di accesso alla piantina; - pulsante di modifica; - pulsante di eliminazione. Il pulsante "Accedi" apre la piantina della quest, da cui si gestiscono capitoli ed esercizi. ### Creazione o modifica di una quest Per creare una nuova quest premere "Nuova quest". Campi principali: - "Nome quest": nome visualizzato al docente e agli studenti; - "Immagine quest": immagine rappresentativa della quest; - "Piantina quest": immagine usata come mappa di sfondo; - "Blocca esercizi": modalita di avanzamento degli studenti. Le immagini accettate sono nei formati comuni, ad esempio `jpg`, `jpeg`, `png`, `gif` e `webp`. La voce "Blocca esercizi" controlla l'ordine di avanzamento: - se il blocco e attivo, lo studente deve completare gli esercizi precedenti prima di accedere ai successivi; - se il blocco non e attivo, gli esercizi attivi risultano accessibili senza vincolo progressivo. In modifica e possibile aggiornare il nome, la modalita di blocco e, se necessario, le immagini associate. ### Piantina della quest Entrando in una quest viene mostrata la piantina. La piantina serve a rappresentare visivamente il percorso e a posizionare i capitoli sulla mappa. Azioni disponibili: - tornare all'elenco delle quest; - aprire la lista dei capitoli; - visualizzare le consegne non valutate; - aggiungere un nuovo capitolo. Per inserire un capitolo: - premere "Aggiungi capitolo"; - cliccare sulla piantina nel punto in cui deve comparire il capitolo; - inserire il nome del capitolo; - indicare il progressivo; - salvare. Le coordinate `x` e `y` vengono compilate automaticamente in base al punto selezionato sulla piantina. ### Lista capitoli La lista capitoli mostra tutti i capitoli della quest ordinati per progressivo. Campi visualizzati: - progressivo; - nome capitolo; - azioni disponibili. Dal pulsante di modifica e possibile aggiornare: - nome capitolo; - coordinate sulla piantina; - progressivo. Il progressivo determina l'ordine di visualizzazione e, quando il blocco esercizi e attivo, contribuisce alla sequenza di sblocco per gli studenti. ### Dettaglio capitolo ed esercizi Aprendo un capitolo viene mostrato l'elenco degli esercizi associati. Per ogni esercizio sono visibili: - progressivo; - nome esercizio; - argomento; - tipologia; - punti esperienza previsti; - stato di attivazione; - azioni disponibili. Gli esercizi non attivi possono essere modificati o eliminati. Gli esercizi attivi non possono essere modificati o eliminati dalla schermata docente. Per questi esercizi è disponibile la consultazione delle consegne. La tabella evidenzia gli esercizi attivi: - esercizio attivo senza consegne in attesa: riga evidenziata come attiva; - esercizio attivo con consegne da valutare: riga evidenziata per richiamare l'attenzione del docente. ### Creazione di un esercizio Per creare un esercizio entrare nel capitolo e premere il pulsante di aggiunta. Campi principali: - nome esercizio; - tipo di esercizio; - difficolta; - materia; - argomento; - materiali collegati; - link di supporto; - punti esperienza; - monete; - storia; - numero di domande; - testo dell'esercizio. I tipi di esercizio disponibili sono: - risposta aperta; - quiz a risposta multipla; - esercizio da consegnare; - quiz misto con risposte multiple e domande aperte. La difficolta puo essere impostata su livelli crescenti, da facile a molto difficile. La difficolta viene usata anche nel calcolo delle ricompense. La materia e l'argomento servono a collegare l'esercizio ai contenuti didattici presenti nel sistema. Dopo aver scelto l'argomento, è possibile associare materiali gia caricati per quell'argomento. Argomenti e domande a scelta multpila possono essere impostati nella sezione "Test creator" Il campo "Link di supporto" consente di inserire riferimenti esterni utili allo studente. I campi "Storia" e "Testo dell'esercizio" usano un editor testuale avanzato. L'editor permette anche l'inserimento di immagini e formule matematiche in formato Latex. ### Testo semplificato per studenti con PEI In modifica esercizio puo essere presente anche il campo per il testo semplificato. Questo testo viene mostrato agli studenti contrassegnati con PEI, se compilato. Se il testo semplificato non è presente, anche questi studenti vedono il testo standard dell'esercizio. ### Modifica di un esercizio Un esercizio puo essere modificato solo se non è ancora attivo. In modifica e possibile aggiornare: - nome; - progressivo; - difficolta; - materiali collegati; - link di supporto; - punti esperienza; - monete; - storia; - testo esercizio; - testo semplificato. Materia, argomento e tipologia sono vincolati alla struttura dell'esercizio e non vengono modificati liberamente dalla schermata di modifica. ### Attivazione degli esercizi Un esercizio diventa visibile agli studenti solo dopo l'attivazione. Quando il docente attiva un esercizio: - l'esercizio risulta disponibile nella quest degli studenti; - il sistema registra lo stato attivo per la classe; - gli studenti ricevono una notifica con il collegamento all'esercizio. Dopo l'attivazione l'esercizio non puo più essere modificato o eliminato, per evitare incoerenze con consegne gia aperte o completate. ### Consegne degli studenti Dal dettaglio del capitolo, per un esercizio attivo, il docente puo aprire la pagina delle consegne. La pagina mostra, per ogni studente: - nome e cognome; - stato della consegna; - eventuale valutazione gia assegnata; - link alla consegna dello studente. Se lo studente non ha ancora consegnato, la riga indica che la consegna non e presente. Se la consegna e stata valutata, la riga mostra la valutazione assegnata. ### Valutazione di una consegna Aprendo la consegna di uno studente, il docente vede: - testo dell'esercizio; - risposta dello studente; - eventuali file consegnati; - eventuali risposte a quiz; - campo commento; - campo valutazione. La valutazione viene espressa con un voto da 1 a 10. In base alla valutazione, al livello dello studente, alla difficolta e ai valori impostati nell'esercizio, il sistema calcola e assegna le ricompense: - punti esperienza; - monete; - eventuale avanzamento di livello. Per valutazioni molto basse, la ricompensa viene ridotta. La consegna già valutata non puo essere valutata una seconda volta dalla stessa schermata. ### Suggerimento con Gemini Se il docente ha inserito una API key Gemini nel proprio profilo, in alcune consegne può usare il pulsante di suggerimento valutazione. La funzione è disponibile per le consegne non ancora valutate e per gli esercizi che richiedono correzione testuale o manuale. Il suggerimento non sostituisce la decisione del docente: il voto finale deve essere controllato e confermato manualmente. ### Esercizi a quiz Per gli esercizi a risposta multipla, il sistema confronta le risposte dello studente con quelle corrette. Nella schermata di consegna il docente puo vedere: - risposte selezionate; - risposte corrette; - punteggio o valutazione suggerita. Nei quiz misti, la parte a risposta multipla viene calcolata automaticamente, mentre le domande aperte restano da controllare e commentare. ### Consegne non valutate e problemi Dalla piantina della quest e disponibile la pagina delle consegne non valutate. Questa pagina raccoglie le consegne ancora da correggere per la quest corrente. Per ogni riga sono indicati: - studente; - capitolo; - esercizio; - eventuale segnalazione di problema; - azioni disponibili. Il docente può: - aprire la consegna da correggere; - segnare una consegna come problematica; - aggiungere una descrizione del problema. La segnalazione di problema serve a tenere traccia di consegne che richiedono controllo prima della valutazione. ### Importazione ed esportazione quest Dal pulsante "Importa/Esporta" si accede alla pagina dedicata allo scambio delle quest. Funzioni disponibili: - esportare una quest originale in formato `.zip`; - importare una quest da file `.zip`; - importare una quest presente in un'altra classe. Con quest originale si intende una non importata da un'altra classe, ma creata manualmente dal docente o importata da file esterno. Durante l'esportazione viene generato un archivio con la struttura della quest, i capitoli, gli esercizi e le risorse collegate. Durante l'importazione da file, se la quest contiene argomenti non presenti nella classe o nel sistema, il programma richiede di: - associare l'argomento mancante a un argomento esistente; - creare un nuovo argomento sotto una materia selezionata. L'importazione da altra classe permette di copiare una quest gia esistente senza doverla ricostruire manualmente. Gli esercizi importati risultano inizialmente non attivi nella nuova classe. ### Note operative Una quest completa richiede almeno: - una quest creata; - una piantina; - uno o piu capitoli; - uno o piu esercizi; - attivazione degli esercizi da rendere disponibili agli studenti. Prima di attivare un esercizio è consigliato controllare testo, materiali, ricompense, difficoltà e ordine progressivo. Dopo l'attivazione, l'esercizio entra nel flusso di lavoro degli studenti e non può più essere modificato liberamente. ## 11. Badge Il menu "Badge" contiene due pagine: - "Vedi badge", raggiungibile da `/docenti/badge`; - "Badge studenti", raggiungibile da `/docenti/badge/assegnati`. I badge sono riconoscimenti collegati a materia e argomento. Servono a premiare il raggiungimento di obiettivi didattici, definiti tramite numero minimo di esercizi e media minima richiesta. ### Badge disponibili La pagina `/docenti/badge` mostra i badge presenti nel sistema e permette di crearli, modificarli, eliminarli, importarli ed esportarli. La pagina lavora sulla classe attualmente selezionata, ma i badge sono collegati soprattutto a materia e argomento. ### Filtri Nella parte superiore sono disponibili i filtri: - materia; - argomento. Il filtro per argomento dipende dalla materia selezionata. Se il docente ha materie associate al proprio account, la pagina propone una materia disponibile e mostra i relativi badge. ### Tabella badge La tabella mostra: - nome del badge; - materia e argomento; - descrizione; - immagine; - numero minimo di esercizi; - media minima; - genere; - azioni disponibili. Il genere può essere: - `U`: universale; - `M`: maschile; - `F`: femminile. ### Creazione badge Per creare un badge premere "Aggiungi badge". Campi richiesti: - nome badge; - materia; - argomento; - descrizione; - numero minimo di esercizi; - media minima; - genere; - immagine del badge. Regole principali: - il nome è obbligatorio; - la descrizione è obbligatoria; - l'argomento deve essere valido; - il numero minimo di esercizi deve essere maggiore di `0`; - la media minima deve essere compresa tra `0` e `10`; - l'immagine è obbligatoria in fase di creazione; - i formati immagine ammessi sono `png`, `jpg`, `jpeg`, `gif` e `webp`. Il badge viene salvato con il docente corrente come creatore. ### Modifica badge Un badge può essere modificato solo dal docente che lo ha creato. In modifica è possibile aggiornare: - nome; - materia e argomento; - descrizione; - numero minimo di esercizi; - media minima; - genere; - immagine. Se non viene caricata una nuova immagine, il sistema mantiene quella già presente. I badge creati da altri docenti sono visibili in sola lettura. ### Eliminazione badge Un badge può essere eliminato solo dal docente che lo ha creato. L'eliminazione rimuove: - il badge; - l'immagine caricata; - eventuali assegnazioni già registrate agli studenti. Prima di eliminare un badge è quindi opportuno verificare se è già stato ottenuto da qualche studente. ### Importazione ed esportazione badge Il pulsante "Importa/Esporta" apre la finestra dedicata allo scambio dei badge. Funzioni disponibili: - esportazione dei badge di una materia in formato `.zip`; - importazione di badge da archivio `.zip`. L'esportazione richiede la selezione di una materia. Il file generato contiene i dati dei badge e le immagini collegate. L'importazione richiede un archivio `.zip` valido. Se l'archivio contiene argomenti non presenti nel sistema, il programma chiede di associare gli argomenti mancanti ad argomenti esistenti. I badge importati vengono assegnati come creati dal docente che esegue l'importazione. ### Badge studenti La pagina `/docenti/badge/assegnati` mostra i badge ottenuti dagli studenti della classe selezionata. È possibile filtrare per: - tutti gli studenti; - uno studente specifico. Per ogni badge assegnato vengono mostrati: - nome badge; - immagine; - studente; - materia; - argomento; - data di conquista; - descrizione. Questa pagina è di consultazione: non serve a creare badge e non assegna manualmente nuovi badge. ### Note operative Per usare correttamente i badge è necessario che: - il docente abbia materie associate; - gli argomenti siano presenti e collegati alle materie; - i badge siano configurati con criteri coerenti; - gli studenti svolgano esercizi collegati agli argomenti dei badge. Il numero minimo di esercizi e la media minima definiscono la soglia richiesta per ottenere il badge. Valori troppo alti rendono il badge difficile da raggiungere; valori troppo bassi lo rendono poco selettivo. ## 12. Poteri Il menu "Poteri" contiene due pagine: - "Vedi poteri", raggiungibile da `/docenti/poteri`; - "Poteri assegnati", raggiungibile da `/docenti/poteri/assegnati`. I poteri sono abilità che gli studenti possono scegliere e usare nell'area studente. Ogni potere ha un livello minimo richiesto e un costo in mana. ### Poteri disponibili La pagina `/docenti/poteri` mostra i poteri disponibili per la classe selezionata. La tabella visualizza: - nome del potere; - descrizione; - immagine; - livello richiesto; - mana necessario; - tipo; - azioni disponibili. Il tipo può essere: - "Fisso": potere globale del sistema, visibile ma non modificabile dal docente; - "Classe": potere creato o importato per la classe corrente. ### Creazione potere Per creare un nuovo potere premere "Aggiungi potere". Campi richiesti: - nome potere; - descrizione; - livello; - mana consumato; - immagine del potere. Regole principali: - il nome è obbligatorio; - la descrizione è obbligatoria; - il livello deve essere maggiore o uguale a `0`; - il mana consumato deve essere maggiore o uguale a `1`; - l'immagine è obbligatoria in fase di creazione; - i formati immagine ammessi sono `png`, `jpg`, `jpeg`, `gif` e `webp`. Il potere creato viene collegato alla classe attualmente selezionata. ### Modifica potere È possibile modificare solo i poteri di classe. In modifica si possono aggiornare: - nome; - descrizione; - livello richiesto; - mana necessario; - immagine. Se non viene caricata una nuova immagine, il sistema mantiene quella già presente. I poteri fissi non sono modificabili. ### Eliminazione potere È possibile eliminare solo i poteri di classe. Un potere non può essere eliminato se è già stato scelto da almeno uno studente. I poteri fissi non possono essere eliminati. ### Importazione da altre classi Il pulsante "Importa da altre classi" permette di copiare nella classe corrente un potere creato in un'altra classe. La finestra di import mostra: - nome del potere; - descrizione; - classe di origine; - anno scolastico; - livello richiesto; - mana necessario. Non vengono proposti: - poteri fissi; - poteri della stessa classe; - poteri con nome già presente nella classe corrente. Il potere importato viene copiato nella classe attuale e potrà poi essere usato dagli studenti secondo livello e mana richiesti. ### Poteri assegnati agli studenti La pagina `/docenti/poteri/assegnati` mostra i poteri già scelti dagli studenti della classe. È possibile filtrare per: - tutti gli studenti; - uno studente specifico. Per ogni potere assegnato vengono mostrati: - nome del potere; - immagine; - studente; - livello richiesto; - mana necessario; - descrizione. Questa pagina è di consultazione: non assegna manualmente nuovi poteri agli studenti. ### Scelta e uso da parte degli studenti Gli studenti scelgono i poteri dalla propria area, quando hanno poteri disponibili da selezionare. La scelta è consentita solo se: - lo studente ha almeno un potere da scegliere; - il potere non è già stato scelto dallo stesso studente; - il livello richiesto dal potere non supera il livello dello studente; - il potere è fisso oppure appartiene alla classe selezionata. Quando lo studente usa un potere: - il sistema verifica che il potere sia stato scelto dallo studente; - controlla che il mana disponibile sia sufficiente; - sottrae il mana necessario; - registra l'uso del potere; - genera notifiche per studente e docente. Alcuni poteri possono richiedere la selezione di un compagno come bersaglio. In questi casi il bersaglio deve appartenere alla stessa classe ed essere valido per quel potere. ### Note operative Prima di rendere disponibili molti poteri, è consigliato controllare: - livello richiesto; - costo in mana; - descrizione dell'effetto; - coerenza con le regole della classe. Livelli troppo bassi o costi in mana troppo ridotti possono rendere i poteri troppo facili da usare. Livelli troppo alti o costi troppo elevati possono invece renderli poco utilizzati dagli studenti. ## 13. Personaggi La gestione dei personaggi è disponibile dal menu laterale "Personaggi", oppure dalla pagina `/docenti/personaggi`. I personaggi sono gli avatar iniziali che gli studenti possono scegliere nella propria area. Ogni personaggio definisce valori di partenza e immagini usate nella dashboard studente. ### Elenco personaggi La pagina mostra i personaggi disponibili per la classe selezionata. Per ogni personaggio sono visibili: - nome; - vita iniziale; - mana iniziale; - immagine; - pulsante di modifica. La vita iniziale viene rappresentata con icone cuore. Il mana iniziale viene rappresentato con icone mana. ### Creazione personaggio Per creare un personaggio premere "Aggiungi". Campi richiesti: - nome personaggio; - vita iniziale; - mana iniziale; - colore ombra; - colore bordo; - descrizione; - avatar; - avatar senza sfondo. Regole principali: - il nome è obbligatorio; - vita iniziale e mana iniziale devono essere almeno `1`; - l'avatar è obbligatorio in fase di creazione; - l'avatar senza sfondo è opzionale; - i formati immagine ammessi sono `jpg`, `jpeg`, `png`, `gif` e `webp`. Il personaggio creato viene collegato alla classe attualmente selezionata. ### Immagini del personaggio Il campo "Avatar" contiene l'immagine principale del personaggio, mostrata nelle tabelle e nelle schermate di selezione. Il campo "Avatar senza sfondo" contiene l'immagine usata per comporre il personaggio con personalizzazioni, equipaggiamenti o elementi grafici della dashboard studente. Se il personaggio deve essere usato con personalizzazioni grafiche, è consigliato caricare anche l'immagine senza sfondo, in modo da poter inserire i background al personaggio ed eventualmente sovrapporre i capelli colorati. Vi sono diversi servizi online che permettono di rimuovere gli sfondi dei personaggi con ia in maniera gratuita. ### Colori Il colore ombra e il colore bordo servono alla visualizzazione grafica del personaggio. - "Colore ombra": colore usato per l'effetto ombra intorno all'immagine; - "Colore bordo": colore del bordo dell'immagine. Questi valori non modificano statistiche o regole di gioco. ### Modifica personaggio Il pulsante "Modifica" apre la scheda del personaggio selezionato. In modifica è possibile aggiornare: - nome; - vita iniziale; - mana iniziale; - colore ombra; - colore bordo; - descrizione; - avatar; - avatar senza sfondo. Se non viene caricata una nuova immagine, il sistema mantiene quella già presente. La modifica dei valori iniziali incide sui nuovi utilizzi del personaggio. Gli studenti che hanno già scelto il personaggio potrebbero avere vite, mana e progressi già salvati nel proprio profilo. ### Scelta del personaggio da parte dello studente Lo studente sceglie il personaggio dalla propria area, dopo aver selezionato la classe. La scelta è consentita solo se: - lo studente appartiene alla classe; - il personaggio appartiene alla classe selezionata; - lo studente non ha già scelto un personaggio. Quando lo studente sceglie il personaggio, il sistema salva il collegamento al personaggio e inizializza vite e mana con i valori impostati dal docente, se quei valori non erano già presenti nel profilo dello studente. ### Importazione ed esportazione personaggi Dal pulsante "Importa/Esporta" si accede alla pagina `/docenti/personaggi/import-export`. Funzioni disponibili: - esportare un personaggio originale della classe in formato `.zip`; - importare un personaggio da archivio `.zip`; - importare un personaggio originale da un'altra classe. L'esportazione genera un archivio con: - dati del personaggio; - immagini collegate; - personalizzazioni associate al personaggio. L'importazione da file richiede un archivio `.zip` valido. Il personaggio importato viene collegato alla classe corrente. L'importazione da altra classe mostra i personaggi originali disponibili, con immagine, vita iniziale e mana iniziale. Confermando l'importazione, il sistema copia il personaggio nella classe attuale. ### Personalizzazioni collegate Quando un personaggio viene importato o esportato, possono essere incluse anche le personalizzazioni collegate al personaggio. Questo è importante perché alcune personalizzazioni, come capelli o equipaggiamenti, possono essere specifiche per un determinato personaggio. ### Note operative Prima di far scegliere i personaggi agli studenti è consigliato controllare: - numero di personaggi disponibili; - equilibrio tra vita iniziale e mana iniziale; - qualità dell'immagine principale; - presenza dell'immagine senza sfondo, se si usano personalizzazioni; - descrizione del personaggio. Una volta che gli studenti hanno scelto un personaggio, eventuali modifiche grafiche sono normalmente poco problematiche. Le modifiche ai valori iniziali vanno invece valutate con attenzione, perché gli studenti potrebbero avere già dati di gioco salvati. ## 14. Punizioni Il menu "Punizioni" contiene due pagine: - "Vedi punizioni", raggiungibile da `/docenti/punizioni`; - "Punizioni assegnate", raggiungibile da `/docenti/punizioni/assegnate`. Le punizioni sono attività aggiuntive assegnate agli studenti, in particolare quando uno studente perde tutte le vite o viene applicata la morte istantanea dalla dashboard docente. ### Punizioni disponibili La pagina `/docenti/punizioni` mostra le punizioni configurate per la classe selezionata. La tabella visualizza: - descrizione; - immagine; - giorni per la consegna; - azioni disponibili. ### Creazione punizione Per creare una nuova punizione premere "Aggiungi punizione". Campi richiesti: - descrizione della punizione; - giorni per la consegna; - immagine della punizione. Regole principali: - la descrizione è obbligatoria; - i giorni per la consegna devono essere almeno `1`; - l'immagine è obbligatoria in fase di creazione; - i formati immagine ammessi sono `png`, `jpg`, `jpeg`, `gif` e `webp`. La punizione viene collegata alla classe attualmente selezionata. ### Modifica punizione Il pulsante "Modifica" permette di aggiornare: - descrizione; - giorni per la consegna; - immagine. Se non viene caricata una nuova immagine, il sistema mantiene quella già presente. La modifica riguarda la punizione salvata nella classe. Prima di cambiare una punizione già usata, è opportuno controllare se è stata assegnata a studenti. ### Eliminazione punizione Una punizione può essere eliminata solo se appartiene alla classe corrente. Non è possibile eliminare una punizione già assegnata ad almeno uno studente. Quando l'eliminazione è consentita, il sistema rimuove: - la punizione; - l'immagine caricata collegata alla punizione. ### Importazione da altre classi Il pulsante "Importa da altre classi" permette di copiare nella classe corrente una punizione presente in un'altra classe. La finestra di import mostra: - descrizione; - immagine; - giorni per la consegna; - classe di origine; - anno scolastico. Non vengono proposte punizioni della stessa classe o punizioni con descrizione già presente nella classe corrente. La punizione importata viene copiata nella classe attuale e può essere usata nelle assegnazioni successive. ### Assegnazione dalla dashboard Le punizioni vengono assegnate dalla Dashboard docente quando uno studente arriva a zero vite o quando viene usata la funzione "Morte istantanea". La finestra di assegnazione permette tre modalità: - punizione casuale; - punizione esistente; - nuova punizione. Con la modalità casuale, il sistema sceglie una punizione disponibile per la classe che non risulti già assegnata allo studente. Con la modalità esistente, il docente seleziona una punizione già presente nella classe. Con la modalità nuova, il docente crea direttamente una nuova punizione indicando descrizione, giorni per la consegna ed eventuale immagine. Dopo l'assegnazione: - viene creato il collegamento tra studente e punizione; - viene calcolata la data di scadenza sommando i giorni per la consegna alla data corrente; - lo studente riceve una notifica; - le vite dello studente vengono riportate alle vite massime. ### Punizioni assegnate La pagina `/docenti/punizioni/assegnate` mostra le punizioni assegnate agli studenti della classe. La tabella visualizza: - nome studente; - cognome studente; - descrizione della punizione; - data di scadenza; - giorni per la consegna; - eventuale file consegnato. Se lo studente ha caricato una consegna, il docente può scaricarla dal pulsante dedicato. ### Consegna lato studente Lo studente vede le punizioni non ancora completate nella propria area, dalla pagina `/studenti/punizioni`. Per ogni punizione sono mostrati: - descrizione; - immagine; - data di scadenza; - area di caricamento della consegna. Quando lo studente carica un file: - il file viene salvato tra gli upload delle punizioni; - la punizione viene marcata come completata; - il link alla consegna viene salvato; - il docente riceve una notifica e può consultare la consegna dalla pagina delle punizioni assegnate. ### Note operative Le punizioni sono collegate alla classe selezionata. Prima di usarle è consigliato preparare un elenco coerente con le regole della classe, evitando descrizioni ambigue. Il numero di giorni per la consegna deve essere scelto in base al tipo di attività richiesta. Punizioni molto brevi possono diventare difficili da gestire; punizioni troppo lunghe perdono efficacia nel ciclo di gioco. Per evitare duplicati, l'import da altre classi esclude le punizioni che hanno già la stessa descrizione nella classe corrente. ## 15. Personalizzazioni La gestione delle personalizzazioni è disponibile dal menu laterale "Personalizzazioni". Il menu comprende più pagine: - gestione personalizzazioni: `/docenti/personalizzazioni`; - giornate sconti: `/docenti/personalizzazioni/giornate-sconti`; - personalizzazioni studenti: `/docenti/personalizzazioni/studenti`; - personalizzazioni in uso: `/docenti/personalizzazioni/in-uso`; - set personalizzazioni: `/docenti/personalizzazioni/set`. Le personalizzazioni sono elementi acquistabili o selezionabili dagli studenti per modificare l'aspetto del personaggio, dello sfondo o degli elementi collegati al profilo. ### Tipologie disponibili Le tipologie gestite sono: - `Sfondo`: sfondo dell'avatar; - `BigBackground`: sfondo principale del personaggio; - `Capelli`: personalizzazione legata al personaggio scelto; - `Personale`: immagine personale caricata dal docente o dallo studente; - `Equipaggiamento`: elemento equipaggiabile; - `Pet`: compagno/pet associabile allo studente. Alcune tipologie possono essere collegate a un personaggio specifico. In particolare `Capelli` ed `Equipaggiamento` possono essere limitati a un personaggio. ### Elenco personalizzazioni La pagina `/docenti/personalizzazioni` mostra le personalizzazioni disponibili per la classe selezionata. La tabella visualizza: - nome; - tipologia; - immagine; - costo; - personaggio collegato; - pulsante di modifica. È disponibile un filtro per tipologia. Le personalizzazioni create dagli studenti e collegate a uno studente specifico sono mostrate in sola lettura. ### Creazione personalizzazione Per creare una nuova personalizzazione premere "Aggiungi". Campi principali: - nome; - tipologia; - costo; - personaggio collegato; - descrizione; - suffisso costume; - immagine. Regole principali: - nome e tipologia sono obbligatori; - il costo deve essere maggiore o uguale a `0`; - l'immagine è obbligatoria in fase di creazione; - i formati immagine ammessi sono `jpg`, `jpeg`, `png`, `gif` e `webp`. Il percorso di salvataggio dell'immagine dipende dalla tipologia selezionata. ### Modifica personalizzazione In modifica è possibile aggiornare: - nome; - tipologia; - costo; - personaggio collegato; - descrizione; - suffisso costume; - immagine; - abilità, se la tipologia lo prevede. Se non viene caricata una nuova immagine, il sistema mantiene quella già presente. ### Equipaggiamento e pet Per le tipologie `Equipaggiamento` e `Pet` è possibile associare abilità. Le abilità vengono scelte da un elenco dedicato e salvate insieme alla personalizzazione. Gli effetti effettivi sono applicati lato studente quando l'oggetto viene equipaggiato o attivato, secondo le regole previste dal sistema. Ad esempio un'armatura può fornire scudi: gli scudi sono simili ai cuori, proteggono dalla perdita di vita e vengono consumati prima di perdere i cuori. Un'altra abilità può essere l'aumento di mana, un'altra l'aumento del mana guadagnato al passaggio di livello (per esempio da 2 a 3 mana). I pet possono dare la possibilità di aumentare la probabilità di uscita di forzieri epici e leggendari. ### Costumi Il pulsante "Aggiungi costume" permette di caricare immagini costume nella cartella dedicata ai costumi. Il costume non è una normale personalizzazione acquistabile dal negozio, ma un asset grafico usato nella composizione dell'immagine del personaggio. Il campo "suffisso costume" serve a collegare una personalizzazione al file costume corretto. Verranno quindi caricati i costumi collegati all'equipaggiamento che abbiano come prima parte il nome del personaggio e come seconda il suffisso inserito (comprensivo di estensione del file, ad esempio .jpg o .png) ### Giornate sconti La pagina `/docenti/personalizzazioni/giornate-sconti` permette di configurare sconti applicati al negozio degli studenti. Campi richiesti: - data dello sconto; - percentuale di sconto; - ricorrenza annuale; - motivazione. Regole principali: - la data deve essere valida; - lo sconto deve essere compreso tra `1` e `100`; - la motivazione è obbligatoria; - se la ricorrenza annuale è attiva, lo sconto si ripete ogni anno nella stessa data. Nella stessa pagina sono elencate le giornate già configurate, con possibilità di eliminarle. Quando uno sconto è attivo, nel negozio studente viene mostrata la percentuale applicata e il prezzo finale degli oggetti viene ricalcolato. ### Personalizzazioni caricate dagli studenti La pagina `/docenti/personalizzazioni/studenti` mostra le immagini personali caricate dagli studenti e ancora in attesa di approvazione, in modo da evitare immagini o nomi sconvenienti. Per ogni richiesta sono visibili: - studente; - nome della personalizzazione; - immagine; - pulsante di approvazione; - pulsante di rifiuto. Se la richiesta viene approvata: - la personalizzazione passa allo stato approvato; - viene associata allo studente; - lo studente riceve una notifica. Se la richiesta viene rifiutata: - la personalizzazione passa allo stato rifiutato; - lo studente riceve una notifica. ### Personalizzazioni in uso La pagina `/docenti/personalizzazioni/in-uso` permette di controllare le personalizzazioni possedute e attive per uno studente. È possibile selezionare uno studente della classe e visualizzare: - personalizzazioni attualmente in uso; - personalizzazioni possedute; - stato attivo o non attivo. Questa pagina è di consultazione. ### Set di personalizzazioni La pagina `/docenti/personalizzazioni/set` permette di creare e gestire set di personalizzazioni. Tipologie di set disponibili: - `Equipaggiamento`; - `Pet`; - `BigBackground`; - `Sfondo`. Per creare un set indicare: - nome set; - tipologia; - colore set. Dopo la creazione, il pulsante di assegnazione permette di collegare al set le personalizzazioni della stessa tipologia. La pagina consente anche: - esportare un set in formato `.zip`; - importare un set da archivio `.zip`. L'archivio contiene i dati del set, le personalizzazioni collegate e gli asset necessari. ### Negozio lato studente Gli studenti acquistano personalizzazioni dalla pagina `/studenti/personalizzazioni/negozio`. Nel negozio sono disponibili: - sfondi avatar; - sfondi personaggio; - capelli compatibili con il personaggio scelto; - pet; - caricamento di una personalizzazione personale. L'acquisto richiede monete sufficienti. Se è attiva una giornata sconti, il prezzo viene ridotto in base alla percentuale configurata. Il caricamento di una personalizzazione personale da parte dello studente costa `800` monete. Il file caricato deve essere un'immagine valida, con dimensione massima di 5 MB. L'immagine viene ridimensionata e ritagliata a 1080x1080 pixel prima del salvataggio. Le immagini caricate dagli studenti non diventano disponibili subito: devono essere approvate dal docente. ### Uso, vendita ed equipaggiamento lato studente Dalla pagina `/studenti/personalizzazioni`, lo studente può scegliere quali personalizzazioni possedute usare per: - sfondo; - sfondo personaggio; - capelli; - immagine personale; - pet. Lo studente può anche vendere personalizzazioni possedute. Il rimborso è parziale. Dalla pagina `/studenti/personalizzazioni/equipaggiamento`, lo studente può: - acquistare equipaggiamenti; - equipaggiare un oggetto posseduto; - vendere un equipaggiamento. Quando viene equipaggiato un oggetto, il sistema applica gli effetti previsti, ad esempio bonus collegati agli scudi o ad altre abilità configurate. ### Note operative Prima di rendere disponibili molte personalizzazioni è consigliato verificare: - coerenza tra tipologia e immagine; - costo in monete; - eventuale personaggio collegato; - abilità associate a pet ed equipaggiamenti; - presenza di set, se gli oggetti devono essere raggruppati. Le personalizzazioni incidono sull'esperienza visiva degli studenti e, per equipaggiamenti e pet, possono avere effetti di gioco. Conviene quindi mantenere prezzi e abilità bilanciati rispetto alle ricompense ottenibili nella classe. ## 16. Materiali La gestione dei materiali è disponibile dal menu laterale "Materiali", oppure dalla pagina `/docenti/materiali`. I materiali sono file caricati dal docente e collegati a un argomento. Possono essere usati come supporto negli esercizi delle quest. ### Elenco materiali La pagina mostra i materiali caricati dal docente corrente. La tabella visualizza: - nome materiale; - descrizione; - materia; - argomento; - azioni disponibili. Se il materiale ha un file collegato, il nome è un link apribile in una nuova scheda. I materiali sono ordinati per materia, argomento e nome. ### Argomenti disponibili Nel form di caricamento, l'elenco degli argomenti dipende dalle materie associate al docente. Un docente può caricare materiali solo per argomenti appartenenti alle proprie materie. Se al docente non sono associate materie o argomenti nella sezione Test Creator, non avrà elementi utili da selezionare nel campo argomento. ### Caricamento materiale Per caricare un nuovo materiale premere "Carica materiale". Campi richiesti: - nome materiale; - argomento; - descrizione; - file. Regole principali: - il nome è obbligatorio; - l'argomento è obbligatorio; - il file è obbligatorio in fase di creazione; - l'argomento deve appartenere a una materia associata al docente. Il file viene salvato nella cartella `public/assets/materiali`, dentro una sottocartella generata dal nome dell'argomento. ### Modifica materiale Il pulsante "Modifica" permette di aggiornare: - nome; - argomento; - descrizione; - file. Se non viene caricato un nuovo file, il sistema mantiene quello già presente. Se viene caricato un nuovo file, il file precedente viene sostituito e rimosso dal server. ### Eliminazione materiale Il pulsante "Elimina" rimuove il materiale e il file collegato. L'eliminazione è consentita solo se: - il materiale appartiene al docente corrente; - il materiale non è usato in esercizi. Un materiale non può essere eliminato se è collegato: - direttamente a un esercizio; - come materiale aggiuntivo nella tabella dei materiali dell'esercizio. ### Uso nelle quest Durante la creazione o modifica di un esercizio di una quest, il docente può associare materiali all'esercizio. I materiali disponibili dipendono dall'argomento selezionato per l'esercizio. Lo studente vede i materiali collegati nella pagina dell'esercizio, nella sezione dei materiali di supporto. Ogni materiale viene mostrato come link apribile. Oltre ai file caricati nella sezione "Materiali", l'esercizio può contenere anche link di supporto inseriti manualmente. ### Note operative È consigliato assegnare nomi chiari ai materiali, perché il nome viene mostrato anche agli studenti. Prima di eliminare o sostituire un file, verificare se è già stato usato in esercizi pubblicati o attivi. Per mantenere ordinata la libreria, conviene caricare i materiali già collegandoli all'argomento corretto. Questo semplifica la selezione durante la creazione degli esercizi delle quest. ## 17. Plugin La gestione generale dei plugin è disponibile dal menu utente in alto a destra, voce "Plugin", oppure dalla pagina `/docenti/plugin`. Questa sezione descrive solo la gestione generale dei plugin. Le funzioni specifiche dei singoli plugin sono descritte nelle sezioni dedicate. ### Scopo della pagina La pagina permette di: - vedere i plugin disponibili nel sistema; - attivare o disattivare un plugin per la classe selezionata; - configurare eventuali parametri specifici per la classe; - installare un nuovo plugin, solo se l'utente ha ruolo amministratore. La gestione lavora sempre sulla classe attualmente selezionata. ### Plugin della classe La tabella dei plugin mostra: - stato di attivazione per la classe; - nome del plugin; - codice plugin; - versione; - descrizione; - configurazione JSON per la classe. Un plugin può essere: - attivo globalmente e attivabile per la classe; - disattivato globalmente e quindi non attivabile dalla classe. Se un plugin è disattivato globalmente, il selettore di attivazione per la classe non è modificabile. ### Attivazione o disattivazione Per attivare un plugin nella classe: - selezionare la classe corretta; - aprire `/docenti/plugin`; - spuntare il plugin nella colonna di attivazione; - salvare. Per disattivarlo, togliere la spunta e salvare. L'attivazione vale solo per la classe corrente. Lo stesso plugin può essere attivo in una classe e non attivo in un'altra. ### Configurazione JSON Ogni plugin può avere una configurazione specifica per classe. La configurazione va inserita nel campo "Configurazione classe" in formato JSON. Esempio di struttura: ```json { "chiave": "valore" } ``` Il campo può essere lasciato vuoto se il plugin non richiede configurazioni. Al salvataggio, il sistema controlla che il JSON sia valido. Se il formato non è corretto, la configurazione non viene salvata. ### Voci di menu dei plugin Quando un plugin è attivo per la classe, può aggiungere voci dedicate nei menu docente e studente. Le voci dei plugin vengono mostrate solo se: - il plugin è attivo globalmente; - il plugin è attivo per la classe selezionata; - l'utente ha accesso all'area corretta; - il plugin espone una voce di menu per quell'area. Se un docente o uno studente tenta di aprire una pagina di plugin non attiva per la classe, il sistema blocca l'accesso e rimanda alla pagina corretta. ### Installazione di nuovi plugin La sezione di installazione è visibile solo agli amministratori. Per installare un nuovo plugin è necessario caricare un pacchetto `.zip`. Il pacchetto deve contenere un manifest valido, ad esempio: - `plugin.json`; - `manifest.json`; - `.chronoquest/plugin.json`. Il manifest deve indicare almeno: - nome plugin; - codice plugin; - versione; - descrizione; - eventuale configurazione; - eventuali rotte, menu o eventi gestiti dal plugin. Il codice plugin deve contenere solo lettere minuscole, numeri e underscore. Se il pacchetto contiene SQL di installazione, il sistema accetta solo istruzioni `CREATE TABLE` per tabelle con nome che inizi con `ct_plugin_`. ### File installabili Durante l'installazione, il sistema estrae solo file ammessi nelle cartelle previste dal plugin. Le aree previste includono: - codice PHP del plugin; - viste del plugin; - file CSS e JavaScript del plugin; - asset pubblici del plugin; - file di traduzione; - eventuale pacchetto caricato. Questa limitazione serve a evitare che un pacchetto plugin scriva file in aree non previste dell'applicazione. ### Note operative Prima di attivare un plugin in una classe è consigliato verificare: - che il plugin sia globalmente attivo; - che la classe selezionata sia quella corretta; - che l'eventuale configurazione JSON sia valida; - che docenti e studenti interessati abbiano accesso alla classe. I plugin possono modificare il comportamento del sistema, aggiungere pagine, menu o gestire eventi interni. Per questo è preferibile attivarli una classe alla volta e verificarne il funzionamento prima di usarli in modo esteso. ## 18. Test Creator: home, materie e argomenti Test Creator è l'area dedicata alla preparazione e gestione dei contenuti per test, esercizi e materiali collegati alle materie. Le prime pagine da configurare sono: - home page di Test Creator; - materie; - argomenti. ### Home page di Test Creator La home page di Test Creator è raggiungibile da `/testcreator/begin`. Questa pagina mostra una panoramica iniziale delle materie assegnate al docente autenticato. Per ogni materia assegnata viene mostrata una riga nella tabella con: - nome della materia; - azioni disponibili. Dalla home il docente può rimuovere l'associazione con una materia tramite il pulsante di disassegnazione. Se non sono presenti materie assegnate, la tabella non contiene elementi operativi. In questo caso è necessario passare dalla pagina delle materie e assegnare almeno una materia al proprio account. ### Materie La pagina delle materie è raggiungibile da `/testcreator/materie`. Questa pagina serve a consultare l'elenco delle materie disponibili e a scegliere quali materie associare al proprio account docente. La tabella mostra: - nome della materia; - stato di assegnazione al docente; - azioni disponibili. Una materia può essere: - assegnata al docente corrente; - non assegnata al docente corrente. Per lavorare sui contenuti collegati a una materia, il docente deve prima assegnarla al proprio account. ### Assegnazione e disassegnazione delle materie Per assegnare una materia: - aprire `/testcreator/materie`; - individuare la materia desiderata; - usare il comando di assegnazione. Dopo l'assegnazione, la materia diventa disponibile nella home di Test Creator e nelle pagine successive collegate ai contenuti. Per rimuovere una materia dal proprio account: - aprire la home di Test Creator oppure la pagina delle materie; - usare il comando di disassegnazione. La disassegnazione rimuove il collegamento tra docente e materia, ma non elimina la materia dal sistema. ### Gestione amministrativa delle materie Le funzioni di creazione, modifica, eliminazione, importazione ed esportazione delle materie sono riservate all'amministratore. L'amministratore può: - creare una nuova materia; - modificare il nome di una materia esistente; - esportare una materia in formato JSON; - importare una materia da file JSON; - eliminare una materia, se non è collegata a contenuti che ne bloccano la cancellazione. Il nome della materia è obbligatorio e non può superare 255 caratteri. L'eliminazione di una materia viene bloccata se la materia contiene argomenti o quiz collegati. ### Importazione ed esportazione JSON L'esportazione JSON permette di scaricare una materia con i dati collegati previsti dal sistema. L'importazione JSON permette di caricare una materia da un file `.json` compatibile. Queste funzioni sono pensate per trasferire o riutilizzare strutture di materie già preparate. Prima di importare un file è necessario verificare che il JSON sia valido e coerente con il formato previsto da Test Creator. ### Argomenti La pagina degli argomenti è raggiungibile da `/testcreator/argomenti`. Gli argomenti servono a suddividere una materia in unità più specifiche. Sono usati come riferimento per organizzare contenuti, domande, esercizi e materiali. La pagina mostra: - elenco degli argomenti; - materia collegata a ciascun argomento; - filtro per materia; - azioni di creazione, modifica ed eliminazione, in base ai permessi dell'utente. Il docente vede e gestisce gli argomenti delle materie a cui ha accesso. L'amministratore può vedere tutte le materie. ### Creazione e modifica degli argomenti Per creare un argomento: - aprire `/testcreator/argomenti`; - selezionare la materia; - inserire il nome dell'argomento; - salvare. Per modificare un argomento: - individuare l'argomento nella tabella; - aprire il comando di modifica; - correggere materia o nome; - salvare. Il nome dell'argomento è obbligatorio e non può superare 255 caratteri. Un docente non amministratore può creare o modificare argomenti solo nelle materie assegnate al proprio account. ### Eliminazione degli argomenti L'eliminazione degli argomenti è riservata all'amministratore. Un argomento può essere eliminato solo se non è collegato a materiali o esercizi. Se l'argomento non è eliminabile, il sistema mostra un messaggio con il motivo del blocco. Quando un argomento viene eliminato, vengono rimosse anche le domande collegate direttamente a quell'argomento. ### Note operative Prima di iniziare a creare contenuti in Test Creator è consigliato: - verificare di avere assegnato al proprio account le materie corrette; - creare o controllare gli argomenti principali di ogni materia; - evitare nomi duplicati o troppo generici; - usare il filtro per materia quando l'elenco degli argomenti diventa esteso. La struttura materie-argomenti è la base organizzativa delle sezioni successive di Test Creator. ## 19. Test Creator: domande La sezione domande di Test Creator permette di creare, modificare, importare, esportare e organizzare le domande collegate agli argomenti. La pagina principale è raggiungibile da `/testcreator/domande`. ### Scelta dell'argomento La pagina `/testcreator/domande` mostra l'elenco degli argomenti disponibili per il docente. La tabella contiene: - argomento; - materia collegata; - azione per visualizzare le domande. È possibile filtrare gli argomenti per materia. Il docente vede solo gli argomenti delle materie assegnate al proprio account. L'amministratore può accedere agli argomenti di tutte le materie. Per aprire l'archivio domande di un argomento, usare il comando di visualizzazione nella riga corrispondente. ### Elenco domande di un argomento L'elenco delle domande di un argomento è raggiungibile da: `/testcreator/domande/argomenti/{id_argomento}` La pagina mostra: - testo della domanda; - tipo di domanda; - libro di riferimento; - numero gruppo; - azioni disponibili. Da questa pagina il docente può: - tornare alla selezione degli argomenti; - creare una nuova domanda; - modificare una domanda esistente; - rimuovere una domanda dal proprio archivio; - eliminare definitivamente una domanda, se consentito. Le domande visualizzate sono quelle associate al docente corrente. ### Creazione di una domanda Per creare una domanda: - aprire l'argomento desiderato; - premere il comando per aggiungere una nuova domanda; - compilare i campi richiesti; - salvare. Campi principali: - testo della domanda; - punti; - livello di difficoltà, da 1 a 5; - numero gruppo: questo numero indica un gruppo di domande ed è utilizzato nella scelta casuale delle domande nella creazione dei quiz. Solo una domanda del gruppo viene scelta casualmente per l'inserimento nel quiz, mentre le altre non vengono usate. Utile quando si vogliono creare più quiz con una domanda dello stesso tipo diversa per ogni quiz; - numero righe di risposta; - libro di riferimento; - tipo di domanda; - eventuali risposte; - eventuale testo dell'esercizio numerico. All'interno dell'esercizio numerico, si possono usare i caratteri %% e ?? per inserire dei numeri casuali, in modo da creare esercizi uguali, ma con numeri diversi. Tra i caratteri %% e ?? vanno inseriti 2 numeri separati da virgola: verranno estratti dei numeri casuali compresi tra i 2 numeri. Se io scrivo, ad esempio, %%3,7?? lì verrà inserito un numero casuale tra 3 e 7, se scrivo %%10,20?? otterrò la stampa di un numero compreso tra 10 e 20. Il testo della domanda e il libro di riferimento sono obbligatori, ma come libro si può lasciare quello di default a nessuno. ### Tipi di domanda I tipi gestiti sono: - risposta aperta; - scelta multipla; - risposta multipla; - esercizio con numeri. Per le domande a risposta aperta è necessario indicare il numero di righe disponibili per la risposta. Per le domande a scelta multipla o risposta multipla è necessario inserire almeno due risposte. Le risposte corrette si indicano tramite la relativa casella di selezione. Per gli esercizi con numeri viene usato un campo testuale esteso, adatto a contenuti più strutturati. ### Modifica di una domanda Per modificare una domanda: - aprire l'elenco delle domande dell'argomento; - selezionare il comando di modifica; - aggiornare i campi necessari; - salvare. Durante la modifica il tipo di domanda non viene cambiato. Il sistema mantiene il tipo scelto in fase di creazione. Quando si modifica una domanda a scelta multipla o risposta multipla, le risposte vengono risalvate in base ai valori presenti nel form. ### Immagini nel testo della domanda L'editor permette il caricamento di immagini collegate alla domanda. Formati ammessi: - `jpg`; - `jpeg`; - `png`; - `gif`; - `webp`. Le immagini caricate vengono salvate nella cartella: `public/assets/images/Questions` Questa funzione è utile per formule, schemi, grafici o immagini necessarie alla comprensione della domanda. ### Rimozione dall'archivio del docente Il comando di rimozione elimina il collegamento tra il docente e la domanda. La domanda non viene necessariamente cancellata dal database: viene rimossa dall'archivio personale del docente corrente. Questa funzione è utile quando una domanda è stata importata o associata al docente ma non deve più comparire nel suo elenco. ### Eliminazione definitiva L'eliminazione definitiva rimuove la domanda dal sistema. È consentita solo se: - la domanda è stata creata dal docente corrente; - la domanda non è associata ad altri docenti; - la domanda non è collegata a quiz; - la domanda non è collegata a esercizi. Se uno di questi vincoli non è rispettato, il sistema blocca l'eliminazione e mostra un messaggio. L'eliminazione definitiva rimuove anche le risposte collegate alla domanda. ### Importazione domande da altri docenti La pagina di importazione è raggiungibile da `/testcreator/import-domande`. Da questa pagina il docente può: - scegliere l'argomento; - visualizzare le domande create da altri docenti sullo stesso argomento; - importare una domanda nel proprio archivio; - visualizzare un'anteprima delle risposte, quando disponibili. L'importazione non crea una nuova domanda duplicata. Associa la domanda esistente anche al docente che la importa. Le domande già presenti nell'archivio del docente non vengono mostrate come importabili. ### Importazione domande da CSV L'importazione da CSV è disponibile dalla pagina `/testcreator/import-domande/csv` oppure dalla pagina CSV di uno specifico argomento. Il file deve essere in formato `.csv` e non deve superare circa 500 KB. Il separatore previsto è il punto e virgola `;`. Struttura delle colonne: ```text domanda;tipo_domanda;risposta_1;risposta_2;risposta_3;risposta_4;risposta_5;risposta_6;meta;punti;argomento ``` Valori ammessi per `tipo_domanda`: - `risposta aperta`; - `scelta multipla`; - `risposta multipla`; - `esercizio con numeri`. Uso del campo `meta`: - per risposta aperta: numero di righe; - per scelta multipla: numero della risposta corretta; - per risposta multipla: numeri delle risposte corrette separati da virgola; - per esercizio con numeri: testo dell'esercizio. Se l'importazione viene avviata da uno specifico argomento, le domande vengono importate in quell'argomento. Se l'importazione viene avviata senza argomento, il sistema usa la colonna `argomento` del CSV e cerca una corrispondenza tra gli argomenti accessibili al docente. Le righe non valide vengono ignorate. Al termine il sistema indica quante domande sono state importate e quante righe sono state scartate. ### Esportazione domande in CSV La pagina di esportazione è raggiungibile da `/testcreator/esporta-domande`. Da questa pagina il docente può: - filtrare gli argomenti per materia; - selezionare uno o più argomenti; - esportare le domande in formato CSV. Il file esportato usa la stessa struttura prevista per l'importazione: ```text domanda;tipo_domanda;risposta_1;risposta_2;risposta_3;risposta_4;risposta_5;risposta_6;meta;punti;argomento ``` L'esportazione include solo le domande degli argomenti accessibili al docente. ### Note operative Prima di creare o importare domande è consigliato: - verificare che la materia sia assegnata al docente; - controllare che l'argomento sia corretto; - associare il libro di riferimento; - usare nomi e testi chiari; - indicare sempre le risposte corrette nei quesiti a scelta; - evitare eliminazioni definitive se la domanda è già stata usata in quiz o attività. Le domande create in questa sezione possono essere riutilizzate nelle funzioni successive di Test Creator e negli esercizi collegati alle quest. ## 20. Test Creator: quiz Il menu Quiz di Test Creator permette di creare verifiche a partire dalle domande già presenti nell'archivio del docente. La pagina principale è raggiungibile da `/testcreator/quiz`. ### Elenco quiz La pagina mostra i quiz creati dal docente autenticato. La tabella contiene: - nome del quiz; - numero di domande; - materia; - data di creazione; - azioni disponibili. Azioni principali: - generare il quiz; - modificare il quiz; - eliminare il quiz. Il numero di domande viene calcolato in modo diverso in base al tipo di quiz: - per quiz casuali: somma delle regole impostate per numero e tipo di domanda; - per quiz non casuali: numero di domande selezionate manualmente. ### Creazione di un quiz Per creare un quiz: - aprire `/testcreator/quiz`; - premere il comando di creazione; - inserire il nome del quiz; - selezionare la materia; - selezionare uno o più argomenti; - configurare le opzioni; - salvare. Il nome del quiz è obbligatorio e non può superare 255 caratteri. La materia deve essere assegnata al docente. Gli argomenti selezionabili dipendono dalla materia scelta. È obbligatorio selezionare almeno un argomento. ### Campi e opzioni del quiz Nel form di creazione o modifica sono disponibili questi campi: - nome quiz; - materia; - argomenti; - mostra punti delle domande; - mescola domande; - griglia di valutazione; - domande casuali; - mescola risposte; - regole per tipo di domanda. La griglia di valutazione è opzionale. Se selezionata, viene inclusa nella stampa del quiz. L'opzione "mostra punti" decide se visualizzare il punteggio delle singole domande nella stampa. L'opzione "mescola risposte" modifica l'ordine delle risposte nei quesiti con alternative. ### Quiz casuale Un quiz casuale genera automaticamente le domande a partire dagli argomenti selezionati. Per configurarlo è necessario indicare una o più regole: - tipo di domanda; - numero di domande da estrarre. Il tipo può essere: - qualsiasi tipo; - risposta aperta; - scelta multipla; - risposta multipla; - esercizio con numeri. Se una domanda ha un numero gruppo diverso da zero, il sistema considera quel gruppo nella selezione casuale e può estrarre una domanda per gruppo. Le domande estratte appartengono all'archivio del docente e agli argomenti selezionati nel quiz. ### Quiz con selezione manuale Se l'opzione "domande casuali" è disattivata, il quiz usa la selezione manuale delle domande. Dopo il salvataggio, il sistema apre la pagina: `/testcreator/quiz/{id_quiz}/domande-selezione` In questa pagina il docente può: - vedere le domande disponibili negli argomenti selezionati; - selezionare le domande da includere; - salvare la selezione. Il sistema accetta solo domande accessibili al docente e appartenenti agli argomenti del quiz. ### Modifica di un quiz Per modificare un quiz: - aprire `/testcreator/quiz`; - scegliere il quiz; - premere il comando di modifica; - aggiornare le impostazioni; - salvare. Durante la modifica: - la materia resta quella del quiz; - la modalità casuale o manuale resta quella scelta in fase di creazione; - argomenti, opzioni e regole possono essere aggiornati. Se il quiz è manuale, dopo la modifica può essere necessario ricontrollare la selezione delle domande. ### Generazione del quiz Il comando di generazione apre: `/testcreator/quiz/{id_quiz}/genera` La pagina mostra l'anteprima delle domande del quiz. Per un quiz casuale, il sistema estrae le domande secondo le regole configurate. Per un quiz manuale, il sistema usa le domande salvate nella selezione manuale. Se non sono disponibili domande compatibili con le impostazioni del quiz, viene mostrato un messaggio di errore. ### Stampa e PDF Dalla pagina di generazione sono disponibili: - stampa standard; - stampa DSA; - esportazione CSV; - stampa per co-correzione. La stampa standard genera il PDF del quiz. Il PDF viene generato usando intestazione e piè di pagina impostati nel template di stampa caricato e salvato. La stampa DSA permette di applicare opzioni specifiche: - riduzione del numero di domande del 20%; - riduzione delle risposte a tre alternative; - testo più grande; - font OpenDyslexic, se disponibile nel sistema, un font particolare pensato per migliorare la lettura di persone affette da dislessia. La stampa per co-correzione richiede il numero di codici da generare e produce un PDF dedicato alla gestione della co-correzione. ### Esportazione CSV del quiz L'esportazione CSV del quiz è disponibile dalla pagina di generazione. Il file esportato contiene le domande generate o selezionate, quando compatibili con il formato di esportazione. Le domande a scelta vengono esportate con risposte e risposta corretta. Le righe non compatibili con il formato richiesto possono essere escluse dall'esportazione. ### Eliminazione di un quiz Il comando di eliminazione rimuove il quiz del docente corrente. Vengono eliminati anche: - collegamenti agli argomenti; - regole per tipo di domanda; - eventuali domande selezionate manualmente. Le domande originali non vengono eliminate dall'archivio del docente. ### Note operative Prima di creare un quiz è consigliato: - verificare che la materia sia assegnata al docente; - controllare che gli argomenti contengano domande sufficienti; - scegliere se usare selezione casuale o manuale; - impostare regole coerenti con i tipi di domanda disponibili; - generare un'anteprima prima della stampa; - usare la stampa DSA solo quando serve una versione adattata. Il quiz dipende dalle domande presenti nell'archivio del docente. Se l'archivio è vuoto o non contiene domande per gli argomenti selezionati, la generazione non produce risultati utili. ## 21. Test Creator: libri e griglie di valutazione Il menu Test Creator include anche la gestione dei libri di testo e delle griglie di valutazione. I libri servono come riferimento bibliografico per le domande. Le griglie servono come allegato o criterio di valutazione nei quiz stampati. ### Libri La pagina dei libri è raggiungibile da `/testcreator/libri`. La tabella mostra: - titolo del libro; - casa editrice; - autori; - stato; - azioni disponibili. Lo stato può essere: - attivo; - disattivato. I libri attivi possono essere selezionati nelle domande come libro di riferimento. ### Creazione di un libro Per creare un libro: - aprire `/testcreator/libri`; - premere il comando per aggiungere un libro; - compilare i campi richiesti; - salvare. Campi richiesti: - titolo del libro; - casa editrice; - autori. I campi hanno lunghezza massima di 255 caratteri. ### Modifica di un libro Per modificare un libro: - aprire `/testcreator/libri`; - selezionare il comando di modifica; - aggiornare titolo, casa editrice o autori; - salvare. La modifica aggiorna il dato usato come riferimento nelle domande. ### Disattivazione di un libro Il comando di disattivazione imposta il libro come non attivo. La disattivazione non elimina il libro dal database e non rimuove i collegamenti già presenti nelle domande. Un libro disattivato resta visibile nella tabella con stato dedicato, ma non va usato per nuove domande. ### Griglie di valutazione La pagina delle griglie è raggiungibile da `/testcreator/griglie`. Le griglie sono personali del docente: ogni docente vede e gestisce le proprie griglie attive. La tabella mostra: - nome della griglia; - azioni disponibili. Azioni principali: - creare una nuova griglia; - modificare una griglia esistente; - eliminare una griglia. ### Creazione di una griglia Per creare una griglia: - aprire `/testcreator/griglie`; - premere il comando per aggiungere una nuova griglia; - inserire il nome; - compilare il contenuto della griglia; - salvare. Campi richiesti: - nome griglia; - contenuto della griglia. Il nome della griglia non può superare 40 caratteri. Il contenuto viene inserito tramite editor testuale e può contenere una struttura descrittiva o tabellare della valutazione. ### Modifica di una griglia Per modificare una griglia: - aprire `/testcreator/griglie`; - selezionare il comando di modifica; - aggiornare nome o contenuto; - salvare. La modifica è consentita solo al docente proprietario della griglia. ### Eliminazione di una griglia Il comando di eliminazione disattiva la griglia. La griglia non viene rimossa fisicamente dal database: viene impostata come non attiva e non compare più tra le griglie disponibili. ### Uso delle griglie nei quiz Durante la creazione o modifica di un quiz, il docente può selezionare una griglia di valutazione. Se una griglia è associata al quiz, il suo contenuto viene incluso nella stampa del quiz, inserita in fondo, come ultimo elemento delle pagine del quiz. Sono selezionabili solo le griglie attive del docente corrente. ### Note operative Prima di creare domande e quiz è consigliato: - inserire o controllare i libri di riferimento; - evitare duplicati inutili nell'archivio libri; - disattivare i libri non più usati invece di modificarli in modo improprio; - preparare griglie brevi e leggibili; - verificare l'anteprima di stampa del quiz quando viene associata una griglia. Libri e griglie non creano direttamente domande o quiz, ma rendono più ordinata la gestione dei contenuti e della valutazione. ## 22. Test Creator: template di stampa La pagina dei template di stampa permette di scegliere l'aspetto grafico usato nella stampa PDF dei quiz. La pagina è raggiungibile da `/testcreator/template-stampa`. ### Elenco template La tabella mostra i template disponibili nel sistema. Per ogni template viene mostrato: - nome del template; - stato di selezione; - azione di selezione. Il template selezionato viene salvato sull'account del docente corrente e viene usato nelle stampe successive dei quiz. Se il template selezionato non è più disponibile, il sistema usa un template di fallback. ### Selezione del template Per selezionare un template: - aprire `/testcreator/template-stampa`; - individuare il template desiderato; - premere il comando di selezione. Il template scelto viene registrato per il docente autenticato. La selezione non modifica i quiz già creati: incide sulla generazione della stampa quando il PDF viene prodotto. ### Struttura di un template I template sono cartelle presenti in: `public/assets/template` Ogni cartella rappresenta un template. Durante la stampa il sistema cerca questi file nella cartella del template: - `header.html`; - `intro.html`; - `footer.html`. Se un file non è presente, quella parte della stampa viene lasciata vuota. Il file `intro.html` viene usato come parte iniziale del documento. Il contenuto del quiz viene poi aggiunto dal sistema. ### Uso degli asset nel template I file HTML del template possono usare risorse presenti nella cartella del template, ad esempio immagini o file collegati. Il sistema normalizza i percorsi degli asset durante la generazione del PDF. Sono gestiti in particolare i riferimenti a: - `/assets/template/{nome_template}/`; - `./template/{nome_template}/`; - `/css/stampa.css`; - `../css/stampa.css`. In questo modo immagini e CSS possono essere risolti correttamente nella stampa PDF. ### Caricamento di un nuovo template Per caricare un nuovo template: - aprire `/testcreator/template-stampa`; - premere il comando di aggiunta template; - selezionare un file `.zip`; - salvare. Il file caricato deve essere uno ZIP valido. Lo ZIP deve contenere una sola cartella principale. Il nome di questa cartella diventa il nome del template. Durante il caricamento: - gli spazi nel nome della cartella vengono rimossi; - eventuali barre `/` o `\` vengono rimosse dal nome; - il template viene copiato in `public/assets/template`; - il caricamento viene bloccato se esiste già una cartella con lo stesso nome. ### Vincoli del caricamento Il caricamento viene rifiutato se: - non viene caricato alcun file; - il file non è in formato `.zip`; - lo ZIP non può essere estratto; - lo ZIP non contiene una sola cartella principale; - il nome della cartella non è valido; - esiste già un template con lo stesso nome; - la cartella di destinazione non è scrivibile. Non è prevista da questa pagina la cancellazione di un template già installato. ### Uso nei quiz Il template di stampa viene applicato quando si genera il PDF da: `/testcreator/quiz/{id_quiz}/stampa` Il template influisce su: - intestazione; - parte introduttiva; - piè di pagina; - eventuali immagini o stili inclusi nel template. Il contenuto delle domande, delle risposte e dell'eventuale griglia di valutazione viene invece generato dal sistema. ### Note operative Prima di caricare un template è consigliato: - verificare che lo ZIP contenga una sola cartella; - usare nomi cartella brevi e senza spazi; - includere `header.html`, `intro.html` e `footer.html` solo se necessari; - verificare che immagini e CSS usino percorsi compatibili; - generare una stampa di prova dopo la selezione. I template modificano solo l'aspetto del PDF. Non cambiano domande, risposte, punteggi o criteri di generazione del quiz. ## 23. Test Creator: importazione ed esportazione domande Test Creator permette di importare ed esportare domande per riutilizzare archivi già preparati o condividere contenuti tra docenti. Le funzioni principali sono: - importazione da altri docenti; - importazione da CSV; - esportazione in CSV. ### Menu di importazione La pagina principale di importazione è raggiungibile da `/testcreator/import-domande`. La pagina mostra gli argomenti disponibili per il docente, con filtro per materia. Per ogni argomento è disponibile il comando di importazione. Il docente vede solo gli argomenti delle materie assegnate al proprio account. ### Importazione da altri docenti L'importazione da altri docenti è disponibile da: `/testcreator/import-domande/argomenti/{id_argomento}/altri-docenti` La pagina mostra le domande create da altri docenti per lo stesso argomento. La tabella contiene: - testo della domanda; - tipo di domanda; - libro di riferimento; - autore; - azioni disponibili. Il docente può: - importare la domanda nel proprio archivio; - visualizzare le risposte, per domande a scelta multipla o risposta multipla. L'importazione non duplica la domanda nel database. Il sistema collega la domanda esistente anche all'archivio del docente che la importa. Le domande già associate al docente non vengono mostrate come importabili. ### Importazione da CSV L'importazione da CSV è raggiungibile da: `/testcreator/import-domande/csv` oppure, per uno specifico argomento: `/testcreator/import-domande/argomenti/{id_argomento}/csv` Il file deve essere in formato `.csv`. Il limite massimo del file è circa 500 KB. Il separatore previsto è il punto e virgola `;`. ### Importazione CSV su argomento specifico Se l'importazione viene avviata dalla pagina CSV di un argomento, tutte le domande valide vengono importate in quell'argomento. In questo caso la colonna `argomento` del CSV non è necessaria per determinare la destinazione. ### Importazione CSV con argomento automatico Se l'importazione viene avviata da `/testcreator/import-domande/csv`, il sistema usa la colonna `argomento` del CSV. Il nome dell'argomento viene confrontato con gli argomenti accessibili al docente. Se non viene trovata una corrispondenza, la riga viene ignorata. ### Struttura del CSV Il formato CSV e l'importazione possono essere sfruttati per far costruire le domande ad una IA, come chatGPT o similari. Basta specificare il tipo di domande che deve generare ed il formato in cui esse vadano generate e l'IA sarà in grado di creare un file CSV importabile direttamente in ChronoQuest. La struttura prevista è: ```text domanda;tipo_domanda;risposta_1;risposta_2;risposta_3;risposta_4;risposta_5;risposta_6;meta;punti;argomento ``` La prima riga può contenere l'intestazione. Campi: - `domanda`: testo della domanda; - `tipo_domanda`: tipo di domanda; - `risposta_1` - `risposta_6`: risposte disponibili, usate per domande a scelta; - `meta`: dato tecnico variabile in base al tipo di domanda; - `punti`: punteggio della domanda; - `argomento`: nome dell'argomento di destinazione, usato nell'importazione senza argomento specifico. ### Tipi di domanda nel CSV Valori ammessi per `tipo_domanda`: - `risposta aperta`; - `scelta multipla`; - `risposta multipla`; - `esercizio con numeri`. Se il tipo non è riconosciuto, il sistema tratta la riga come domanda a risposta aperta. ### Campo meta Il campo `meta` cambia significato in base al tipo: - risposta aperta: numero di righe disponibili per la risposta; - scelta multipla: numero della risposta corretta; - risposta multipla: numeri delle risposte corrette separati da virgola; - esercizio con numeri: testo dell'esercizio. Per domande a scelta multipla o risposta multipla sono richieste almeno due risposte. Per la risposta multipla deve essere indicata almeno una risposta corretta valida. ### Valori predefiniti in importazione CSV Durante l'importazione da CSV il sistema imposta alcuni valori in modo automatico: - numero gruppo: `0`, cioè nessun gruppo; - libro di riferimento: `1`, cioè nessuno; - livello di difficoltà: `3`, cioè media difficoltà; - data di creazione: data corrente; - proprietario: docente che esegue l'importazione. Le domande importate vengono associate all'archivio del docente. ### Righe ignorate Una riga viene ignorata se: - è vuota; - non contiene il testo della domanda; - ha meno di due risposte per domande a scelta; - non indica risposte corrette valide per risposta multipla; - non è possibile determinare l'argomento di destinazione; - si verifica un errore durante il salvataggio. Al termine dell'importazione il sistema indica quante domande sono state importate e quante righe sono state ignorate. ### Esportazione in CSV La pagina di esportazione è raggiungibile da `/testcreator/esporta-domande`. La pagina mostra gli argomenti accessibili al docente, con filtro per materia. Per esportare: - selezionare uno o più argomenti; - usare il comando di esportazione CSV. È possibile selezionare tutti gli argomenti filtrati o svuotare la selezione. ### Contenuto del CSV esportato Il CSV esportato usa la stessa struttura prevista per l'importazione: ```text domanda;tipo_domanda;risposta_1;risposta_2;risposta_3;risposta_4;risposta_5;risposta_6;meta;punti;argomento ``` L'esportazione include solo: - domande appartenenti agli argomenti selezionati; - domande accessibili al docente; - tipi domanda supportati dal formato CSV. Per domande a scelta, il campo `meta` contiene l'indice della risposta corretta o gli indici delle risposte corrette. Per domande aperte, il campo `meta` contiene il numero di righe. Per esercizi con numeri, il campo `meta` contiene il testo dell'esercizio. ### Note operative Prima di importare o esportare domande è consigliato: - verificare che le materie siano assegnate al docente; - controllare che gli argomenti esistano già; - usare il separatore `;` nel CSV; - mantenere i nomi degli argomenti coerenti; - controllare le risposte corrette prima dell'importazione; - fare una prova con poche righe prima di importare un archivio esteso. L'importazione ed esportazione non sostituiscono la revisione didattica delle domande: dopo l'importazione è opportuno controllare testi, risposte e punteggi dalla pagina delle domande. ## 24. Test Creator: le mie classi La voce "Le mie classi" del menu Test Creator rimanda a `/docenti/classi`. Questa voce non apre una funzione interna di Test Creator, ma riporta all'area base di ChronoQuest. Da questa pagina il docente può: - consultare le proprie classi; - creare o modificare classi, in base ai permessi; - selezionare una classe; - rientrare nella gestione ordinaria della classe. La funzione è utile quando il docente deve uscire dal flusso Test Creator e tornare alla gestione base di ChronoQuest. In alternativa può cliccare sul logo di ChronoQuest, che lo riporterà alla sezione docenti. ## 25. Test Creator: mail docenti La pagina "Mail docenti" è raggiungibile da `/testcreator/mail-docenti`. Questa sezione è visibile e utilizzabile solo dagli amministratori. Serve a gestire l'elenco delle email abilitate per i docenti che possono iscriversi alla piattaforma. ### Elenco email La tabella mostra: - indirizzo email; - azione di eliminazione. Gli indirizzi sono ordinati alfabeticamente. ### Aggiunta manuale Per aggiungere una email: - aprire `/testcreator/mail-docenti`; - premere il comando di aggiunta; - inserire l'indirizzo email; - salvare. Il sistema: - normalizza l'indirizzo in minuscolo; - verifica che il formato sia valido; - impedisce l'inserimento di duplicati. ### Importazione CSV L'amministratore può importare un file CSV contenente indirizzi email. Il sistema legge gli indirizzi dal file e accetta separatori `;` oppure `,`. Vengono importati solo valori con formato email valido. Attenzione: l'importazione CSV sostituisce l'elenco esistente. Prima di procedere è opportuno verificare che il file contenga tutti gli indirizzi da mantenere. ### Eliminazione email Il comando di eliminazione rimuove l'indirizzo dall'elenco delle email abilitate. Se l'indirizzo non esiste più, il sistema mostra un messaggio di errore. ### Note operative Questa sezione va usata per mantenere aggiornato l'elenco degli indirizzi autorizzati. Prima di importare un CSV è consigliato: - controllare che il file contenga solo email valide; - rimuovere righe vuote o dati non pertinenti; - verificare che l'elenco sia completo, perché l'importazione sostituisce quello precedente. ## 26. Test Creator: amministratori La pagina "Amministratori" è raggiungibile da `/testcreator/amministratori`. Questa sezione è visibile e utilizzabile solo dagli amministratori. Serve a gestire quali docenti hanno anche privilegi di amministratore. ### Elenco docenti La tabella mostra: - nome; - cognome; - username; - stato; - azioni disponibili. Lo stato può essere: - docente; - amministratore. ### Promozione ad amministratore Per assegnare i privilegi di amministratore: - aprire `/testcreator/amministratori`; - individuare il docente; - usare il comando di promozione. Il sistema aggiunge al docente anche il ruolo di amministratore. Se il docente è già amministratore, l'operazione non crea duplicati. ### Rimozione dei privilegi Per rimuovere i privilegi di amministratore: - aprire `/testcreator/amministratori`; - individuare l'utente amministratore; - usare il comando di rimozione privilegi. Il sistema rimuove il ruolo amministratore dall'utente selezionato. L'amministratore principale con ID utente `1` e username `admin` non può essere rimosso da questa pagina. ### Note operative La gestione amministratori modifica i permessi generali dell'utente. È consigliato assegnare il ruolo amministratore solo a docenti che devono gestire funzioni di configurazione, come: - materie; - template; - mail abilitate; - altri amministratori; - funzioni riservate del sistema. La rimozione dei privilegi non elimina l'utente e non rimuove il ruolo docente.