> 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/funzioni-e-dettagli-tecnici/funzioni-interne.md).

# Funzioni interne

Questa pagina descrive alcuni contratti centrali del codice, con ingressi, risultati ed effetti. È una guida ragionata ai servizi principali, non un elenco di tutti i metodi del solver.

## Il modello del curricolo

In [curriculumService.js](https://github.com/lsponta/orario/blob/3bf5b58/src/services/curriculumService.js), `costruisciModello({ classi, curricolo, classiGruppi })` costruisce in memoria le relazioni tra classi e gruppi e i conteggi delle ore. Non riceve una connessione al database.

| Funzione o risultato                    | Significato                                                                       |
| --------------------------------------- | --------------------------------------------------------------------------------- |
| `caricaModello(db)`                     | Legge classi, curricolo e appartenenze e chiama il costruttore del modello        |
| `righeClasse(classeId)`                 | Restituisce il dettaglio delle materie e delle ore proprie/condivise della classe |
| `totaliClasse(classeId)`                | Restituisce ore proprie, condivise e complessive; valori zero se assente          |
| `oreMateriaClasse(classeId, materiaId)` | Ore complessive della materia per la classe                                       |
| `pesoEvento(classeId)`                  | Uno per una classe; almeno uno, o il numero dei membri, per una pluriclasse       |
| `oreEffettiveAssegnate(lezioni)`        | Somma i pesi degli eventi assegnati                                               |

Un evento condiviso da due classi pesa una volta come attività del docente e due volte nel conteggio delle ore frequentate. Confondere queste unità produce percentuali di copertura scorrette.

## Impronte, metriche e fotografie

[scheduleSnapshotService.js](https://github.com/lsponta/orario/blob/3bf5b58/src/services/scheduleSnapshotService.js) separa quattro responsabilità.

| Funzione                             | Ingresso e risultato                                                          | Effetti            |
| ------------------------------------ | ----------------------------------------------------------------------------- | ------------------ |
| `dataFingerprint(db)`                | Hash delle tabelle di ingresso selezionate dal servizio                       | Legge il database  |
| `draftFingerprint(db)`               | Hash del contenuto della bozza considerato dal servizio                       | Legge il database  |
| `draftMetrics(db)`                   | Conteggi degli eventi e delle ore effettive, con ripartizione del curricolo   | Legge il database  |
| `saveSnapshotContent(db, versionId)` | Copia lezioni, sostegno e relazioni nella versione indicata                   | Scrive il database |
| `publicContext(db)`                  | Oggetto con calendario, anagrafiche e relazioni necessarie alla consultazione | Legge il database  |

Le impronte rilevano cambiamenti tra lettura e applicazione; non sostituiscono una transazione. Il contesto pubblico permette di consultare una versione con le anagrafiche e il calendario del momento dell'approvazione.

## Rapporti di verifica e bozza vuota

`compatibilityService.analyze(db)` restituisce problemi separati per categoria `dati` e `orario`, impronte e contatori. Con zero lezioni, `bozza_vuota` è `true`: vengono eseguiti i controlli dei dati, mentre `errori_orario` è zero perché la bozza non viene valutata. Lo zero non certifica un orario valido.

Per dashboard ed elenco conflitti, le route usano `conflictEngine.getAllConflicts(db, { skipEmptyDraft: true })`. Su bozza vuota restano i controlli sui dati e sul sostegno; con lezioni riprende il normale rapporto. L'opzione è disattivata per default: approvazione, versioni e diagnosi ricevono la verifica completa. `GET /api/stats` espone `bozzaVuota` e calcola il totale con lo stesso criterio di `GET /api/conflitti`.

## La decisione di approvazione

In [scheduleApprovalService.js](https://github.com/lsponta/orario/blob/3bf5b58/src/services/scheduleApprovalService.js):

* `curriculumCoverage(db, metriche)` verifica la copertura rispetto alle richieste del curricolo;
* `chairCoverage(db)` verifica le cattedre;
* `verifyDraft(db)` combina copertura, cattedre, analisi dei profili e conflitti.

`verifyDraft` restituisce `approvabile`, `improntaDati`, `improntaOrario`, `metriche`, i dettagli dei controlli e un `riepilogo`. La decisione richiede copertura, cattedre e profili validi e zero conflitti con severità `errore`. Gli avvisi sono restituiti separatamente e non bloccano questa condizione.

Questa funzione legge e verifica; la scrittura della pubblicazione avviene nella rotta di approvazione, che ricontrolla le impronte nella transazione.

## Il confine del generatore

[GenerationOperationManager](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/generationOperationManager.js) gestisce il ciclo di vita delle operazioni. Il worker esegue il calcolo separatamente dal processo HTTP; la pipeline organizza le fasi di ricerca.

Per orientarsi nel codice, seguire questo ordine: rotta di avvio → manager → `generationWorker.js` → `solver/GenerationPipeline.js`. La lettura del solo algoritmo non spiega quando un risultato viene adottato nella bozza: questa responsabilità appartiene al livello applicativo.

`extendTime(id, { fase, minuti, richiestaId })` aumenta il budget della fase attiva, anche durante la sua pausa. `generationControlSignal` coordina il cambio di fase e il tempo aggiuntivo tra manager e worker; `searchDeadline` legge la scadenza aggiornata. Il processo Python riceve a sua volta gli incrementi per proseguire oltre la scadenza iniziale. Il timer di sicurezza del server e il registro dell'operazione vengono aggiornati.

La richiesta è idempotente a parità di identificativo e contenuto. Una richiesta arrivata dopo il cambio di fase non estende accidentalmente la fase successiva. Dettagli HTTP ed esempio sono in [API e integrazioni](/orario/funzioni-e-dettagli-tecnici/api.md).

## La lettura pubblica

[createPublicScheduleService(db)](https://github.com/lsponta/orario/blob/3bf5b58/src/services/publicScheduleService.js) restituisce i metodi utilizzati dalle rotte pubbliche.

| Metodo                                             | Risultato                                                                                             |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `status()`                                         | Disponibilità e metadati; nessuna pubblicazione produce una risposta normale con `disponibile: false` |
| `sites()`, `subjects()`, `teachers()`, `classes()` | Anagrafiche della fotografia, filtrate rispetto alle entità referenziate                              |
| `calendar()`                                       | Configurazione del calendario congelata                                                               |
| `schedule(filters)`                                | Lezioni arricchite con nomi e altri dati della fotografia                                             |
| `supports(filters)`                                | Ore di sostegno arricchite per la consultazione                                                       |

Salvo `status()`, l'assenza della pubblicazione attiva genera un errore con stato HTTP 404 e codice `nessuna_pubblicazione`.

Il filtro per classe include i gruppi collegati. Quello per docente nelle lezioni considera anche il compresente. Il servizio legge le tabelle delle versioni e il contesto salvato: le modifiche alla bozza non cambiano automaticamente ciò che il pubblico vede.