Gestione Esami - Plugin WordPress

Plugin per la gestione completa degli esami universitari durante il percorso accademico
Elaborato di Tesi Triennale in Ingegneria Informatica (L-8)
Università Telematica Mercatorum
Matricola: 0082301383
Studente: Lorenzo Guardabascio
Relatore: Prof. Rocco Pietrini

---

📋 Indice

• Introduzione
• Caratteristiche Principali
• Obiettivi del Progetto
• Tecnologie Utilizzate
• Architettura del Plugin
• Funzionalità Implementate
• Struttura del Database
• Installazione
• Utilizzo
• API e Integrazione
• Licenza

---

🎯 Introduzione

Gestione Esami è un plugin WordPress sviluppato come elaborato finale per il corso di laurea triennale in Ingegneria Informatica (L-8) presso l'Università Telematica Mercatorum.

Il plugin nasce dall'esigenza personale di gestire in modo efficiente e organizzato il percorso accademico universitario, fornendo strumenti per:

• Monitorare la percentuale di fruizione dei corsi
• Tracciare l'apertura e chiusura delle iscrizioni alle sessioni d'esame
• Gestire e visualizzare le date degli esami
• Organizzare materie, sessioni e appelli in un'unica interfaccia

Il progetto dimostra l'applicazione pratica delle competenze acquisite durante il percorso di studi, con particolare attenzione allo sviluppo web, alla gestione dei database e all'architettura software.

Demo Live

🌐 URL: https://gestionale-esami.l-g.cloud/

---

✨ Caratteristiche Principali

• 🎓 Gestione Sessioni: Creazione e organizzazione di sessioni d'esame con date di apertura e chiusura iscrizioni

• 📚 Gestione Materie: Tracciamento delle materie con stato di completamento e percentuale di fruizione

• 📅 Calendario Esami: Visualizzazione cronologica di tutti gli appelli d'esame

• 📊 Dashboard Interattiva: Interfaccia utente intuitiva con contatori e statistiche in tempo reale

• 🔐 Sistema Multi-Utente: Gestione personalizzata per ogni utente con dati isolati

• 📊 Statistiche Avanzate: Dashboard con grafici interattivi (medie, CFU, proiezioni, distribuzione voti)

• 📱 Responsive Design: Interfaccia completamente responsive e mobile-friendly

• ⚡ Operazioni AJAX: Tutte le operazioni CRUD senza ricaricamento pagina

• 📤 Import/Export: Funzionalità di esportazione e importazione dati calendario

• 📧 Sistema Notifiche Avanzato: Pannello alert personalizzabile con notifiche email configurabili

---

🎯 Obiettivi del Progetto

Questo plugin è stato sviluppato con i seguenti obiettivi accademici e tecnici:

Obiettivi Accademici

1. Applicare le conoscenze teoriche acquisite durante il corso di studi
2. Dimostrare competenze nell'analisi e progettazione software
3. Sviluppare una soluzione a un problema reale
4. Documentare il processo di sviluppo in ottica di tesi universitaria

Obiettivi Tecnici

1. Implementare un plugin WordPress seguendo le best practice
2. Creare un'architettura modulare e manutenibile
3. Gestire dati complessi tramite Custom Post Types e Meta Fields
4. Sviluppare un'interfaccia utente moderna e user-friendly
5. Implementare un sistema di gestione utenti con isolamento dati

---

🛠 Tecnologie Utilizzate

Backend

• PHP 7.4+ - Linguaggio di programmazione principale
• WordPress 5.9+ - CMS e framework base
• MySQL - Database relazionale per la gestione dati
• WordPress Custom Post Types - Per la gestione strutturata dei dati
• WordPress REST API - Per le operazioni asincrone

Frontend

• HTML5 - Struttura delle pagine
• CSS3 - Styling e layout responsive
• JavaScript (ES6+) - Logica client-side e interattività
• AJAX - Comunicazione asincrona con il server
• jQuery - Manipolazione DOM (legacy support WordPress)

Strumenti di Sviluppo

• Git - Version control system
• GitHub - Repository e collaborazione
• VS Code - Editor di codice
• Linux - Ambiente di sviluppo

