> For the complete documentation index, see [llms.txt](https://sponta.gitbook.io/orario/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sponta.gitbook.io/orario/comprendere-orario/dominio.md).

# Il dominio scolastico

Per comprendere Orario conviene partire da tre domande: **che cosa deve frequentare una classe, chi lo insegna e quando può svolgersi**. Curricolo, cattedra e calendario rispondono a domande diverse e si incontrano nella lezione collocata in orario.

## Gli oggetti principali

| Oggetto           | Significato nel progetto                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| Plesso            | Sede di riferimento delle classi, con un calendario effettivo e relazioni con i docenti                 |
| Classe            | Unità scolastica con insegnamenti richiesti e un profilo giornaliero                                    |
| Materia           | Insegnamento identificato da nome, indirizzo e ciclo; lo stesso nome può corrispondere a record diversi |
| Docente           | Risorsa con monte ore, materie insegnabili, plessi ammessi e disponibilità                              |
| Curricolo         | Ore richieste per coppia classe–materia e loro composizione in blocchi                                  |
| Cattedra          | Assegnazione di un docente a una coppia classe–materia, come titolare o compresente                     |
| Aula              | Risorsa fisica da considerare quando una lezione ne richiede l'assegnazione                             |
| Lezione collocata | Associazione tra classe o gruppo, materia, docente, plesso, giorno e periodo                            |

```mermaid
flowchart TD
    P[Plesso e calendario] --> C[Classe]
    C --> R[Curricolo: materia e blocchi richiesti]
    D[Docente e disponibilità] --> T[Cattedra confermata]
    R --> T
    R --> L[Lezioni da collocare]
    T --> L
    P --> L
    V[Vincoli e risorse] --> L
```

Il diagramma mostra dipendenze concettuali, non tutte le chiavi esterne del database.

## Le ore sono periodi della griglia

Nel modello l'ora è un indice di periodo nel giorno scolastico. I calendari stabiliscono quanti periodi sono disponibili e quanti appartengono alla mattina. Il calendario del plesso può specificare eccezioni a quello d'istituto; un totale di zero chiude il giorno per quel plesso.

Il **profilo della classe** esprime invece la distribuzione delle ore tra i giorni. Calendario e profilo non sono intercambiabili: il primo delimita quando si può lavorare, il secondo descrive la distribuzione richiesta per quella classe.

Per un docente si combinano associazione al plesso, giorni ammessi, indisponibilità generali e indisponibilità aggiuntive per singolo plesso. I trasferimenti tra sedi richiedono inoltre spazio nella griglia.

## Dal curricolo ai blocchi

Supponiamo, come esempio illustrativo, che una classe richieda cinque periodi settimanali di una materia, organizzati in due blocchi da due e uno da uno. Il generatore deve collocare **tre blocchi**, per un totale di **cinque periodi**.

Un blocco da due conserva il significato di due periodi consecutivi. Due singole ore collocate separatamente non sono equivalenti solo perché la somma è la stessa. Anche le lezioni già fissate devono essere compatibili con i blocchi richiesti quando si completa una bozza.

La cattedra indica il docente da usare. L'abilitazione di un docente a una materia descrive una possibilità; una cattedra confermata descrive l'assegnazione operativa. La compresenza aggiunge un secondo docente a determinate attività e impegna anche la sua disponibilità.

## Pluriclassi: una lezione, più classi partecipanti

Una pluriclasse rappresenta un gruppo di classi che condividono lezioni. Nel database è rappresentata come una classe di tipo gruppo, collegata alle classi membro. Il suo curricolo produce eventi condivisi.

Per una classe reale, il **curricolo effettivo** somma le ore proprie e le ore condivise frequentate attraverso le pluriclassi.

Esempio: due classi frequentano insieme un blocco da due periodi. Il generatore colloca due eventi orari, uno per periodo. Ciascuna delle due classi riceve due periodi: il totale delle ore effettive sulle classi è quattro. Duplicare la lezione per ogni classe falserebbe sia l'occupazione del docente sia il conteggio degli eventi.

Per questo **eventi collocati** e **ore effettive delle classi** possono avere totali diversi senza che ci sia un errore.

## Articolazioni: gruppi che seguono attività diverse

Le articolazioni descrivono la suddivisione di una o più classi in gruppi per attività differenti. Il modello distingue:

* **Partizione:** gruppi paralleli e sincronizzati; in quei periodi non si sovrappone una lezione a classe intera.
* **Estrazione:** un gruppo esce mentre la classe di provenienza prosegue.

La composizione usa numeri dichiarati di studenti, non un'anagrafica individuale. I gruppi hanno curricoli, cattedre e lezioni propri.

Una pluriclasse riunisce classi per una lezione condivisa; un'articolazione gestisce la loro suddivisione per attività diverse. La differenza cambia quali occupazioni sono compatibili nello stesso periodo.

## Vincoli rigidi e preferenze

Le regole strutturali tutelano la validità del modello. I vincoli configurati aggiungono condizioni con un ambito, un destinatario e parametri; quando flessibili, contribuiscono alla valutazione della qualità con un peso. Il motore risolve anche la precedenza tra istanze globali e specifiche.

Per leggere un risultato occorre quindi sapere quali regole sono attive e con quale configurazione. Una categoria disattivata non equivale a una preferenza attiva che l'orario soddisfa.

## Buche effettive dei docenti

Le buche sono periodi liberi fra lezioni della stessa giornata. Il conteggio effettivo esclude i periodi necessari ai trasferimenti e quelli in cui il docente risulta indisponibile, senza sottrarre due volte lo stesso periodo.

Per esempio, con lezioni alle ore 1, 2, 5 e 6, le ore 3 e 4 non diventano due buche effettive se il docente è indisponibile in entrambe. Se invece sono disponibili e non servono per un trasferimento, entrano nel conteggio. Questa distinzione è condivisa fra generazione e verifica attraverso `TeacherItinerary`. Il requisito di pausa giornaliera è una regola distinta dal limite delle buche effettive.

## Prossima lettura e riscontri

La [mappa dell'architettura](/orario/comprendere-orario/architettura.md) mostra dove vivono questi concetti.

* [Schema di base](https://github.com/lsponta/orario/blob/3bf5b58/src/db/schema.sql) e [migrazioni, pluriclassi e articolazioni](https://github.com/lsponta/orario/blob/3bf5b58/src/db/database.js).
* [Curricolo effettivo e conteggi](https://github.com/lsponta/orario/blob/3bf5b58/src/services/curriculumService.js), [calendario](https://github.com/lsponta/orario/blob/3bf5b58/src/services/calendarService.js) e [profili](https://github.com/lsponta/orario/blob/3bf5b58/src/services/classProfileService.js).
* [Trasformazione del curricolo in task](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/solver/TaskGenerator.js) e [motore delle regole](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/solver/RulesEngine.js).