# 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.

## 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)