---

🏗 Architettura del Plugin

Il plugin segue un'architettura modulare basata su classi PHP orientate agli oggetti:

Struttura File

gestione-esami/
│
├── gestione-esami.php              # File principale del plugin
├── uninstall.php                   # Script di disinstallazione
├── README.md                       # Documentazione
│
├── includes/                       # Classi PHP principali
│   ├── class-gestione-esami-db.php          # Gestione database e query
│   ├── class-gestione-esami-frontend.php    # Gestione frontend e routing
│   ├── class-gestione-esami-ajax.php        # Handler per richieste AJAX
│   ├── class-gestione-esami-settings.php    # Pagina impostazioni admin
│   ├── class-gestione-esami-shortcodes.php  # Gestione shortcode
│   ├── class-gestione-esami-notifications.php # Sistema notifiche email
│   ├── class-gestione-esami-statistics.php  # Calcoli statistici 
│   ├── notification-settings.php            # Pannello alert utente
│   ├── statistics-ajax-handlers.php         # Handler AJAX statistiche 
│   ├── statistics-shortcodes.php            # Shortcode statistiche 
│   ├── enqueue.php                          # Caricamento CSS/JS
│   └── template-functions.php               # Funzioni helper template
│
├── api/                            # API endpoints
│   ├── get_calendar_data.php      # Recupero dati calendario
│   ├── export_calendar.php        # Esportazione dati
│   └── import_calendar.php        # Importazione dati
│
├── templates/                      # Template HTML
│   ├── dashboard.php              # Template dashboard principale
│   ├── calendar.php               # Template calendario esami
│   ├── modal-templates/           # Template modali CRUD
│   └── template-gestione-esami.php # Template base
│
├── css/                           # Fogli di stile
│   ├── gestione-esami.css        # Stili principali
│   └── statistics.css            # Stili dashboard statistiche 
│
└── js/                            # Script JavaScript
    ├── gestione-esami.js         # Logica frontend
    └── statistics.js             # Gestione grafici Chart.js 

Classi Principali

1. Gestione_Esami_DB

Gestisce tutte le operazioni di database:

• Recupero sessioni utente
• Gestione materie (attive/completate)
• Gestione esami
• Query ottimizzate con post meta

2. Gestione_Esami_Frontend

Gestisce il frontend del plugin:

• Registrazione Custom Post Types (sessione, materia, esame)
• Routing delle pagine personalizzate
• Template loading

3. Gestione_Esami_Ajax

Handler per tutte le richieste AJAX:

• CRUD per sessioni
• CRUD per materie
• CRUD per esami
• Aggiornamento contatori in tempo reale
• Export/Import dati

4. Gestione_Esami_Settings

Pagina di amministrazione WordPress:

• Configurazione pagine del plugin
• Impostazioni generali
• Reset configurazione

5. Gestione_Esami_Shortcodes

Gestione shortcode WordPress:

• [gestione_esami_dashboard] - Dashboard principale
• [gestione_esami_calendar] - Calendario esami
• [gestione_esami_alert_panel] - Pannello avvisi e notifiche
• [gestione_esami_statistics] - Dashboard statistiche completa

6. Gestione_Esami_Notifications (v1.1.0)

Sistema completo di notifiche email:

• Invio automatico notifiche tramite WordPress Cron
• Template HTML responsive personalizzabili
• Gestione preferenze utente per ogni tipo di notifica
• Configurazione giorni di anticipo personalizzati
• Tre tipologie di notifiche: apertura sessioni, scadenze iscrizioni, promemoria esami

7. Gestione_Esami_Statistics (v1.2.0)

Sistema completo di statistiche e analisi:

• Calcolo media aritmetica e ponderata (CFU)
• Proiezione voto di laurea
• Distribuzione voti e trend progressivi
• CFU completati e percentuale avanzamento
• Tasso di superamento esami
• Analisi temporale (tempo medio tra esami, esami per sessione)
• Integrazione Chart.js 4.4.0 per grafici interattivi

---

🚀 Funzionalità Implementate

1. Gestione Sessioni d'Esame

