From 8551382c770e9dc1eb83336b4410494801ccf281 Mon Sep 17 00:00:00 2001 From: Francesco Manfredi Date: Thu, 16 Jul 2026 00:06:33 +0200 Subject: [PATCH] First version 2025.07.16 --- 01-introduzione.md | 105 +++++++++++++++++++++++++++ 02-panoramica-del-processo.md | 121 ++++++++++++++++++++++++++++++++ 03-primi-passi.md | 121 ++++++++++++++++++++++++++++++++ 04-anni-scolastici.md | 58 +++++++++++++++ 05-scuole.md | 69 ++++++++++++++++++ 06-aule-e-laboratori.md | 69 ++++++++++++++++++ 07-orari-e-campanella.md | 93 ++++++++++++++++++++++++ 08-materie.md | 62 ++++++++++++++++ 09-classi.md | 114 ++++++++++++++++++++++++++++++ 10-docenti.md | 98 ++++++++++++++++++++++++++ 11-spostamenti.md | 77 ++++++++++++++++++++ 12-raccolta-preferenze.md | 101 ++++++++++++++++++++++++++ 13-generazione-orario.md | 117 ++++++++++++++++++++++++++++++ 14-comprendere-i-punteggi.md | 87 +++++++++++++++++++++++ 15-revisione-orario.md | 113 +++++++++++++++++++++++++++++ 16-personalizzazione-orario.md | 82 ++++++++++++++++++++++ 17-esportazione.md | 67 ++++++++++++++++++ 18-buone-pratiche-e-problemi.md | 112 +++++++++++++++++++++++++++++ 19-glossario.md | 111 +++++++++++++++++++++++++++++ README.md | 63 +++++++++++++++++ 20 files changed, 1840 insertions(+) create mode 100644 01-introduzione.md create mode 100644 02-panoramica-del-processo.md create mode 100644 03-primi-passi.md create mode 100644 04-anni-scolastici.md create mode 100644 05-scuole.md create mode 100644 06-aule-e-laboratori.md create mode 100644 07-orari-e-campanella.md create mode 100644 08-materie.md create mode 100644 09-classi.md create mode 100644 10-docenti.md create mode 100644 11-spostamenti.md create mode 100644 12-raccolta-preferenze.md create mode 100644 13-generazione-orario.md create mode 100644 14-comprendere-i-punteggi.md create mode 100644 15-revisione-orario.md create mode 100644 16-personalizzazione-orario.md create mode 100644 17-esportazione.md create mode 100644 18-buone-pratiche-e-problemi.md create mode 100644 19-glossario.md create mode 100644 README.md diff --git a/01-introduzione.md b/01-introduzione.md new file mode 100644 index 0000000..ce23eb2 --- /dev/null +++ b/01-introduzione.md @@ -0,0 +1,105 @@ +# 1. Introduzione: cos'è questo sistema + +Questo capitolo spiega **a cosa serve** lo strumento, **perché** è pensato in +questo modo e introduce le **parole chiave** che userai in tutto il manuale. +Leggilo con calma: capire questi concetti ora ti farà risparmiare molto tempo +dopo. + +## Il problema: costruire l'orario di un istituto + +Costruire l'orario di una scuola è uno dei lavori più complessi dell'anno. +Bisogna incastrare centinaia di lezioni in modo che: + +- ogni classe abbia esattamente le ore previste per ciascuna materia; +- nessun docente sia in due classi nello stesso momento; +- si rispettino i limiti di ore giornaliere e le indisponibilità; +- i docenti che lavorano su più plessi abbiano il tempo di spostarsi; +- e, possibilmente, tutti siano contenti dell'orario che ricevono. + +Fatto a mano, questo lavoro richiede giorni e produce spesso soluzioni con troppi +"buchi", spostamenti inutili o preferenze ignorate. Questo sistema **automatizza** +la parte più faticosa — trovare una combinazione valida — lasciando a te il +controllo delle decisioni importanti. + +## Il contesto della scuola italiana + +Lo strumento è progettato per le scuole italiane, che funzionano in modo diverso +dalle università: + +- **Gli studenti restano nella loro aula.** Ogni classe (per esempio la "1ª A") + è un gruppo fisso di studenti che rimane nella stessa aula per la maggior parte + delle lezioni. +- **Sono i docenti a spostarsi.** I professori cambiano aula tra un'ora e l'altra + e, quando l'istituto ha più plessi, si spostano anche tra edifici diversi. +- **Un istituto può avere più scuole.** Il sistema gestisce più edifici (plessi) + e tiene conto dei **tempi di viaggio** tra di essi. + +Di conseguenza l'orario non deve ottimizzare solo la sequenza delle lezioni di +ogni classe, ma anche **i movimenti e la disponibilità dei docenti**. + +## Cosa fa lo strumento, in breve + +1. **Raccoglie i dati** della scuola: plessi, aule, orario delle campanelle, + materie, classi, monte ore e docenti. +2. **Raccoglie le preferenze** dei docenti (orari graditi, indisponibilità, sedi + preferite, giorno libero...). +3. **Genera automaticamente** uno o più orari con un motore di ottimizzazione. +4. **Valuta la qualità** di ogni orario con un punteggio, così puoi confrontare le + alternative. +5. Ti permette di **rivedere, correggere a mano ed esportare** l'orario scelto. + +> [Immagine: schermata iniziale del sistema con la barra laterale delle sezioni] +> — Didascalia: la home dello strumento, con le sezioni "Configuration" e +> "Timetable" nel menu a sinistra. + +## Vincoli obbligatori e preferenze: la distinzione più importante + +Tutto il funzionamento del sistema ruota intorno a due tipi di regole. Tienile +ben distinte fin da subito: + +- **Vincoli rigidi (obbligatori).** Regole che **devono** essere sempre + rispettate. Se anche una sola viene violata, l'orario non è valido. Esempi: il + monte ore di ogni materia, il divieto di doppia presenza di un docente, le + indisponibilità dichiarate, il tempo minimo per spostarsi tra plessi. +- **Preferenze (obiettivi di qualità).** Desideri che il sistema cerca di + soddisfare il più possibile, ma che **può sacrificare** se necessario per + trovare una soluzione valida. Esempi: preferire le ore del mattino, evitare i + "buchi", ridurre gli spostamenti, rispettare gli orari graditi da un docente. + +In pratica: i **vincoli rigidi** definiscono cosa è un orario *ammissibile*; le +**preferenze** definiscono cosa è un orario *buono*. Il motore prima trova una +soluzione ammissibile, poi la migliora sul fronte della qualità. + +## Vocabolario di base + +Questi termini ricorrono in tutto il manuale. Per la lista completa vedi il +[Glossario](19-glossario.md). + +| Termine | Significato | +|---------|-------------| +| **Anno scolastico** | Il periodo di riferimento (es. 2025-2026). Ogni dato appartiene a un anno. | +| **Scuola / plesso** | Un edificio dell'istituto, con indirizzo e posizione. | +| **Aula/laboratorio** | Una stanza speciale (palestra, laboratorio) richiesta da alcune materie. | +| **Slot orario** | Una casella "giorno + ora" della griglia (es. lunedì 3ª ora). | +| **Materia** | Una disciplina insegnata (Matematica, Italiano...). | +| **Classe** | Un gruppo fisso di studenti (es. 2ª B) che appartiene a una scuola. | +| **Monte ore** | Quante ore settimanali di una materia servono a una classe. | +| **Assegnazione docente** | Il legame "questo docente insegna questa materia a questa classe". | +| **Preferenza** | Un desiderio del docente trattato come obiettivo di qualità. | +| **Indisponibilità** | Un periodo in cui il docente non può proprio esserci (vincolo rigido). | +| **Versione di orario** | Un orario generato, con il suo punteggio e il suo stato (bozza/finale/archiviato). | + +## Cosa NON copre questo manuale + +Questo è un manuale d'uso per chi costruisce l'orario. Non tratta l'installazione, +la configurazione tecnica del server né lo sviluppo del software: per questi temi +esiste la documentazione tecnica nella cartella `docs/`. + +--- + +Ora che sai cosa fa lo strumento, vediamo l'intero processo dall'alto prima di +entrare nel dettaglio delle singole funzioni. + +--- + +[← Indice](README.md) · [Successivo: Panoramica dal dato all'orario finale →](02-panoramica-del-processo.md) diff --git a/02-panoramica-del-processo.md b/02-panoramica-del-processo.md new file mode 100644 index 0000000..a79d927 --- /dev/null +++ b/02-panoramica-del-processo.md @@ -0,0 +1,121 @@ +# 2. Panoramica: dal dato all'orario finale + +Prima di entrare nel dettaglio delle singole schermate, è utile avere in mente +**l'intero percorso**. Questo capitolo è la mappa del processo: mostra i passaggi +nell'ordine in cui li affronterai la prima volta e rimanda ai capitoli che li +approfondiscono. + +## La sequenza completa + +``` + PREPARA I DATI RACCOGLI GENERA E SCEGLI RIFINISCI + (Configurazione) PREFERENZE + ┌───────────────────┐ ┌───────────────┐ ┌────────────────────┐ ┌───────────────────┐ + │ Anno scolastico │ │ Crea campagna │ │ Configura e avvia │ │ Personalizza a │ + │ Scuole │──▶│ Invita docenti│──▶│ l'ottimizzatore │──▶│ mano (se serve) │ + │ Aule/laboratori │ │ Invia email │ │ │ │ │ + │ Orari/campanella │ │ Monitora le │ │ Confronta le │ │ Finalizza la │ + │ Materie │ │ risposte │ │ versioni e i │ │ versione scelta │ + │ Classi + monte ore│ │ │ │ punteggi │ │ │ + │ Docenti │ │ │ │ │ │ Esporta in foglio │ + │ Distanze/viaggi │ │ │ │ Scegli la migliore │ │ di calcolo │ + └───────────────────┘ └───────────────┘ └────────────────────┘ └───────────────────┘ +``` + +Le quattro fasi corrispondono alle quattro parti operative di questo manuale. + +## Fase 1 — Prepara i dati (Configurazione) + +È la fase più lunga, ma si fa **una volta sola** e negli anni successivi si +aggiorna solo ciò che cambia. Inserisci, in quest'ordine consigliato: + +1. **[Anno scolastico](04-anni-scolastici.md)** — crea l'anno di riferimento. + Tutto il resto sarà legato ad esso. +2. **[Scuole](05-scuole.md)** — gli edifici dell'istituto, con indirizzo e + posizione (serve per calcolare gli spostamenti). +3. **[Aule e laboratori](06-aule-e-laboratori.md)** — solo le stanze speciali + (palestra, laboratori) se alcune materie le richiedono. +4. **[Orari e campanella](07-orari-e-campanella.md)** — la griglia giorni × ore + di ciascuna scuola. +5. **[Materie](08-materie.md)** — l'elenco delle discipline. +6. **[Classi](09-classi.md)** — le classi con il **monte ore** per materia e + l'**assegnazione dei docenti** (chi insegna cosa a chi). È il cuore della + configurazione. +7. **[Docenti](10-docenti.md)** — l'anagrafica, i limiti (ore massime giornaliere, + giorno libero) ed eventuali indisponibilità. +8. **[Distanze e spostamenti](11-spostamenti.md)** — i tempi di viaggio tra i + plessi (necessari solo se l'istituto ha più scuole). + +> **Perché quest'ordine?** Ogni passo si appoggia ai precedenti: non puoi +> assegnare un docente a una classe se la classe non esiste, né definire il monte +> ore se non hai le materie. Seguire l'ordine evita di tornare indietro. + +## Fase 2 — Raccogli le preferenze dei docenti + +Questa fase è **facoltativa ma fortemente consigliata**: le preferenze migliorano +molto la qualità dell'orario e il gradimento dei docenti. + +- Crei una **campagna** per l'anno scolastico. +- Inviti i docenti e invii loro un'email con un link personale. +- Ogni docente compila un modulo con i propri orari graditi, indisponibilità, + sedi preferite, giorno libero, ecc. +- Tu **monitori** chi ha risposto. + +Vedi [Raccolta preferenze dei docenti](12-raccolta-preferenze.md). In alternativa, +puoi inserire le preferenze tu stesso dalla scheda del docente +([Docenti](10-docenti.md)). + +## Fase 3 — Genera e scegli + +Quando i dati sono pronti: + +1. Apri la pagina **[Generazione](13-generazione-orario.md)**, scegli l'ambito + (tutto l'istituto o un sottoinsieme), le impostazioni e avvii il motore. +2. Il sistema lavora e, al termine, restituisce **una o più versioni** di orario, + ciascuna con un **punteggio di qualità**. +3. Impari a leggere quei punteggi in [Comprendere i punteggi](14-comprendere-i-punteggi.md) + e confronti le versioni nella pagina di [Revisione](15-revisione-orario.md). + +## Fase 4 — Rifinisci, finalizza ed esporta + +- Se una versione è quasi perfetta ma ha qualche dettaglio da sistemare, la + **[personalizzi a mano](16-personalizzazione-orario.md)**: la modifica crea una + nuova bozza, senza toccare l'originale. +- Quando sei soddisfatto, **finalizzi** la versione scelta (diventa l'orario + ufficiale) dalla pagina di [Revisione](15-revisione-orario.md). +- Infine **[esporti](17-esportazione.md)** l'orario in Excel o OpenDocument per + distribuirlo e stamparlo. + +## Un processo iterativo, non lineare + +Nella realtà raramente si va dritti dall'inizio alla fine. È del tutto normale: + +- generare, guardare i punteggi, **cambiare qualche impostazione** e rigenerare; +- accorgersi che manca un dato, **tornare alla configurazione** e correggere; +- **personalizzare** una versione, valutarla e poi decidere. + +Lo strumento è pensato proprio per questo ciclo: *genera → valuta → correggi → +rigenera*. Non aver paura di creare più versioni: puoi sempre confrontarle ed +eliminare quelle che non servono. + +## Il tuo primo orario: percorso minimo + +Se vuoi arrivare rapidamente a un primo risultato, questo è il percorso essenziale: + +1. Crea l'anno scolastico e almeno una scuola. +2. Definisci l'orario delle campanelle per quella scuola. +3. Inserisci le materie e almeno una classe con il suo monte ore. +4. Inserisci i docenti e assegnali alle classi/materie. +5. Vai su **Generazione**, lascia le impostazioni predefinite e avvia. +6. Apri la versione prodotta in **Revisione** e osservala. + +Poi potrai raffinare aggiungendo preferenze, più classi e più plessi. + +--- + +Nel prossimo capitolo vediamo come accedere allo strumento e come è organizzata +l'interfaccia. + +--- + +[← Precedente: Introduzione](01-introduzione.md) · [Indice](README.md) · [Successivo: Primi passi →](03-primi-passi.md) diff --git a/03-primi-passi.md b/03-primi-passi.md new file mode 100644 index 0000000..9367eb4 --- /dev/null +++ b/03-primi-passi.md @@ -0,0 +1,121 @@ +# 3. Primi passi: accesso e interfaccia + +In questo capitolo impari ad **accedere** allo strumento e a **muoverti** +nell'interfaccia. Sono le poche nozioni pratiche che userai in ogni sessione di +lavoro. + +## Accedere al sistema + +Lo strumento si usa dal **browser** (Chrome, Firefox, Edge...). L'indirizzo web è +quello fornito da chi ha installato il sistema per il tuo istituto. + +1. Apri l'indirizzo del sistema nel browser. +2. Compare la pagina di **accesso** (Login). +3. Inserisci **nome utente e password** che ti sono stati forniti. +4. Premi **Accedi**. + +> [Immagine: pagina di login con i campi utente e password] — Didascalia: la +> schermata di accesso. Le credenziali sono fornite dall'amministratore del +> sistema. + +Alcune indicazioni utili: + +- **Non esiste una registrazione autonoma.** L'utente amministratore viene creato + al momento dell'installazione. Se non hai le credenziali, richiedile a chi + gestisce il sistema. +- **La sessione resta attiva** sul tuo browser finché non premi *Logout*. Su un + computer condiviso, esci sempre al termine del lavoro. +- Se dopo un po' di inattività ricevi di nuovo la richiesta di accesso, è normale: + reinserisci le credenziali. + +## La struttura dell'interfaccia + +Dopo l'accesso vedrai tre aree principali: + +``` +┌──────────────────────────────────────────────────────────────┐ +│ INTESTAZIONE: [titolo] [Lingua: EN/IT] [Logout] │ +├───────────────┬──────────────────────────────────────────────┤ +│ BARRA │ │ +│ LATERALE │ AREA CONTENUTO │ +│ │ │ +│ Configuration│ (qui compare la pagina selezionata) │ +│ • ... │ │ +│ Timetable │ │ +│ • ... │ │ +└───────────────┴──────────────────────────────────────────────┘ +``` + +- **Intestazione (in alto):** contiene il selettore della **lingua** e il pulsante + **Logout**. +- **Barra laterale (a sinistra):** il menu di navigazione, diviso in due sezioni + (vedi sotto). Clicca una voce per aprire la pagina corrispondente. +- **Area contenuto (al centro):** mostra la pagina selezionata, dove leggi e + modifichi i dati. + +> [Immagine: interfaccia completa con intestazione, barra laterale e area +> contenuto] — Didascalia: le tre aree dell'interfaccia. + +## Le due sezioni del menu + +La barra laterale è organizzata secondo il processo di lavoro descritto nella +[Panoramica](02-panoramica-del-processo.md): + +### Configuration (Configurazione) +Qui prepari tutti i dati della scuola: + +| Voce di menu | Pagina del manuale | +|--------------|--------------------| +| Academic Years | [Anni scolastici](04-anni-scolastici.md) | +| Schools | [Scuole](05-scuole.md) | +| Facilities | [Aule e laboratori](06-aule-e-laboratori.md) | +| Time Slots | [Orari e campanella](07-orari-e-campanella.md) | +| Subjects | [Materie](08-materie.md) | +| Class Groups | [Classi](09-classi.md) | +| Travel Matrix | [Distanze e spostamenti](11-spostamenti.md) | +| Teachers | [Docenti](10-docenti.md) | +| Preferences Campaign | [Raccolta preferenze](12-raccolta-preferenze.md) | + +### Timetable (Orario) +Qui generi e gestisci gli orari: + +| Voce di menu | Pagina del manuale | +|--------------|--------------------| +| Generate | [Generazione dell'orario](13-generazione-orario.md) | +| Review | [Revisione delle versioni](15-revisione-orario.md) | + +> **Nota.** Le voci dell'interfaccia sono qui riportate anche in inglese perché, +> a seconda della lingua impostata, potresti vederle in inglese o in italiano. + +## Cambiare la lingua + +In alto a destra c'è il **selettore della lingua** (EN / IT). Cliccalo per passare +tra **inglese** e **italiano**. La scelta cambia immediatamente tutte le etichette +dell'interfaccia. Puoi cambiarla in qualsiasi momento senza perdere i dati. + +## Elementi comuni a tutte le pagine + +Imparerai a riconoscere alcuni elementi che si ripetono ovunque: + +- **Pulsante "Nuovo/Aggiungi":** crea un nuovo elemento (una scuola, una classe...). +- **Icone di modifica ed eliminazione** accanto a ogni riga di un elenco. +- **Finestre di dialogo (modali):** si aprono sopra la pagina per creare o + modificare un elemento; si chiudono con *Salva* o *Chiudi*. +- **Messaggi di conferma (toast):** brevi avvisi che compaiono per confermare + un'operazione riuscita o segnalare un errore. +- **Doppia conferma per le eliminazioni:** le operazioni distruttive richiedono + una conferma esplicita, per evitare cancellazioni accidentali. + +## Uscire dal sistema + +Premi **Logout** nell'intestazione per terminare la sessione. Verrai riportato +alla pagina di accesso. + +--- + +Ora sei pronto a inserire i dati. Iniziamo dall'**anno scolastico**, il +contenitore a cui appartiene tutto il resto. + +--- + +[← Precedente: Panoramica](02-panoramica-del-processo.md) · [Indice](README.md) · [Successivo: Anni scolastici →](04-anni-scolastici.md) diff --git a/04-anni-scolastici.md b/04-anni-scolastici.md new file mode 100644 index 0000000..09f9ac0 --- /dev/null +++ b/04-anni-scolastici.md @@ -0,0 +1,58 @@ +# 4. Anni scolastici + +L'**anno scolastico** è il contenitore a cui appartiene ogni altro dato: scuole, +classi, orari, preferenze e versioni di orario sono sempre riferiti a un anno +preciso. Per questo è il **primo** elemento da creare. + +> Voce di menu: **Configuration → Academic Years**. + +## A cosa serve + +Definire l'anno (per esempio `2025/2026`) ti permette di: + +- tenere separati i dati di anni diversi (l'orario del 2024/2025 non si mescola con + quello del 2025/2026); +- **conservare lo storico**: gli anni passati restano consultabili; +- lavorare al nuovo orario mentre quello vecchio resta intatto. + +In quasi tutte le altre pagine sceglierai l'anno di riferimento da un menu a +tendina in alto: se quel menu è vuoto, è perché non hai ancora creato nessun anno +qui. + +## Creare un anno scolastico + +1. Apri **Academic Years** dal menu. +2. Clicca **+ New Academic Year** (Nuovo anno scolastico). +3. Inserisci l'**etichetta** dell'anno, per esempio `2025/2026`. + - Massimo 20 caratteri. + - Deve essere **univoca**: non possono esistere due anni con la stessa + etichetta. +4. Salva. + +> [Immagine: finestra di creazione di un nuovo anno scolastico] — Didascalia: il +> campo etichetta accetta un testo libero, tipicamente nel formato `AAAA/AAAA`. + +## Modificare o eliminare + +- **Modifica:** usa l'icona di modifica accanto all'anno per correggere + l'etichetta. +- **Elimina:** usa l'icona di eliminazione. Ti verrà chiesta una conferma. + +> **Attenzione.** Eliminare un anno scolastico ha effetti a cascata su tutto ciò +> che vi è collegato (classi, orari, versioni...). Elimina un anno solo se sei +> certo di non averne più bisogno. In generale conviene **conservare** gli anni +> passati come archivio. + +## Consiglio pratico + +Crea l'anno **prima** di iniziare qualsiasi altra configurazione. Se stai +preparando l'orario per il prossimo anno mentre quello corrente è ancora in uso, +crea semplicemente il nuovo anno: i due resteranno indipendenti. + +--- + +Con l'anno creato, il passo successivo è definire le **scuole** dell'istituto. + +--- + +[← Precedente: Primi passi](03-primi-passi.md) · [Indice](README.md) · [Successivo: Scuole →](05-scuole.md) diff --git a/05-scuole.md b/05-scuole.md new file mode 100644 index 0000000..45374a5 --- /dev/null +++ b/05-scuole.md @@ -0,0 +1,69 @@ +# 5. Scuole + +Una **scuola** (o plesso) è un edificio dell'istituto. Qui inserisci tutti gli +edifici in cui si svolgono le lezioni. Anche se il tuo istituto ha un solo +edificio, devi comunque crearne almeno uno. + +> Voce di menu: **Configuration → Schools**. + +## Perché le scuole sono importanti + +Le scuole sono il luogo dove esistono le aule e dove i docenti si spostano. La loro +**posizione geografica** è usata dal sistema per calcolare i **tempi di viaggio**: + +- da un plesso all'altro (per i docenti che insegnano su più sedi); +- da casa del docente a ciascun plesso. + +Questi tempi diventano poi vincoli e obiettivi durante la generazione (vedi +[Distanze e spostamenti](11-spostamenti.md) e +[Scheduling: gli spostamenti](02-panoramica-del-processo.md)). + +## Creare una scuola + +1. Apri **Schools** dal menu. +2. Clicca **+ New School** (Nuova scuola). +3. Compila i campi: + - **Nome** — es. `Liceo Scientifico`, `Sede centrale`, `Succursale Via Verdi`. + - **Indirizzo** — es. `Via Roma 1, 00100 Roma`. + - **Latitudine / Longitudine** *(facoltative)* — le coordinate geografiche, in + gradi decimali (es. `41.8902`, `12.4964`). +4. Salva. + +> [Immagine: finestra di creazione scuola con nome, indirizzo e coordinate] — +> Didascalia: le coordinate sono facoltative ma consigliate se l'istituto ha più +> plessi. + +## Coordinate: quando servono + +- **Un solo plesso:** le coordinate non incidono sull'orario; puoi lasciarle + vuote. +- **Più plessi:** le coordinate permettono al sistema di stimare automaticamente i + tempi di viaggio tra le sedi. In alternativa puoi inserire i tempi a mano nella + [Travel Matrix](11-spostamenti.md). + +Se non conosci le coordinate esatte, puoi ricavarle da una mappa online cercando +l'indirizzo, oppure lasciare che il sistema le stimi dall'indirizzo (funzione di +geocodifica descritta nel capitolo sugli spostamenti). + +## Modificare o eliminare + +- **Cerca** una scuola con la barra di ricerca quando l'elenco è lungo. +- **Modifica** con l'icona corrispondente per aggiornare nome, indirizzo o + coordinate. +- **Elimina** con doppia conferma. Non eliminare una scuola a cui sono già + collegate classi o aule, a meno che tu non voglia rimuoverle tutte. + +## Consiglio pratico + +Dai alle scuole nomi **chiari e distinguibili** (es. "Sede centrale" e "Succursale") +piuttosto che sigle criptiche: quei nomi compariranno nei filtri, nelle viste +dell'orario e nei file esportati. + +--- + +Definiti gli edifici, puoi (se necessario) censire le **aule e i laboratori** +speciali. + +--- + +[← Precedente: Anni scolastici](04-anni-scolastici.md) · [Indice](README.md) · [Successivo: Aule e laboratori →](06-aule-e-laboratori.md) diff --git a/06-aule-e-laboratori.md b/06-aule-e-laboratori.md new file mode 100644 index 0000000..aeda2ef --- /dev/null +++ b/06-aule-e-laboratori.md @@ -0,0 +1,69 @@ +# 6. Aule e laboratori + +Nel linguaggio dello strumento, una **facility** (aula o laboratorio speciale) è +una stanza a uso specifico — palestra, laboratorio di chimica, aula di musica, +biblioteca — che alcune materie **richiedono** e che non può essere usata da due +classi contemporaneamente. + +> Voce di menu: **Configuration → Facilities**. + +## Quando ti serve questa sezione + +Ricorda che, di norma, **ogni classe ha la propria aula fissa**: quella non va +inserita qui. Questa sezione serve **solo** per gli spazi condivisi e limitati, +per esempio: + +- la **palestra** (una sola, usata a turno da tante classi); +- i **laboratori** (informatica, chimica, fisica...); +- l'**aula magna**, l'aula di musica, ecc. + +Se nessuna materia della tua scuola richiede spazi speciali, puoi **saltare +completamente** questo capitolo. + +## Perché sono importanti per l'orario + +Il sistema tratta ogni facility come una risorsa limitata: durante la generazione +impone come **vincolo rigido** che una stessa aula/laboratorio non sia occupata da +due classi nello stesso momento. Così l'orario prodotto non manderà mai due classi +in palestra alla stessa ora. + +## Creare un'aula o un laboratorio + +1. Apri **Facilities** dal menu. +2. In alto puoi **filtrare per scuola** per vedere le facility di un plesso + specifico. +3. Clicca **+ New Facility** (Nuova facility). +4. Compila: + - **Scuola** — a quale plesso appartiene la stanza. + - **Nome** — es. `Palestra A`, `Laboratorio di Chimica`. + - **Tipo** — una parola chiave per la categoria, es. `gym`, `lab`, + `music_room`. Puoi scegliere un suggerimento o scriverne uno tuo (max 50 + caratteri). +5. Salva. + +> [Immagine: finestra di creazione facility con scuola, nome e tipo] — Didascalia: +> ogni facility appartiene a una scuola precisa. + +> **Attenzione.** La **scuola non è modificabile** dopo la creazione. Se sbagli +> plesso, elimina la facility e ricreala. + +## Collegare una facility a una materia + +Definire la facility è solo il primo passo: perché il sistema la usi, la materia +che la richiede deve essere collegata ad essa. Questo collegamento si imposta nella +gestione delle materie e delle classi — vedi [Materie](08-materie.md) e +[Classi](09-classi.md). + +## Modificare o eliminare + +- **Modifica** per aggiornare nome o tipo. +- **Elimina** con conferma. Verifica prima che nessuna materia dipenda ancora da + quella facility. + +--- + +Passiamo ora a definire **quando** si fa lezione: l'orario delle campanelle. + +--- + +[← Precedente: Scuole](05-scuole.md) · [Indice](README.md) · [Successivo: Orari e campanella →](07-orari-e-campanella.md) diff --git a/07-orari-e-campanella.md b/07-orari-e-campanella.md new file mode 100644 index 0000000..1ecd4ff --- /dev/null +++ b/07-orari-e-campanella.md @@ -0,0 +1,93 @@ +# 7. Orari e campanella + +Gli **slot orari** (Time Slots) definiscono la **griglia** temporale in cui il +sistema colloca le lezioni: quali giorni si fa lezione e in quali ore. In pratica, +qui riproduci l'**orario delle campanelle** di ciascuna scuola. + +> Voce di menu: **Configuration → Time Slots**. + +## Il concetto di slot + +Uno **slot** è la combinazione di un **giorno** e di un'**ora (periodo)**. Per +esempio: *lunedì, 1ª ora, 8:00–8:55*. L'insieme di tutti gli slot forma la griglia +vuota che l'ottimizzatore riempirà con le lezioni. + +``` + Lun Mar Mer Gio Ven + 1ª [8:00] [8:00] [8:00] [8:00] [8:00] + 2ª [8:55] [8:55] [8:55] [8:55] [8:55] + 3ª ... ... ... ... ... +``` + +Caratteristiche importanti: + +- Gli slot sono definiti **per scuola**: plessi diversi possono avere campanelle + diverse. +- Ogni slot appartiene a un **anno scolastico**. +- Ogni slot ha un **numero di periodo** (1 = prima ora), un **orario di inizio** e + una **durata**. + +## Prima di iniziare + +In alto nella pagina devi selezionare **l'anno scolastico** e la **scuola** di cui +vuoi definire gli orari. Finché non li scegli, la pagina ti invita a farlo e non +mostra alcuna griglia. + +> [Immagine: pagina Time Slots con i selettori di anno e scuola in alto] — +> Didascalia: gli slot mostrati dipendono dall'anno e dalla scuola selezionati. + +## Creare gli slot in blocco (consigliato) + +Il modo più veloce per impostare una giornata tipo è generare più slot in una volta: + +1. Clicca **+ Add Multiple Slots** (Aggiungi più slot). +2. Indica: + - **Orario di inizio** della prima ora (es. `08:00`); + - **Durata (minuti)** di ogni ora (es. `55` o `60`); + - **Numero di periodi** da creare (es. `6`); + - **Numero del primo periodo** (di solito `1`). +3. Conferma con **Add Slots**. + +Il sistema crea automaticamente gli slot consecutivi calcolando gli orari. Ripeti +l'operazione se alcuni giorni hanno un numero di ore diverso. + +> **Nota sulle pause.** Se vuoi rappresentare l'intervallo, imposta gli orari in +> modo che tra un'ora e l'altra resti il tempo dell'intervallo, oppure semplicemente +> non creare uno slot in corrispondenza della ricreazione. La griglia deve +> rispecchiare le ore in cui si fa **effettivamente lezione**. + +## Creare o modificare un singolo slot + +- **+ New Slot** crea un singolo slot: scegli numero di periodo, giorno, orario di + inizio e fine. +- L'icona di **modifica** su uno slot esistente permette di correggerne gli orari. +- L'icona di **eliminazione** lo rimuove. + +La pagina mostra un riepilogo del tipo *"X slot su Y periodi"* per aiutarti a +controllare la coerenza della griglia. + +## Perché la griglia è così importante + +La qualità dell'orario dipende molto dalla griglia: + +- Se definisci **poche ore**, il sistema potrebbe non riuscire a collocare tutto il + monte ore delle classi (orario **non ammissibile**). +- Se definisci **troppe ore** rispetto al necessario, il sistema avrà più libertà, + ma potrebbero comparire più "buchi" da gestire con le preferenze di compattezza. + +L'obiettivo è riprodurre fedelmente l'orario reale delle campanelle della scuola. + +## Consiglio pratico + +Definisci gli slot **coerentemente per tutte le scuole** coinvolte prima di +generare l'orario. Se un docente lavora su due plessi con campanelle sfasate, +è proprio grazie a questi orari che il sistema calcola se ha il tempo di spostarsi +(vedi [Distanze e spostamenti](11-spostamenti.md)). + +--- + +Definito il *quando*, passiamo al *cosa* si insegna: le materie. + +--- + +[← Precedente: Aule e laboratori](06-aule-e-laboratori.md) · [Indice](README.md) · [Successivo: Materie →](08-materie.md) diff --git a/08-materie.md b/08-materie.md new file mode 100644 index 0000000..df30f40 --- /dev/null +++ b/08-materie.md @@ -0,0 +1,62 @@ +# 8. Materie + +Le **materie** sono le discipline insegnate nell'istituto: Matematica, Italiano, +Storia, Educazione fisica, e così via. Sono un elenco condiviso da tutte le scuole +e da tutte le classi. + +> Voce di menu: **Configuration → Subjects**. + +## A cosa servono + +Le materie sono i "mattoni" che collegano le classi ai docenti: + +- ogni classe dichiara **quante ore** di ciascuna materia le servono (il monte ore, + vedi [Classi](09-classi.md)); +- ogni docente viene **assegnato** a insegnare una materia a una classe. + +Per questo le materie vanno create **prima** di configurare le classi e i docenti. + +## Creare una materia + +1. Apri **Subjects** dal menu. +2. Clicca **+ New Subject** (Nuova materia). +3. Compila: + - **Nome** — es. `Matematica`. + - **Codice** *(facoltativo)* — una sigla breve, es. `MAT`. Se lo usi deve + essere **univoco** (max 50 caratteri). +4. Salva. + +> [Immagine: finestra di creazione materia con nome e codice] — Didascalia: il +> codice è facoltativo ma utile per abbreviazioni e stampe compatte. + +## Come nominare le materie + +- Usa nomi **uniformi** in tutto l'istituto: scegli, per esempio, sempre + `Scienze` e non a volte `Scienze naturali`. Nomi diversi verrebbero trattati + come materie diverse. +- Se distingui articolazioni o indirizzi, considera se conviene creare materie + separate (es. `Matematica` e `Matematica applicata`) oppure gestirle come una + sola. Materie separate permettono monte ore e assegnazioni distinte. + +## Materie che richiedono un'aula speciale + +Se una materia si svolge in un laboratorio o in palestra, ricordati di aver +creato la relativa **facility** ([Aule e laboratori](06-aule-e-laboratori.md)): il +collegamento tra materia e spazio speciale garantisce che il sistema non assegni +due classi alla stessa risorsa nello stesso momento. + +## Modificare o eliminare + +- **Cerca**, **modifica** ed **elimina** con i controlli accanto a ciascuna + materia. +- Non eliminare una materia già usata nel monte ore delle classi o nelle + assegnazioni dei docenti, salvo tu voglia rimuovere anche quei collegamenti. + +--- + +Ora abbiamo tutti gli ingredienti di base. Il prossimo capitolo è il **cuore** +della configurazione: le classi, il loro monte ore e l'assegnazione dei docenti. + +--- + +[← Precedente: Orari e campanella](07-orari-e-campanella.md) · [Indice](README.md) · [Successivo: Classi →](09-classi.md) diff --git a/09-classi.md b/09-classi.md new file mode 100644 index 0000000..4e7a960 --- /dev/null +++ b/09-classi.md @@ -0,0 +1,114 @@ +# 9. Classi, monte ore e assegnazione docenti + +Questo è il **cuore** della configurazione. Una **classe** (Class Group) è un +gruppo fisso di studenti — per esempio la `1A` — che appartiene a una scuola e a un +anno scolastico. Su ogni classe definisci due cose fondamentali: + +1. il **monte ore**: quante ore settimanali le servono per ciascuna materia; +2. l'**assegnazione dei docenti**: chi insegna ciascuna materia a quella classe. + +> Voce di menu: **Configuration → Class Groups**. + +Da questi dati il sistema capisce **quante lezioni** deve collocare e **con quali +docenti**: sono le informazioni più importanti per la generazione. + +## Creare una classe + +1. Apri **Class Groups** dal menu. In alto seleziona l'**anno scolastico**; puoi + filtrare per **scuola**. +2. Clicca **+ New Class Group** (Nuova classe). +3. Compila: + - **Scuola** — a quale plesso appartiene la classe. + - **Nome** — es. `1A`, `3B` (max 20 caratteri). + - **Anno di corso (Year Level)** — il livello numerico, tipicamente da `1` a + `5`. +4. Salva. + +> [Immagine: finestra di creazione classe con scuola, nome e anno di corso] — +> Didascalia: la classe appartiene a una scuola e a un anno scolastico. + +> **Attenzione.** La **scuola non è modificabile** dopo la creazione della classe. + +## Il monte ore (Teachings / Requirements) + +Dopo aver creato la classe, apri la sua sezione **Teachings** (insegnamenti): +cliccando la voce corrispondente sulla riga della classe si apre la finestra +*"Teachings — 1A (2025/2026)"*. + +Qui definisci, materia per materia, quante ore settimanali servono alla classe: + +1. Aggiungi una **materia** tra quelle create in [Materie](08-materie.md). +2. Indica le **ore settimanali** (Weekly Lesson Hrs), es. `4` per Italiano. +3. Ripeti per tutte le materie della classe. + +Se non hai ancora definito nulla, vedrai il messaggio *"No requirements defined +yet"* (nessun monte ore definito). + +> **Regola fondamentale.** Il monte ore è un **vincolo rigido**: il sistema +> collocherà **esattamente** quel numero di ore per materia, né una di più né una +> di meno. Controlla bene i totali: la somma delle ore di tutte le materie è il +> numero di lezioni settimanali della classe, e deve poter entrare nella griglia +> oraria ([Orari e campanella](07-orari-e-campanella.md)). + +> [Immagine: finestra Teachings con l'elenco materie e le ore settimanali] — +> Didascalia: ogni riga è una materia con il suo monte ore. + +## L'assegnazione dei docenti + +Sempre nella sezione Teachings colleghi a ciascuna materia il **docente** che la +insegna a quella classe. È l'informazione che risponde alla domanda *"chi fa +Matematica in 1A?"*. + +- Per ogni materia della classe scegli il docente incaricato tra quelli inseriti in + [Docenti](10-docenti.md). +- Un docente può essere assegnato a più materie e a più classi. +- Se assegnando un docente si superano le sue ore massime settimanali, il sistema + ti avvisa: *"Il docente avrebbe N h/settimana ma il massimo è M h. Assegnare + comunque?"*. Puoi procedere o rivedere l'assegnazione. + +Quando tutte le materie hanno un docente, comparirà l'indicazione *"All subjects +have been assigned"* (tutte le materie sono assegnate). + +> **Perché è indispensabile.** Senza l'assegnazione dei docenti il sistema sa che +> servono, ad esempio, 4 ore di Italiano, ma non chi le tiene: non può generare +> l'orario. Verifica che **ogni** materia di **ogni** classe abbia il suo docente. + +## Strumenti per andare più veloce + +Configurare tante classi simili a mano è noioso. La pagina offre alcune scorciatoie: + +- **Clone from …** — copia nel gruppo corrente tutto il monte ore di un'altra + classe. Le materie già presenti non vengono duplicate. +- **Clone to …** — copia il monte ore della classe corrente verso una o più altre + classi selezionate. +- **Copy teachers from …** — copia le assegnazioni dei docenti da un'altra classe, + limitatamente alle materie presenti in entrambe. + +Flusso tipico: configuri **una** classe "modello" per ogni indirizzo/anno di +corso, poi usi *Clone to* e *Copy teachers from* per replicarla sulle sezioni +parallele, correggendo solo le differenze. + +> [Immagine: menu Clone from / Clone to / Copy teachers from] — Didascalia: gli +> strumenti di clonazione velocizzano la configurazione di classi simili. + +## Modificare o eliminare una classe + +- **Modifica** per correggere nome o anno di corso (non la scuola). +- **Elimina** con conferma: rimuove anche il monte ore e le assegnazioni collegate. + +## Lista di controllo prima di procedere + +Prima di passare oltre, verifica che per ogni classe: + +- [ ] siano definite **tutte** le materie con il monte ore corretto; +- [ ] la somma delle ore **entri** nella griglia oraria della scuola; +- [ ] **ogni** materia abbia un **docente assegnato**. + +--- + +Il prossimo capitolo riguarda proprio i **docenti**: anagrafica, limiti e +preferenze. + +--- + +[← Precedente: Materie](08-materie.md) · [Indice](README.md) · [Successivo: Docenti →](10-docenti.md) diff --git a/10-docenti.md b/10-docenti.md new file mode 100644 index 0000000..1531d15 --- /dev/null +++ b/10-docenti.md @@ -0,0 +1,98 @@ +# 10. Docenti e preferenze + +I **docenti** sono le persone che insegnano le materie alle classi. In questa +pagina gestisci la loro anagrafica, i limiti contrattuali e — se vuoi inserirle tu +stesso — le loro preferenze e indisponibilità. + +> Voce di menu: **Configuration → Teachers**. + +## Creare un docente + +1. Apri **Teachers** dal menu. +2. Clicca **+ New Teacher** (Nuovo docente). +3. Compila i dati principali: + - **Nome** e **Cognome** — es. `Mario` `Rossi`. + - **Email** — es. `mario.rossi@scuola.it`. Serve per inviargli l'invito a + compilare le preferenze (vedi [Raccolta preferenze](12-raccolta-preferenze.md)). + - **Ore settimanali massime (Max Weekly Hours)** — es. `18`. È il tetto di ore + che il docente può insegnare a settimana. + - **Giorno libero (Free Day)** *(facoltativo)* — il giorno della settimana che + il docente preferirebbe tenere libero. È una **preferenza**, non una garanzia. + - **Latitudine / Longitudine di casa** *(facoltative)* — la posizione + dell'abitazione, usata per stimare i tempi di spostamento casa→scuola. +4. Salva. + +> [Immagine: finestra di creazione docente con nome, email, ore massime e giorno +> libero] — Didascalia: l'email è necessaria per la raccolta delle preferenze. + +## Limiti che diventano vincoli rigidi + +Alcuni dati del docente sono trattati come **vincoli rigidi** in fase di +generazione: + +- le **ore settimanali massime** e le **ore giornaliere massime** non vengono mai + superate; +- le **indisponibilità** dichiarate (vedi sotto) sono assolute. + +Altri dati sono invece **preferenze** (obiettivi di qualità), come il **giorno +libero** o gli orari graditi: il sistema cerca di rispettarli, ma può derogare se +necessario per trovare una soluzione valida. Per la distinzione vedi +[Introduzione](01-introduzione.md#vincoli-obbligatori-e-preferenze-la-distinzione-più-importante). + +## Le preferenze del docente + +Ogni docente ha una sezione **Preferences** (preferenze), che apri dalla sua riga +nell'elenco (*"Preferences — Mario Rossi"*). Vi si trovano: + +1. **Preferenze sugli slot** — per ogni giorno e ora, il docente può indicare: + *neutrale*, *preferito*, *da evitare* oppure *non disponibile*. Possono anche + essere riferite a una classe specifica. +2. **Preferenze sulle sedi** — un ordine di gradimento tra i plessi (utile negli + istituti con più scuole). +3. **Caratteristiche dell'orario** — per esempio la preferenza per le ore del + **mattino** e la preferenza per un orario **compatto** (senza "buchi"). +4. **Indisponibilità assolute** — i periodi in cui il docente non può proprio + esserci: sono un **vincolo rigido**. + +> **Neutrale / preferito / da evitare / non disponibile.** Attenzione alla +> differenza: *"da evitare"* è una preferenza (il sistema cerca di rispettarla ma +> può ignorarla), mentre *"non disponibile"* e le indisponibilità assolute sono +> vincoli rigidi (mai violati). Usa "non disponibile" solo per impossibilità reali, +> altrimenti rischi di rendere l'orario impossibile da costruire. + +> [Immagine: editor delle preferenze del docente con la griglia giorni × ore] — +> Didascalia: la griglia degli slot permette di marcare ogni ora come preferita, +> da evitare o non disponibile. + +## Due modi per raccogliere le preferenze + +Hai due possibilità, che puoi anche combinare: + +1. **Inserimento diretto** — compili tu le preferenze dalla scheda del docente, + come appena descritto. Comodo per pochi docenti o per correzioni puntuali. +2. **Campagna di raccolta** — inviti i docenti a compilare da soli un modulo online + (vedi [Raccolta preferenze dei docenti](12-raccolta-preferenze.md)). Consigliato + quando i docenti sono molti. + +## Modificare o eliminare + +- **Cerca** un docente con la barra di ricerca. +- **Modifica** per aggiornare anagrafica, limiti o preferenze. +- **Elimina** con conferma. Se il docente è assegnato a delle classi, valuta prima + di rimuoverlo: quelle materie resterebbero senza insegnante. + +## Consiglio pratico + +Inserisci **ore massime realistiche** e usa le indisponibilità con parsimonia. La +causa più comune di un orario "impossibile da generare" sono limiti e +indisponibilità troppo stringenti che, sommati, non lasciano spazio a una +soluzione valida (vedi [Buone pratiche e problemi](18-buone-pratiche-e-problemi.md)). + +--- + +Se il tuo istituto ha più plessi, il prossimo passo è definire i tempi di +spostamento tra le sedi. + +--- + +[← Precedente: Classi](09-classi.md) · [Indice](README.md) · [Successivo: Distanze e spostamenti →](11-spostamenti.md) diff --git a/11-spostamenti.md b/11-spostamenti.md new file mode 100644 index 0000000..15f06a6 --- /dev/null +++ b/11-spostamenti.md @@ -0,0 +1,77 @@ +# 11. Distanze e spostamenti (Travel Matrix) + +Negli istituti con **più plessi**, alcuni docenti insegnano in sedi diverse anche +nella stessa giornata. Il sistema deve sapere **quanto tempo** serve per spostarsi +da una scuola all'altra, per non produrre orari impossibili (un docente che finisce +in un plesso e inizia subito in un altro lontano). + +> Voce di menu: **Configuration → Travel Matrix**. + +## Cosa gestisce questa pagina + +La **matrice dei tempi di viaggio** raccoglie i tempi di spostamento (in **minuti**) +tra le sedi: + +- **scuola → scuola**: quanto ci vuole per andare da un plesso a un altro; +- (in secondo piano) **casa del docente → scuola**: usato per favorire i docenti + vicini alle sedi in cui insegnano. + +> **Un solo plesso?** Se l'istituto ha un'unica scuola, questa pagina non ti serve: +> non ci sono spostamenti tra sedi da gestire. Puoi saltare il capitolo. + +## Come i tempi influenzano l'orario + +I tempi di viaggio entrano nella generazione in due modi (vedi +[Panoramica](02-panoramica-del-processo.md)): + +- **Come vincolo rigido:** tra due lezioni consecutive in plessi diversi deve + esserci **tempo sufficiente** per lo spostamento. Il sistema confronta i minuti di + viaggio con l'intervallo tra le due ore (definito dagli + [orari delle campanelle](07-orari-e-campanella.md)). +- **Come obiettivo di qualità:** a parità di altre condizioni, il sistema cerca di + **ridurre** gli spostamenti totali dei docenti e di preferire le sedi vicine a + casa loro. + +## Inserire i tempi di viaggio + +Per ogni coppia di scuole imposti il tempo di percorrenza: + +1. Apri **Travel Matrix**. +2. Scegli la scuola di partenza (**From**) e quella di arrivo (**To**). +3. Indica i **minuti di viaggio (Travel Minutes)**. +4. Salva. + +I filtri in alto (From / To, con l'opzione *"Anywhere"* per non filtrare) ti +aiutano a trovare rapidamente la coppia che ti interessa quando le scuole sono +molte. + +> [Immagine: tabella della Travel Matrix con le coppie di scuole e i minuti] — +> Didascalia: ogni riga rappresenta il tempo di viaggio tra due plessi. + +## Calcolo automatico (Recalculate) + +Se hai inserito le **coordinate geografiche** delle scuole +([Scuole](05-scuole.md)), puoi usare il pulsante **Recalculate** (Ricalcola) per +far **stimare automaticamente** i tempi al sistema, a partire dagli indirizzi e +dalle posizioni. + +> **Attenzione: sono stime.** Il calcolo automatico si basa su una stima della +> distanza e **non** conosce traffico, parcheggio o mezzi di trasporto. Controlla +> sempre i valori proposti e correggi a mano le tratte che conosci: pochi minuti in +> più o in meno possono fare la differenza tra un orario ammissibile e uno no. + +## Consiglio pratico + +Inserisci i tempi **in eccesso prudenziale** sulle tratte critiche. È preferibile +un margine di sicurezza in più (che al massimo rende l'orario leggermente meno +"compatto") piuttosto che un tempo troppo ottimistico che costringe un docente a +una corsa impossibile tra due plessi. + +--- + +Con questo si conclude la parte di **configurazione dei dati**. Il prossimo +capitolo apre la fase di **raccolta delle preferenze** dei docenti. + +--- + +[← Precedente: Docenti](10-docenti.md) · [Indice](README.md) · [Successivo: Raccolta preferenze →](12-raccolta-preferenze.md) diff --git a/12-raccolta-preferenze.md b/12-raccolta-preferenze.md new file mode 100644 index 0000000..836c922 --- /dev/null +++ b/12-raccolta-preferenze.md @@ -0,0 +1,101 @@ +# 12. Raccolta preferenze dei docenti + +Le preferenze dei docenti migliorano sensibilmente la qualità dell'orario e il suo +gradimento. Invece di raccoglierle su carta o via email e inserirle a mano, puoi +lanciare una **campagna**: il sistema invia a ogni docente un link personale per +compilare da solo le proprie preferenze. + +> Voce di menu: **Configuration → Preferences Campaign**. + +Questa fase è **facoltativa**: puoi generare un orario anche senza preferenze. Ma +è **fortemente consigliata**, perché è ciò che trasforma un orario semplicemente +"valido" in un orario "buono" per le persone. + +## Come funziona una campagna + +Il ciclo di vita di una campagna è lineare: + +``` +Crea → Invita i docenti → Invia le email → [I docenti rispondono] → Monitora le risposte +``` + +1. **Crea** una campagna per l'anno scolastico, dandole un nome. +2. **Invita** i docenti scegliendoli dall'elenco. +3. **Invia** le email: ogni docente riceve un link personale. +4. I docenti **compilano** il modulo online. +5. Tu **monitori** chi ha risposto e chi no. + +## Passo 1 — Creare la campagna + +1. Apri **Preferences Campaign** dal menu. +2. Crea una nuova campagna: scegli l'**anno scolastico** di riferimento e assegna + un **nome** riconoscibile (es. `Preferenze 2025/2026`). + +> [Immagine: creazione di una campagna con anno e nome] — Didascalia: ogni campagna +> è legata a un anno scolastico. + +## Passo 2 — Invitare i docenti + +Seleziona, dall'elenco dei docenti inseriti in [Docenti](10-docenti.md), quelli che +vuoi includere nella campagna. Puoi invitarli tutti o solo una parte (per esempio +solo i nuovi docenti, se gli altri hanno già fornito le preferenze). + +> **Requisito.** Ogni docente invitato deve avere un **indirizzo email valido** +> nella sua scheda: è lì che verrà recapitato il link. + +## Passo 3 — Inviare le email + +Con il comando di invio, il sistema spedisce a ciascun docente invitato un'email +con un **link personale e univoco**. Il link porta a un modulo online dedicato, +senza bisogno di username o password: il collegamento stesso identifica il docente. + +> **Privacy e sicurezza del link.** Il link è personale e va usato una sola volta. +> Invita i docenti a non condividerlo: chi possiede il link può compilare le +> preferenze a nome loro. + +## Passo 4 — Cosa compila il docente + +Il docente apre il link e trova un modulo semplice in cui può indicare, tra +l'altro: + +- l'**indirizzo di casa** (per il calcolo degli spostamenti); +- il **massimo di ore giornaliere** che preferisce; +- il **giorno libero** desiderato; +- le **preferenze sugli slot** (per ogni giorno/ora: preferito, da evitare, non + disponibile); +- l'**ordine di gradimento delle sedi**; +- le **caratteristiche dell'orario** (preferenza per il mattino, orario compatto); +- le **indisponibilità assolute**. + +Sono le stesse informazioni che potresti inserire tu dalla scheda del docente +([Docenti](10-docenti.md)); qui però le fornisce direttamente l'interessato. + +> [Immagine: il modulo online compilato dal docente] — Didascalia: il modulo è +> pensato per essere compilato in autonomia, anche da smartphone. + +## Passo 5 — Monitorare le risposte + +Aprendo il **dettaglio della campagna** vedi, per ciascun invitato, se ha già +risposto oppure no. Usa questa vista per: + +- sollecitare chi è in ritardo; +- decidere quando "chiudere" la raccolta e passare alla generazione. + +> **Non serve aspettare il 100%.** Puoi generare l'orario anche se non tutti hanno +> risposto: per i docenti senza preferenze il sistema semplicemente non avrà +> obiettivi da rispettare, ma l'orario resterà comunque valido. + +## In ambiente di prova + +Se il sistema è configurato in modalità di prova, le email potrebbero non essere +spedite davvero ma solo registrate. In tal caso rivolgiti a chi gestisce +l'installazione per ottenere i link o per attivare l'invio reale. + +--- + +Quando i dati sono pronti e (idealmente) le preferenze raccolte, sei pronto per il +momento più atteso: **generare l'orario**. + +--- + +[← Precedente: Distanze e spostamenti](11-spostamenti.md) · [Indice](README.md) · [Successivo: Generazione dell'orario →](13-generazione-orario.md) diff --git a/13-generazione-orario.md b/13-generazione-orario.md new file mode 100644 index 0000000..ea7179b --- /dev/null +++ b/13-generazione-orario.md @@ -0,0 +1,117 @@ +# 13. Generazione dell'orario + +È il momento in cui il sistema costruisce l'orario al posto tuo. In questa pagina +imposti l'ambito e le impostazioni, avvii il **motore di ottimizzazione** e ne +segui l'avanzamento in tempo reale. + +> Voce di menu: **Timetable → Generate**. + +## Prima di iniziare: la lista di controllo + +La generazione riesce solo se i dati sono completi. Verifica di aver definito: + +- [ ] l'**anno scolastico** ([cap. 4](04-anni-scolastici.md)); +- [ ] almeno una **scuola** ([cap. 5](05-scuole.md)); +- [ ] gli **orari delle campanelle** per ogni scuola ([cap. 7](07-orari-e-campanella.md)); +- [ ] le **materie** ([cap. 8](08-materie.md)); +- [ ] le **classi** con **monte ore** e **docenti assegnati** ([cap. 9](09-classi.md)); +- [ ] i **docenti** con i loro limiti ([cap. 10](10-docenti.md)); +- [ ] le **aule/laboratori** se richiesti ([cap. 6](06-aule-e-laboratori.md)); +- [ ] i **tempi di viaggio** se hai più plessi ([cap. 11](11-spostamenti.md)); +- [ ] (facoltativo) le **preferenze** dei docenti ([cap. 12](12-raccolta-preferenze.md)). + +## Come lavora il motore, in due parole + +Il motore prima cerca una soluzione che rispetti **tutti i vincoli rigidi** +(orario *ammissibile*), poi la **migliora** massimizzando le preferenze (orario +*di qualità*). Può trovare **più soluzioni** e proporti le migliori a confronto. +Non devi capire la matematica sottostante: ti basta configurare bene i dati e +scegliere quanto tempo concedergli. + +## Passo 1 — Scegliere l'anno e l'ambito + +1. Seleziona l'**anno scolastico** di destinazione. +2. Scegli l'**ambito (scope)**: + - **tutto l'istituto** (tutte le scuole e tutte le classi), oppure + - un **sottoinsieme** (alcune scuole o alcune classi). + +> **Ambito più stretto = calcolo più rapido.** Generare per una sola scuola alla +> volta è utile per fare prove veloci o per programmare in modo incrementale +> (generi e "congeli" una parte, poi procedi con il resto). + +## Passo 2 — Scegliere il preset e i pesi + +Un **preset** è una configurazione salvata che dice al sistema **quanto** dare +importanza a ciascun obiettivo di qualità (i **pesi**). + +- Per il **primo orario** lascia il **preset predefinito**: i pesi standard vanno + bene nella maggior parte dei casi. +- In seguito puoi creare preset personalizzati per dare più peso, ad esempio, alla + **riduzione degli spostamenti** o al **rispetto delle preferenze**. + +Passando il mouse sulle singole opzioni compaiono dei **suggerimenti** che spiegano +a cosa serve ciascun peso. Per capire *come* i pesi influenzano il risultato, leggi +[Comprendere i punteggi di qualità](14-comprendere-i-punteggi.md). + +> **Regola d'oro dei pesi.** I pesi sono **priorità relative**, non percentuali. +> Alzare il peso di un obiettivo lo fa preferire *a scapito* degli altri. Cambia +> **un peso alla volta** e rigenera, così capisci l'effetto di ciascuna modifica. + +> [Immagine: pagina Generate con selezione ambito, preset e pesi] — Didascalia: i +> suggerimenti a comparsa spiegano ogni opzione. + +## Passo 3 — Impostare le opzioni del solutore + +Le principali impostazioni tecniche sono: + +- **Tempo massimo (timeout):** per quanti secondi il motore può lavorare. Più tempo + gli concedi, migliore può essere la soluzione. Per istituti grandi, aumenta questo + valore. +- **Numero massimo di soluzioni:** quante alternative raccogliere per il confronto. + +Puoi partire dai valori predefiniti e regolarli in base ai risultati. + +## Passo 4 — Avviare e seguire l'avanzamento + +Premi **Generate** (Genera). Durante il lavoro vedrai un **avanzamento in tempo +reale**: + +- il numero di **soluzioni trovate** finora; +- la **qualità** (valore obiettivo) della migliore soluzione trovata; +- il **tempo trascorso**. + +> [Immagine: barra di avanzamento con soluzioni trovate e tempo trascorso] — +> Didascalia: puoi seguire il lavoro del motore mentre procede. + +Lascia la pagina aperta durante il calcolo. Se la connessione in tempo reale +dovesse interrompersi, il sistema continua comunque a lavorare e aggiorna lo stato +periodicamente. + +## Passo 5 — Leggere l'esito + +Al termine, il riepilogo mostra: + +- quante **soluzioni** sono state trovate; +- la **qualità** della migliore; +- quante **lezioni (voci di orario)** sono state collocate; +- il collegamento per **vedere l'orario** generato. + +Da qui passi alla pagina di [Revisione](15-revisione-orario.md), dove le versioni +prodotte si analizzano e si confrontano in dettaglio. + +## Se non trova soluzioni + +Se il motore **non trova alcuna soluzione**, quasi sempre significa che i vincoli +rigidi sono in conflitto (l'orario richiesto è *impossibile*, non solo difficile). +Le cause tipiche sono monte ore che non entra nella griglia, indisponibilità +eccessive o tempi di viaggio incompatibili. Trovi la diagnostica passo-passo in +[Buone pratiche e risoluzione dei problemi](18-buone-pratiche-e-problemi.md). + +--- + +Prima di confrontare le versioni, impariamo a **leggere i punteggi** che ne +misurano la qualità. + +--- + +[← Precedente: Raccolta preferenze](12-raccolta-preferenze.md) · [Indice](README.md) · [Successivo: Comprendere i punteggi →](14-comprendere-i-punteggi.md) diff --git a/14-comprendere-i-punteggi.md b/14-comprendere-i-punteggi.md new file mode 100644 index 0000000..87f1318 --- /dev/null +++ b/14-comprendere-i-punteggi.md @@ -0,0 +1,87 @@ +# 14. Comprendere i punteggi di qualità + +Ogni versione di orario generata riceve dei **punteggi** che ne misurano la +qualità. Capirli ti permette di **confrontare** le versioni e di scegliere con +consapevolezza, invece di affidarti all'impressione. Questo capitolo spiega cosa +significano, senza formule complicate. + +## Le due domande a cui rispondono i punteggi + +1. *L'orario è valido?* → lo dicono i **vincoli rigidi**. +2. *Quanto è buono?* → lo dice il **punteggio composito** e la sua scomposizione + per categoria. + +## Il punteggio composito (0–100) + +Il **punteggio composito** riassume la qualità complessiva in un unico numero da +**0 a 100**: più è alto, migliore è l'orario. È una **media pesata** dei singoli +obiettivi di qualità, dove i "pesi" sono quelli che hai scelto nel preset di +generazione ([cap. 13](13-generazione-orario.md)). + +> **La regola più importante.** Se un orario viola **anche un solo vincolo rigido**, +> il suo punteggio composito è forzato a **0**, indipendentemente da quanto sia +> buono sul resto. Un composito pari a 0 è quindi un campanello d'allarme: guarda +> subito la scheda dei **conflitti** ([cap. 15](15-revisione-orario.md#scheda-conflitti-conflicts)). + +> **Il composito è assoluto.** Ogni versione è valutata per conto proprio, non "in +> classifica" rispetto alle altre. Puoi quindi confrontare direttamente i compositi +> di due versioni: 82 è meglio di 75. + +## Le categorie di qualità + +Il composito nasce dalla combinazione di più **categorie**, ciascuna delle quali +misura un aspetto dell'orario con un valore da **0 a 1** (spesso mostrato come +percentuale): **1 = pienamente soddisfatta**, **0 = del tutto disattesa**. + +| Categoria | Cosa misura | +|-----------|-------------| +| **Slot preferiti** | Quanti degli orari *preferiti* dai docenti sono stati effettivamente usati. | +| **Slot da evitare** | Quanto si è riusciti a **non** usare gli orari che i docenti volevano evitare. | +| **Preferenza mattino** | Quanta parte delle lezioni cade al mattino, per chi lo preferisce. | +| **Orario compatto** | Quanto le lezioni di ogni docente sono consecutive, senza "buchi". | +| **Tempo di viaggio** | Quanto sono contenuti gli spostamenti tra plessi. | +| **Giorno libero** | Se il giorno libero preferito dal docente è stato rispettato. | +| **Distribuzione delle classi** | Quanto le ore di una stessa classe sono distribuite su più giorni (invece di ammassarsi). | +| **Tragitto casa-scuola** | Quanto è contenuto il tragitto da casa alle sedi. | + +> **Categorie non applicabili.** Se una categoria non riguarda un docente (per +> esempio non ha indicato un giorno libero), per lui quella categoria vale come +> pienamente soddisfatta e non penalizza il punteggio. + +## Dove leggi i punteggi + +- **Nella lista delle versioni** ([Revisione](15-revisione-orario.md)) vedi il + **composito** di ciascuna versione, utile per un confronto immediato. +- **Nella scheda "Scores"** del dettaglio vedi la **scomposizione per categoria** + con grafici a barre e radar, e anche il **dettaglio per singolo docente**. + +> [Immagine: scheda Scores con grafico a barre delle categorie e grafico radar] — +> Didascalia: la scomposizione mostra quali obiettivi sono soddisfatti e quali no. + +## Come usare i punteggi nella pratica + +- **Confronta due versioni** guardando prima il composito, poi le categorie: una + versione può avere composito più basso ma essere migliore proprio + sull'aspetto che a te sta più a cuore. +- **Individua il punto debole:** la categoria con il valore più basso ti dice cosa + migliorare. Se, ad esempio, "Orario compatto" è basso, aumenta il peso della + compattezza nel preset e rigenera. +- **Non inseguire il 100.** Gli obiettivi sono spesso in conflitto tra loro + (ridurre i buchi può aumentare gli spostamenti, e viceversa): un buon orario è un + **compromesso equilibrato**, non un punteggio perfetto ovunque. + +## Legame con i pesi della generazione + +I **pesi** scelti in fase di generazione decidono **quanto** ciascuna categoria +incide sul composito. Alzare il peso di una categoria spinge il motore a curarla di +più, tipicamente a scapito di altre. È il meccanismo con cui traduci le priorità +del tuo istituto in numeri. Rivedi [Generazione — pesi](13-generazione-orario.md#passo-2--scegliere-il-preset-e-i-pesi). + +--- + +Vediamo ora la pagina in cui tutti questi dati si consultano e si confrontano: la +Revisione. + +--- + +[← Precedente: Generazione dell'orario](13-generazione-orario.md) · [Indice](README.md) · [Successivo: Revisione e confronto →](15-revisione-orario.md) diff --git a/15-revisione-orario.md b/15-revisione-orario.md new file mode 100644 index 0000000..d068157 --- /dev/null +++ b/15-revisione-orario.md @@ -0,0 +1,113 @@ +# 15. Revisione e confronto delle versioni + +Dopo la generazione, la pagina di **Revisione** è il tuo centro di controllo: qui +vedi tutte le versioni di orario prodotte per un anno, le apri in dettaglio, le +confronti, e infine ne finalizzi una come orario ufficiale. + +> Voce di menu: **Timetable → Review**. + +## L'elenco delle versioni + +Selezionato l'anno scolastico, vedi l'elenco delle **versioni** generate. Per +ciascuna sono indicati: + +- il **punteggio composito** (0–100) — vedi [Comprendere i punteggi](14-comprendere-i-punteggi.md); +- lo **stato**: *bozza (draft)*, *finale (final)* o *archiviata (archived)*; +- la **data di creazione**. + +Espandendo una versione ne vedi una sintesi della valutazione. È qui che confronti +"a colpo d'occhio" le alternative prima di aprirne una. + +> [Immagine: elenco delle versioni con punteggio e stato] — Didascalia: ogni riga è +> una versione generata; il punteggio aiuta a confrontarle. + +## Gli stati di una versione + +| Stato | Significato | +|-------|-------------| +| **Bozza (draft)** | Versione di lavoro: può essere modificata, personalizzata o eliminata. | +| **Finale (final)** | La versione approvata come orario ufficiale; bloccata contro modifiche accidentali. | +| **Archiviata (archived)** | Versione conservata come storico, non più attiva. | + +## Il dettaglio di una versione + +Cliccando una versione ne apri il **dettaglio**, organizzato in quattro schede. + +### Scheda griglia (Grid) +È l'orario vero e proprio, in forma di tabella giorni × ore. Puoi **filtrare** la +vista per: + +- **classe** — l'orario di una singola classe; +- **docente** — l'orario di un singolo insegnante; +- **scuola** — l'orario di un plesso; +- **materia** o **giorno**. + +Ogni cella mostra l'assegnazione: materia, docente e — se prevista — l'aula/ +laboratorio. È la vista che userai di più per controllare "a occhio" l'orario. + +> [Immagine: scheda Grid con la tabella giorni × ore e i filtri] — Didascalia: +> cambia il filtro per vedere l'orario dal punto di vista di una classe o di un +> docente. + +### Scheda punteggi (Scores) +La scomposizione della qualità con grafici (barre e radar) e il **dettaglio per +docente**. Serve a capire i punti di forza e di debolezza della versione. Per +interpretarla, vedi [Comprendere i punteggi](14-comprendere-i-punteggi.md). + +### Scheda assegnazioni (Assignments) +Il riepilogo del **carico di lavoro** dei docenti: + +- ore totali settimanali per docente; +- distribuzione tra le classi; +- necessità di spostamento per chi insegna su più plessi. + +Utile per verificare che nessun docente sia sovraccarico e per controllare gli +spostamenti. + +### Scheda conflitti (Conflicts) +Elenca le eventuali **violazioni di vincoli rigidi**. Per una versione generata dal +motore **dovrebbe essere vuota**. Se contiene qualcosa (tipicamente dopo una +[personalizzazione manuale](16-personalizzazione-orario.md)), qui trovi +esattamente cosa non va — per esempio un docente in due classi contemporaneamente o +un monte ore non rispettato. + +> **Ricorda:** qualsiasi conflitto rigido porta il punteggio composito a **0**. +> Controlla questa scheda ogni volta che il composito è 0. + +## Confrontare le versioni + +Poiché l'elenco mostra tutte le versioni dello stesso anno, puoi confrontarle su: + +- il **composito** (qualità complessiva); +- le **categorie** di qualità (aprendo la scheda Scores di ciascuna); +- il **numero di lezioni collocate** e il carico dei docenti. + +Un metodo pratico: apri due versioni in due schede del browser e confrontane le +schede *Scores* e *Grid* fianco a fianco. + +## Finalizzare una versione + +Quando hai scelto l'orario definitivo, clicca **Finalize** (Finalizza) sulla +versione: + +- lo stato passa a **finale**; +- la versione viene **bloccata** contro ulteriori modifiche accidentali. + +Finalizza **solo** una versione priva di conflitti e che ti soddisfa: è il segnale +che quello è l'orario ufficiale. Se in seguito devi correggerla, usa la +[personalizzazione](16-personalizzazione-orario.md), che lavora su una copia. + +## Eliminare una versione + +Con **Delete** (Elimina) rimuovi una versione che non ti serve. L'operazione +richiede una **doppia conferma** per evitare cancellazioni accidentali. Elimina +liberamente le bozze scartate per tenere l'elenco pulito. + +--- + +Se una versione è quasi perfetta ma va ritoccata, il prossimo capitolo spiega come +modificarla a mano. + +--- + +[← Precedente: Comprendere i punteggi](14-comprendere-i-punteggi.md) · [Indice](README.md) · [Successivo: Personalizzazione manuale →](16-personalizzazione-orario.md) diff --git a/16-personalizzazione-orario.md b/16-personalizzazione-orario.md new file mode 100644 index 0000000..640a663 --- /dev/null +++ b/16-personalizzazione-orario.md @@ -0,0 +1,82 @@ +# 16. Personalizzazione manuale + +Anche il miglior orario automatico a volte va ritoccato: un cambio dell'ultimo +minuto, un caso particolare che il motore non poteva conoscere, una richiesta +sopraggiunta. La **personalizzazione** ti permette di modificare a mano una +versione mantenendo il pieno controllo. + +> Si apre con **Customize** (Personalizza) dalla pagina di +> [Revisione](15-revisione-orario.md) di una versione. + +## Il principio: si lavora su una copia + +Quando personalizzi una versione, il sistema **non** modifica l'originale: crea una +**nuova bozza** derivata da essa. Questo significa che: + +- l'orario di partenza resta **intatto** e sempre recuperabile; +- puoi fare esperimenti senza timore; +- puoi generare più varianti manuali e confrontarle come qualsiasi altra versione. + +> [Immagine: pagina Customize con la tabella delle assegnazioni modificabili] — +> Didascalia: le modifiche creano una nuova bozza, senza toccare la versione +> originale. + +## Cosa puoi fare + +Nella pagina di personalizzazione vedi **tutte le assegnazioni** (le singole +lezioni) in una tabella filtrabile e ordinabile. Su ciascuna puoi: + +- **Modificare** una lezione: cambiare lo **slot** (giorno/ora), il **docente** + oppure l'**aula/laboratorio**. +- **Rimuovere** una lezione: eliminare una specifica assegnazione. +- **Aggiungere** una lezione: inserire manualmente una nuova assegnazione. +- **Salvare** le modifiche: viene creata la **nuova bozza** derivata dall'originale. + +## Attenzione: le modifiche manuali non sono controllate in automatico + +Questo è il punto più importante da ricordare. + +> **Le modifiche manuali NON vengono ri-validate automaticamente.** Spostando una +> lezione potresti, senza accorgertene, creare un conflitto: due lezioni della +> stessa classe alla stessa ora, un docente in due posti insieme, un monte ore non +> più rispettato, un tempo di viaggio insufficiente. + +Per questo, **dopo** ogni sessione di modifiche: + +1. Salva la nuova bozza. +2. Aprila in [Revisione](15-revisione-orario.md) e controlla la **scheda + Conflitti**. +3. Usa la funzione di **validazione (Validate)** per verificare che non siano stati + introdotti conflitti rigidi. + +Se la scheda Conflitti è vuota e il punteggio composito non è 0, la tua versione +manuale è valida. + +## Quando personalizzare e quando rigenerare + +- **Personalizza** per **piccoli ritocchi**: spostare una o due lezioni, sostituire + un docente per una supplenza, cambiare un'aula. Sono interventi mirati che non + giustificano una nuova generazione. +- **Rigenera** ([cap. 13](13-generazione-orario.md)) quando i cambiamenti sono + **strutturali**: è cambiato il monte ore, si è aggiunta una classe o un docente, + sono cambiate molte preferenze. In questi casi conviene ripartire dal motore. + +## Un flusso di lavoro efficace + +Il modo migliore di usare lo strumento combina automatico e manuale: + +``` +Genera → Scegli la versione migliore → Personalizza i dettagli → Valida → Finalizza +``` + +Così sfrutti la potenza del motore per il grosso del lavoro e il tuo giudizio per +gli ultimi ritocchi. + +--- + +Quando la versione è pronta e finalizzata, l'ultimo passo è portarla fuori dal +sistema: l'esportazione. + +--- + +[← Precedente: Revisione e confronto](15-revisione-orario.md) · [Indice](README.md) · [Successivo: Esportazione →](17-esportazione.md) diff --git a/17-esportazione.md b/17-esportazione.md new file mode 100644 index 0000000..8f79334 --- /dev/null +++ b/17-esportazione.md @@ -0,0 +1,67 @@ +# 17. Esportazione in foglio di calcolo + +Una volta scelto (ed eventualmente rifinito e finalizzato) l'orario, dovrai +distribuirlo a docenti e classi, stamparlo e magari conservarlo negli archivi +della scuola. Lo strumento permette di **esportare** l'orario in un foglio di +calcolo pronto all'uso. + +## Formati disponibili + +Puoi esportare in due formati, entrambi apribili con i più comuni programmi da +ufficio: + +- **XLSX** — il formato di Microsoft Excel (apribile anche con LibreOffice, + Google Fogli, ecc.). +- **ODS** — il formato OpenDocument (LibreOffice/OpenOffice Calc). + +Scegli il formato in base al programma che usi abitualmente; il contenuto è +identico. + +## Da dove si esporta + +L'esportazione si avvia dalla pagina di [Revisione](15-revisione-orario.md) o dal +**dettaglio** della versione. Individua la versione che vuoi esportare e usa il +comando di esportazione, scegliendo il formato. + +> [Immagine: comando di esportazione con scelta del formato XLSX/ODS] — +> Didascalia: l'esportazione parte dalla versione selezionata. + +## Cosa contiene il file + +Il foglio di calcolo generato è organizzato per essere subito utilizzabile e +comprende: + +- un **foglio per ogni classe** — l'orario settimanale della classe, pronto da + affiggere o distribuire; +- un **foglio per ogni docente** — l'orario personale di ciascun insegnante; +- un **foglio di riepilogo** con i **punteggi di valutazione** della versione. + +In questo modo, dallo stesso file, ricavi sia i prospetti da consegnare alle classi +sia quelli individuali per i docenti. + +## Consigli per la distribuzione + +- **Esporta la versione finalizzata**, non una bozza di lavoro: eviti di far + circolare orari provvisori. +- Prima di stampare, dai un'occhiata all'**anteprima di stampa** del foglio di + calcolo e regola margini e orientamento (l'orizzontale spesso rende meglio per le + griglie settimanali). +- Conserva una copia del file di esportazione insieme alla documentazione + dell'anno: sarà un utile riferimento e punto di partenza per l'anno successivo. + +## E se devo ancora fare modifiche? + +Se dopo l'esportazione emerge la necessità di un cambiamento, **non** modificare il +foglio di calcolo: le modifiche fatte lì non tornano nel sistema e rischi di far +circolare versioni discordanti. Torna invece nello strumento, usa la +[personalizzazione](16-personalizzazione-orario.md), valida e **riesporta**. Il +file esportato deve sempre rispecchiare l'orario "ufficiale" presente nel sistema. + +--- + +Hai completato l'intero percorso: dai dati all'orario esportato. L'ultima parte del +manuale raccoglie consigli pratici e soluzioni ai problemi più comuni. + +--- + +[← Precedente: Personalizzazione manuale](16-personalizzazione-orario.md) · [Indice](README.md) · [Successivo: Buone pratiche e problemi →](18-buone-pratiche-e-problemi.md) diff --git a/18-buone-pratiche-e-problemi.md b/18-buone-pratiche-e-problemi.md new file mode 100644 index 0000000..f297b7a --- /dev/null +++ b/18-buone-pratiche-e-problemi.md @@ -0,0 +1,112 @@ +# 18. Buone pratiche e risoluzione dei problemi + +Questo capitolo raccoglie i consigli che fanno la differenza tra un orario faticoso +e uno costruito con serenità, e una guida ai problemi più comuni con le relative +soluzioni. + +## Buone pratiche per un ottimo orario + +### Cura i dati: è lì che si vince o si perde +La qualità dell'orario dipende quasi tutta dalla qualità dei dati in ingresso. +Prima di generare, verifica che: + +- il **monte ore** di ogni classe sia corretto e **entri** nella griglia oraria; +- **ogni** materia di **ogni** classe abbia un **docente assegnato**; +- le **ore massime** dei docenti siano realistiche; +- le **indisponibilità** siano davvero indispensabili (vedi sotto). + +### Distingui sempre vincoli rigidi e preferenze +È l'errore concettuale più frequente. Marca come **"non disponibile"** o come +**indisponibilità** solo le impossibilità reali. Tutto ciò che è "gradito ma non +obbligatorio" va espresso come **preferenza** ("da evitare", "preferito"). Troppi +vincoli rigidi sono la causa numero uno degli orari impossibili da generare. + +### Parti semplice, poi raffina +Per il primo orario, usa il **preset predefinito** e l'ambito completo. Guarda il +risultato, individua il punto debole dai [punteggi](14-comprendere-i-punteggi.md), +poi cambia **un solo peso alla volta** e rigenera. Così capisci l'effetto di ogni +modifica. + +### Lavora per versioni +Non aver paura di generare molte versioni: costano poco e puoi confrontarle. Tieni +le più promettenti, elimina le altre per non fare confusione, e **finalizza** solo +alla fine. + +### Concedi tempo al motore sugli istituti grandi +Se l'istituto è grande, aumenta il **tempo massimo** di calcolo o restringi +l'**ambito** (genera una scuola alla volta). Più tempo e meno complessità aiutano +il motore a trovare soluzioni migliori. + +### Valida sempre dopo le modifiche manuali +Ogni volta che [personalizzi](16-personalizzazione-orario.md) un orario, controlla +la scheda **Conflitti** ed esegui la **validazione**: le modifiche manuali non sono +controllate in automatico. + +## Risoluzione dei problemi + +### Il motore non trova alcuna soluzione +Significa che i **vincoli rigidi sono in conflitto**: l'orario richiesto è +*impossibile*, non solo difficile. Controlla, in quest'ordine: + +| Verifica | Cosa controllare | +|----------|------------------| +| Griglia oraria | Il totale delle ore di una classe **entra** nel numero di slot disponibili? Servono più ore nella settimana? Vedi [cap. 7](07-orari-e-campanella.md). | +| Indisponibilità | Ci sono docenti con troppe ore marcate "non disponibile"? Riducile all'essenziale. Vedi [cap. 10](10-docenti.md). | +| Ore massime | Le ore massime (settimanali/giornaliere) dei docenti sono sufficienti a coprire le loro assegnazioni? | +| Assegnazioni | Un docente è assegnato a troppe classi rispetto al monte ore che può coprire? | +| Spostamenti | Per i multi-plesso, i tempi di viaggio sono compatibili con l'intervallo tra le ore? Vedi [cap. 11](11-spostamenti.md). | + +Correggi il dato più sospetto e rigenera. Procedi per tentativi, cambiando **una +cosa alla volta**. + +### La qualità è bassa (composito basso, ma > 0) +L'orario è valido ma migliorabile. Apri la scheda **Scores** +([cap. 14](14-comprendere-i-punteggi.md)), individua la **categoria più bassa** e +aumenta il **peso** corrispondente nel preset, poi rigenera. Ricorda che gli +obiettivi sono in parte in conflitto: migliorarne uno può peggiorarne un altro. + +### Il punteggio composito è 0 +C'è (almeno) una **violazione di un vincolo rigido**. Apri la scheda **Conflitti** +([cap. 15](15-revisione-orario.md#scheda-conflitti-conflicts)): elenca esattamente +le violazioni. Succede tipicamente dopo una modifica manuale; correggi la lezione +segnalata e valida di nuovo. + +### Il calcolo va in timeout senza una buona soluzione +L'istanza è troppo grande per il tempo concesso. Soluzioni: **aumenta il tempo +massimo**, oppure **restringi l'ambito** (genera meno scuole/classi per volta), +oppure semplifica i vincoli. + +### Non vedo classi o materie nella generazione +Quasi sempre mancano i **monte ore** o le **assegnazioni docenti**. Torna in +[Classi](09-classi.md) e verifica che ogni classe abbia le materie con le ore e il +docente. + +### Un docente risulta sovraccarico +Controlla la scheda **Assignments** ([cap. 15](15-revisione-orario.md)) per vedere +il totale ore. Se supera il previsto, rivedi le sue **assegnazioni** in +[Classi](09-classi.md) o le sue **ore massime** in [Docenti](10-docenti.md). + +### Le email delle preferenze non arrivano +Il sistema potrebbe essere in modalità di prova (le email vengono registrate ma non +spedite). Rivolgiti a chi gestisce l'installazione. Nel frattempo puoi inserire le +preferenze a mano dalla scheda del docente ([cap. 10](10-docenti.md)). + +### Ho perso l'accesso / la sessione è scaduta +Reinserisci le credenziali nella pagina di login ([cap. 3](03-primi-passi.md)). Se +le hai smarrite, contatta l'amministratore del sistema: non esiste un recupero +autonomo. + +## Quando chiedere aiuto tecnico + +Se un problema non rientra tra quelli qui sopra — per esempio errori di sistema, +pagine che non si caricano o comportamenti anomali — annota **cosa stavi facendo** e +**quale messaggio** hai visto, e contatta chi gestisce l'installazione del sistema +per il tuo istituto. + +--- + +Consulta il glossario per un ripasso rapido dei termini. + +--- + +[← Precedente: Esportazione](17-esportazione.md) · [Indice](README.md) · [Successivo: Glossario →](19-glossario.md) diff --git a/19-glossario.md b/19-glossario.md new file mode 100644 index 0000000..e9d3640 --- /dev/null +++ b/19-glossario.md @@ -0,0 +1,111 @@ +# 19. Glossario + +Definizioni brevi dei termini usati nel manuale e nell'interfaccia. Dove utile, il +rimando porta al capitolo che approfondisce il concetto. Tra parentesi, in +corsivo, l'etichetta inglese che potresti vedere nell'interfaccia. + +### Ambito / Scope *(scope)* +La porzione di orario da generare: tutto l'istituto oppure un sottoinsieme di scuole +o classi. Un ambito più stretto rende il calcolo più rapido. Vedi +[cap. 13](13-generazione-orario.md). + +### Anno scolastico *(academic year)* +Il periodo di riferimento (es. 2025/2026) a cui appartengono tutti i dati. Vedi +[cap. 4](04-anni-scolastici.md). + +### Assegnazione (docente) *(teacher assignment)* +Il legame "questo docente insegna questa materia a questa classe". Senza +assegnazioni il sistema non sa chi tiene le lezioni. Vedi [cap. 9](09-classi.md). + +### Aula/laboratorio *(facility)* +Una stanza a uso speciale e condiviso (palestra, laboratorio) richiesta da alcune +materie e non usabile da due classi insieme. Vedi [cap. 6](06-aule-e-laboratori.md). + +### Bozza *(draft)* +Stato di una versione di orario ancora modificabile. Vedi [cap. 15](15-revisione-orario.md). + +### Campagna (di raccolta preferenze) *(campaign)* +L'iniziativa con cui inviti i docenti a compilare le loro preferenze tramite un link +personale. Vedi [cap. 12](12-raccolta-preferenze.md). + +### Classe *(class group)* +Un gruppo fisso di studenti (es. 1A) che appartiene a una scuola e resta nella +propria aula. Vedi [cap. 9](09-classi.md). + +### Composito (punteggio) *(composite score)* +Il punteggio complessivo di qualità di una versione, da 0 a 100. Una violazione +rigida lo azzera. Vedi [cap. 14](14-comprendere-i-punteggi.md). + +### Conflitto *(conflict)* +Una violazione di un vincolo rigido in una versione di orario. Elencati nell'apposita +scheda del dettaglio. Vedi [cap. 15](15-revisione-orario.md#scheda-conflitti-conflicts). + +### Finalizzare *(finalize)* +Approvare una versione come orario ufficiale, bloccandola contro modifiche +accidentali. Vedi [cap. 15](15-revisione-orario.md). + +### Generazione / Ottimizzazione *(generate / optimization)* +Il processo con cui il motore costruisce automaticamente l'orario rispettando i +vincoli e massimizzando la qualità. Vedi [cap. 13](13-generazione-orario.md). + +### Giorno libero *(free day)* +Il giorno che un docente preferirebbe tenere libero da lezioni. È una **preferenza**, +non una garanzia. Vedi [cap. 10](10-docenti.md). + +### Indisponibilità *(unavailability)* +Un periodo in cui un docente non può proprio esserci: è un **vincolo rigido**, +sempre rispettato. Da non confondere con la preferenza "da evitare". Vedi +[cap. 10](10-docenti.md). + +### Materia *(subject)* +Una disciplina insegnata (Matematica, Italiano...). Vedi [cap. 8](08-materie.md). + +### Monte ore / Requisito *(subject requirement)* +Le ore settimanali di una materia richieste da una classe. È un **vincolo rigido**: +vengono collocate esattamente. Vedi [cap. 9](09-classi.md). + +### Orario compatto / Compattezza *(compactness)* +La qualità di un orario senza "buchi" tra le lezioni di un docente nello stesso +giorno. Obiettivo di qualità. Vedi [cap. 14](14-comprendere-i-punteggi.md). + +### Peso *(weight)* +Il valore che stabilisce quanta importanza dare a un obiettivo di qualità durante la +generazione. I pesi sono priorità relative, non percentuali. Vedi +[cap. 13](13-generazione-orario.md). + +### Plesso / Scuola *(school)* +Un edificio dell'istituto. Vedi [cap. 5](05-scuole.md). + +### Preferenza *(preference)* +Un desiderio (del docente o dell'istituto) trattato come **obiettivo di qualità**: +il sistema cerca di soddisfarlo ma può derogare. Contrapposto al vincolo rigido. +Vedi [cap. 1](01-introduzione.md). + +### Preset *(preset)* +Una configurazione salvata di pesi e impostazioni per la generazione, riutilizzabile. +Vedi [cap. 13](13-generazione-orario.md). + +### Slot orario *(time slot)* +Una casella "giorno + ora" della griglia oraria (es. lunedì, 3ª ora). Vedi +[cap. 7](07-orari-e-campanella.md). + +### Tempo massimo *(timeout)* +Il tempo massimo concesso al motore per cercare una soluzione. Vedi +[cap. 13](13-generazione-orario.md). + +### Vincolo rigido *(hard constraint)* +Una regola che **deve** sempre essere rispettata; se violata, l'orario non è valido. +Contrapposto alla preferenza. Vedi [cap. 1](01-introduzione.md). + +### Versione (di orario) *(timetable version)* +Un orario generato, con il suo punteggio e il suo stato (bozza/finale/archiviata). +Vedi [cap. 15](15-revisione-orario.md). + +--- + +Questo conclude il manuale. Per ricominciare da capo o consultare un altro +argomento, torna all'[Indice](README.md). + +--- + +[← Precedente: Buone pratiche e problemi](18-buone-pratiche-e-problemi.md) · [Indice](README.md) diff --git a/README.md b/README.md new file mode 100644 index 0000000..335dc20 --- /dev/null +++ b/README.md @@ -0,0 +1,63 @@ +# Manuale d'uso — Generatore di orario scolastico + +Benvenuto nel manuale del sistema di **pianificazione e ottimizzazione dell'orario +scolastico**. Questo strumento aiuta chi si occupa dell'orario (la cosiddetta +"funzione strumentale orario", un collaboratore del Dirigente o chiunque abbia +questo incarico) a costruire un orario di qualità per un istituto composto da una +o più scuole, riducendo drasticamente il lavoro manuale. + +Il sistema raccoglie i dati della scuola (aule, classi, materie, docenti, monte +ore) e le preferenze dei docenti, quindi genera automaticamente uno o più orari +che rispettano tutti i **vincoli obbligatori** e cercano di massimizzare la +**qualità complessiva** (meno spostamenti, meno "buchi", rispetto delle +preferenze). Tu resti sempre al comando: puoi confrontare le versioni, correggerle +a mano ed esportarle. + +## Come leggere questo manuale + +Il manuale è pensato per essere letto **in ordine** la prima volta: i capitoli +seguono la sequenza reale di lavoro, dall'inserimento dei dati fino all'orario +finale esportato. Ogni pagina termina con i collegamenti alla pagina +**precedente** e **successiva**, oltre che a questo indice. + +Se hai già dimestichezza con lo strumento, usa l'indice qui sotto per saltare +direttamente all'argomento che ti interessa. + +> **Nota sulle immagini.** In questo manuale le schermate sono indicate con +> segnaposto del tipo `[Immagine: ...]`. Sostituiscili con le catture reali +> dell'interfaccia della tua installazione quando distribuisci il manuale. + +## Indice + +### Parte 1 — Introduzione e orientamento +1. [Introduzione: cos'è questo sistema](01-introduzione.md) — cosa fa lo strumento, il contesto della scuola italiana e il vocabolario di base. +2. [Panoramica: dal dato all'orario finale](02-panoramica-del-processo.md) — la sequenza completa di lavoro, dall'inizio alla fine. +3. [Primi passi: accesso e interfaccia](03-primi-passi.md) — come accedere, muoversi tra le sezioni e cambiare lingua. + +### Parte 2 — Preparare i dati (Configurazione) +4. [Anni scolastici](04-anni-scolastici.md) — l'anno di riferimento a cui appartengono tutti i dati. +5. [Scuole](05-scuole.md) — gli edifici dell'istituto. +6. [Aule e laboratori](06-aule-e-laboratori.md) — le aule speciali richieste da alcune materie. +7. [Orari e campanella](07-orari-e-campanella.md) — la griglia giorni × ore di ogni scuola. +8. [Materie](08-materie.md) — le discipline insegnate. +9. [Classi, monte ore e assegnazione docenti](09-classi.md) — le classi, le ore per materia e chi insegna cosa. +10. [Docenti e preferenze](10-docenti.md) — l'anagrafica dei docenti e i loro vincoli. +11. [Distanze e spostamenti](11-spostamenti.md) — i tempi di viaggio tra scuole e da casa. + +### Parte 3 — Preferenze dei docenti +12. [Raccolta preferenze dei docenti](12-raccolta-preferenze.md) — le campagne per invitare i docenti a compilare le loro preferenze. + +### Parte 4 — Generare e rivedere l'orario +13. [Generazione dell'orario](13-generazione-orario.md) — avviare l'ottimizzatore e seguirne l'avanzamento. +14. [Comprendere i punteggi di qualità](14-comprendere-i-punteggi.md) — come leggere e confrontare la qualità delle versioni. +15. [Revisione e confronto delle versioni](15-revisione-orario.md) — analizzare l'orario, finalizzarlo o eliminarlo. +16. [Personalizzazione manuale](16-personalizzazione-orario.md) — correggere a mano una versione. +17. [Esportazione in foglio di calcolo](17-esportazione.md) — scaricare l'orario in Excel o OpenDocument. + +### Parte 5 — Consigli e riferimenti +18. [Buone pratiche e risoluzione dei problemi](18-buone-pratiche-e-problemi.md) — come ottenere un buon primo orario e cosa fare quando qualcosa non torna. +19. [Glossario](19-glossario.md) — i termini chiave spiegati in breve. + +--- + +[Inizia dal capitolo 1: Introduzione →](01-introduzione.md)