• Creazione sessioni con nome, date apertura/chiusura iscrizioni
• Modifica sessioni esistenti
• Eliminazione sessioni con conferma
• Ordinamento personalizzato delle sessioni
• Visualizzazione stato sessione (attiva/chiusa)

2. Gestione Materie

• Aggiunta materie con percentuale di fruizione
• Tracciamento CFU per ogni materia
• Inserimento voto opzionale (18-30 e lode)
• Stato completamento (attiva/completata)
• Associazione a sessione specifica
• Statistiche e contatori automatici
• Integrazione statistiche: i voti delle materie confluiscono nei calcoli

3. Gestione Esami

• Creazione appelli con data e ora
• Associazione a materia e sessione
• Voto conseguito (opzionale)
• Stato esame (da sostenere/sostenuto)
• Calcolo automatico media voti

4. Dashboard Interattiva

• Contatori in tempo reale:
  • Sessioni totali
  • Materie attive
  • Esami da sostenere
  • Esami completati
  • Media voti
• Sezioni organizzate:
  • Lista sessioni
  • Materie attive
  • Materie completate
  • Esami da sostenere
  • Esami completati

5. Calendario Esami

• Visualizzazione cronologica degli esami
• Filtro per materia e sessione
• Ordinamento per data
• Indicatori visivi per esami passati/futuri

6. Import/Export

• Esportazione dati in formato JSON
• Importazione da file JSON
• Backup e restore dati utente

7. Sistema Notifiche Email (v1.1.0)

• Pannello Alert personalizzabile con shortcode [gestione_esami_alert_panel]
• Tre tipologie di notifiche configurabili:
  • Apertura sessioni: Avviso quando si aprono le iscrizioni
  • Scadenze iscrizioni: Email promemoria chiusura iscrizioni
  • Promemoria esami: Reminder per esami imminenti
• Configurazione granulare per utente:
  • Giorni di anticipo personalizzabili (0-30 giorni) per ogni tipo di notifica
  • Attivazione/disattivazione individuale di ogni tipo di avviso
  • Salvataggio preferenze tramite user meta WordPress
• Template HTML: Email per ogni tipologia di alert
• WordPress Cron: Invio automatico programmato

8. Statistiche e Grafici

• Dashboard Statistiche Completa con shortcode [gestione_esami_statistics]
• 6 KPI Cards principali:
  • Media Aritmetica voti (include voti materie)
  • Media Ponderata (pesata per CFU, include voti materie)
  • CFU Totali Completati
  • Proiezione Voto di Laurea
  • Tasso di Superamento Esami (%)
  • Tempo Medio tra Esami
• 4 Grafici Interattivi (Chart.js):
  • Grafico Lineare: Andamento media voti nel tempo
  • Grafico a Barre: Distribuzione voti (18-30L)
  • Grafico a Torta: CFU completati vs rimanenti
  • Grafico a Barre Orizzontali: Esami per sessione
• Calcoli Automatici:
  • Formula proiezione laurea: (Media Ponderata × 110) / 30
  • Gestione voti "30 e lode" normalizzati a 30
  • Aggregazione dati per sessione e timeline
  • Integrazione voti materie: i voti inseriti nelle materie completate sono inclusi nei calcoli statistici
• Design Responsive: Grafici adattivi per mobile e desktop
• Export Visuale: Grafici ottimizzati per stampa e presentazioni

---

🗄 Struttura del Database

Il plugin utilizza i Custom Post Types di WordPress invece di creare tabelle personalizzate, sfruttando l'architettura nativa di WordPress.

Custom Post Types

1. sessione

• Campi Post Standard:

  • post_title - Nome della sessione
  • post_author - ID utente proprietario

• Post Meta:

  • _user_id - ID utente (per query ottimizzate)
  • session_order - Ordine visualizzazione
  • data_apertura_iscrizioni - Data apertura iscrizioni
  • data_chiusura_iscrizioni - Data chiusura iscrizioni

2. materia

• Campi Post Standard:

  • post_title - Nome materia
  • post_author - ID utente proprietario

• Post Meta:

  • _user_id - ID utente
  • _session_id - ID sessione associata
  • _cfu - Crediti formativi
  • _percentage - Percentuale fruizione corso
  • _completed - Stato completamento (0/1)
  • _grade - Voto esame (opzionale, 18-30L)

3. esame

• Campi Post Standard:

  • post_title - Titolo esame (auto-generato)
  • post_author - ID utente proprietario

• Post Meta:

  • _user_id - ID utente
  • _subject_id - ID materia associata
  • _session_id - ID sessione associata
  • _exam_date - Data e ora esame
  • _grade - Voto conseguito (opzionale)
  • _completed - Stato esame (0/1)

Vantaggi dell'Approccio Custom Post Types

1. Integrazione nativa con WordPress
2. Nessuna tabella custom da gestire
3. Sfruttamento sistema di query WordPress (WP_Query)
4. Compatibilità con plugin terze parti
5. Scalabilità e performance ottimizzate
6. Gestione automatica trash/restore

---

📥 Installazione

Requisiti di Sistema

• WordPress 5.9 o superiore
• PHP 7.4 o superiore
• MySQL 5.6 o superiore
• Struttura permalink attiva (non "Plain")

Procedura di Installazione

1. Scarica il plugin

   git clone https://github.com/tuousername/gestione-esami.git

2. Carica nella directory plugin

   cp -r gestione-esami /percorso/wordpress/wp-content/plugins/

3. Attiva il plugin

   • Vai su WordPress Admin → Plugin
   • Cerca "Gestione Esami"
   • Clicca "Attiva"

4. Configurazione automatica

   • All'attivazione vengono create automaticamente le pagine:
     • /gestione-esami/ - Dashboard principale
     • /calendario-esami/ - Calendario esami
     • /login-esami/ - Pagina login personalizzata

5. Verifica permalink

   • Vai su Impostazioni → Permalink
   • Assicurati che NON sia impostato su "Plain"
   • Salva le modifiche

---

📖 Utilizzo

Per l'Utente Finale

1. Accesso al Sistema

   • Effettua il login su WordPress
   • Vai alla pagina /gestione-esami/

2. Creare una Sessione

   • Clicca su "Nuova Sessione"
   • Inserisci nome, data apertura e chiusura iscrizioni
   • Salva

3. Aggiungere una Materia

   • Nella sezione "Materie Attive" clicca "Nuova Materia"
   • Inserisci nome, CFU, percentuale fruizione
   • Seleziona la sessione di riferimento
   • Salva

4. Creare un Esame

   • Nella sezione "Esami da Sostenere" clicca "Nuovo Esame"
   • Seleziona materia e sessione
   • Inserisci data e ora esame
   • Salva

5. Segnare un Esame come Completato

   • Modifica l'esame
   • Inserisci il voto
   • Spunta "Esame sostenuto"
   • La media viene calcolata automaticamente

6. Gestione Notifiche Email (v1.1.0)

   • Vai su /impostazioni-notifiche-esami/
   • Attiva/disattiva notifiche specifiche
   • Scegli tra: scadenze, promemoria esami, conferme operazioni
   • Salva le tue preferenze

Per l'Amministratore

1. Configurazione Plugin

   • Vai su Impostazioni → Gestione Esami
   • Configura le pagine predefinite
   • Usa "Ripristina Pagine" se necessario

2. Gestione Utenti

   • Ogni utente ha i propri dati isolati
   • Gli admin possono accedere al backend

---

🔌 API e Integrazione

Shortcode Disponibili

[gestione_esami_dashboard]

Visualizza la dashboard completa con:

• Contatori statistiche
• Gestione sessioni
• Gestione materie
• Gestione esami

Utilizzo:

[gestione_esami_dashboard]

[gestione_esami_calendar]

Visualizza il calendario esami

Utilizzo:

[gestione_esami_calendar]

[gestione_esami_notification_settings] (v1.1.0)

Pannello per gestione preferenze notifiche email

Utilizzo:

[gestione_esami_notification_settings]

Endpoint AJAX

Tutti gli endpoint sono protetti e richiedono autenticazione WordPress.

Sessioni

• wp_ajax_create_session - Crea nuova sessione
• wp_ajax_edit_session - Modifica sessione
• wp_ajax_delete_session - Elimina sessione
• wp_ajax_get_sessions - Recupera lista sessioni

Materie

• wp_ajax_create_subject - Crea nuova materia
• wp_ajax_edit_subject - Modifica materia
• wp_ajax_delete_subject - Elimina materia
• wp_ajax_get_subjects - Recupera lista materie

Esami

• wp_ajax_create_exam - Crea nuovo esame
• wp_ajax_edit_exam - Modifica esame
• wp_ajax_delete_exam - Elimina esame
• wp_ajax_get_exams - Recupera lista esami

Utility

• wp_ajax_get_counters_html - Aggiorna contatori dashboard
• wp_ajax_get_calendar_data - Recupera dati calendario
• wp_ajax_export_calendar - Esporta dati
• wp_ajax_import_calendar - Importa dati

---

📚 Documentazione Tesi

Questo plugin fa parte dell'elaborato finale per la tesi triennale dal titolo:

"Sviluppo plugin WordPress per la gestione degli esami durante il percorso accademico"

Struttura dell'Elaborato

1. Introduzione

   • Obiettivi della tesi
   • Contesto e motivazioni del progetto
   • Metodologia adottata

2. Strumenti e tecnologie utilizzate

   • WordPress come CMS e piattaforma di sviluppo
   • Struttura e API dei plugin WordPress
   • Ambiente di sviluppo e controllo di versione con Git
   • Linguaggi e tecnologie web coinvolte

3. Analisi del problema e specifiche funzionali

   • Esigenze dell'utente
   • Funzionalità previste
   • Casi d'uso principali

4. Progettazione e sviluppo del plugin

   • Struttura del plugin
   • Interfaccia utente e gestione ruoli
   • Funzionalità implementate
   • Estensioni possibili e roadmap evolutiva

5. Conclusioni

   • Considerazioni finali
   • Obiettivi raggiunti
   • Sviluppi futuri

Sviluppo Incrementale

Il plugin viene sviluppato e pubblicato in modo incrementale, con commit regolari che documentano l'avanzamento del lavoro. Ogni fase di sviluppo è tracciata tramite Git per dimostrare il processo di evoluzione del software.

---

👨‍💻 Autore

Lorenzo Guardabascio

• Matricola: 0082301383
• Corso: Ingegneria Informatica (L-8)
• Università: Telematica Mercatorum
• Email: lorenzo.guardabascio@studenti.unimercatorum.it

Relatore

• Prof. Rocco Pietrini
• Email: rocco.pietrini@unimercatorum.it

---

📄 Licenza

Questo progetto è rilasciato sotto licenza GPL v2 o successiva.

Copyright (C) 2025 Lorenzo Guardabascio

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

---

🙏 Ringraziamenti

Si ringrazia:

• Il Prof. Rocco Pietrini per la supervisione
• L'Università Telematica Mercatorum per il supporto accademico
• La community WordPress per la documentazione e le risorse

---

📞 Supporto e Contatti

Per domande, suggerimenti o segnalazioni:

• Email: lorenzo.guardabascio@studenti.unimercatorum.it
• Demo: https://gestionale-esami.l-g.cloud/
• Repository: URL del repository Git

---

🔄 Changelog

Versione 1.1.0 (Ottobre 2025)

• ✨ Aggiunto sistema notifiche email automatiche
• 📧 Template HTML professionali per email
• ⏰ WordPress Cron Jobs per invii programmati
• ⚙️ Pannello preferenze notifiche utente
• 📄 Nuovo shortcode per impostazioni notifiche

Versione 1.0.0 (Ottobre 2025)

• Implementazione base del plugin
• Sistema di gestione sessioni, materie ed esami
• Dashboard interattiva con AJAX
• Calendario esami
• Sistema import/export
• Custom Post Types per gestione dati
• Sistema multi-utente con isolamento dati
• Interfaccia responsive
• Pagina impostazioni amministrazione

---

Questo README è parte integrante dell'elaborato di tesi e viene aggiornato durante lo sviluppo del progetto.