> 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/flusso-orario.md). # Come nasce un orario Seguiamo una generazione attraverso dati, ricerca, bozza e approvazione. Il percorso descritto è quello asincrono esposto da `/api/orario/generazioni`, con pipeline per fasi. Nel codice esiste anche il percorso sincrono `/api/orario/genera`: non va confuso con il gestore delle operazioni lunghe. ## 1. Preparare una domanda coerente Prima di cercare le posizioni delle lezioni, occorre descrivere che cosa collocare: curricoli e blocchi, cattedre confermate, calendari, profili delle classi, disponibilità, gruppi e risorse. La richiesta passa dai controlli di autenticazione e ruolo amministrativo. Il server valida le opzioni e analizza la compatibilità dei dati con i vincoli rigidi. Se trova errori di dati, la ricerca viene fermata prima di avviare il worker. Superare questi controlli non costituisce da solo una prova che esista una soluzione completa. Premendo **Avvia generazione**, il comando diventa subito **Preparazione in corso…** e non permette un secondo avvio durante i controlli. Il registro spiega che vengono controllati dati e vincoli prima della ricerca. ## 2. Stabilire che cosa può cambiare **Rigenerare** consente di ricostruire le lezioni modificabili; **completare** parte dalle lezioni da preservare. I lock identificano assegnazioni da mantenere. Una modalità di sola ottimizzazione parte invece dalla bozza esistente, rendendo mobili i blocchi non bloccati secondo quel percorso. Il gestore registra le impronte dei dati e della bozza e avvia il worker. Quest'ultimo legge il database e invia aggiornamenti al server: la durata della ricerca non coincide con quella di una singola richiesta HTTP. ## 3. Costruire, poi migliorare Il motore distingue quattro fasi. Nel pannello corrente sono selezionabili Costruzione e Ricostruzioni mirate; le altre due sono temporaneamente disabilitate nell'interfaccia, pur restando implementate nel motore: | Fase | Scopo | | -------------------------- | ------------------------------------------------------------------------ | | Costruzione | Trovare una collocazione completa rispettando le condizioni necessarie | | Spostamenti e scambi | Migliorare la soluzione attraverso modifiche locali | | Ricostruzioni mirate | Riaprire parti selezionate dell'orario per cercare combinazioni migliori | | Ricerca sull'intero orario | Esplorare modifiche su scala più ampia | Ogni fase ha abilitazione e budget propri. Il percorso di costruzione della pipeline richiede la strategia esatta, che usa il risolutore Python. Se la costruzione non produce un risultato completo, la pipeline restituisce quell'esito senza proseguire con le fasi di qualità. Le fasi di miglioramento condividono una soluzione verificata e possono emettere checkpoint. Le preferenze sono confrontate attraverso la policy di qualità; una soluzione con un punteggio migliore non autorizza a ignorare completezza, regole rigide e invarianti dello stato. La pausa conserva il contesto della ricerca; il worker sottrae il tempo di pausa dal tempo di calcolo conteggiato. L'arresto e il raggiungimento di un limite devono essere interpretati attraverso lo stato finale dell'operazione. ### Aggiungere tempo durante la ricerca **Aggiungi tempo** propone +5, +15 e +30 minuti, +1 e +2 ore, oppure una durata personalizzata espressa in minuti o ore interi positivi. L'aggiunta aumenta il limite della **fase attiva**, che viene aggiornato nel pannello e nel registro. Non occorre riavviare la generazione. Il comando funziona anche durante la pausa della fase. Durante una pausa fra due fasi occorre prima riprendere e attendere l'avvio della successiva. Una fase conclusa non può essere prolungata. Nelle ricostruzioni mirate restano validi i limiti dei singoli tentativi: aumenta il tempo complessivo della fase, non quello di ogni ricostruzione. Il limite è un massimo, non una durata obbligatoria. Se la ricerca dimostra che un orario completo è impossibile, aggiungere tempo non risolve la contraddizione. Se invece termina per tempo esaurito, non ha dimostrato l'impossibilità del problema. ## 4. Decidere cosa diventa bozza Il risultato attraversa un controllo distinto dalla ricerca: ```mermaid flowchart TD R[Risultato della ricerca] --> F{Dati e bozza ancora compatibili?} F -->|No| S[Risultato superato: non applicato] F -->|Sì| E{Tipo di esito} E -->|Completo| A[Applicazione transazionale alla bozza] E -->|Parziale da conservare| D[Decisione: conserva o scarta] D -->|Conserva e controlli superati| A E -->|Nessuna soluzione nella costruzione esatta| N[Bozza precedente conservata] A --> V[Verifica per approvazione] V --> P[Approvazione esplicita e snapshot pubblico] ``` Nel gestore corrente, un risultato parziale o un tempo esaurito può restare in attesa della decisione **conserva/scarta**, invece di essere scritto immediatamente. Nella costruzione esatta senza alcuna soluzione completa, la bozza precedente resta invariata. Se dati o bozza sono cambiati durante la ricerca, il risultato è segnato come superato e non viene applicato. La scrittura crea un backup e usa una transazione. Un errore di scrittura provoca rollback e il risultato può restare disponibile per una decisione successiva. Eventuali checkpoint già salvati sono parte dello stato corrente: non bisogna interpretare un arresto come annullamento automatico di ogni salvataggio precedente. ## 5. Correggere e verificare Una bozza può essere esaminata, modificata e conservata in versioni. Gli strumenti di allocazione assistita aiutano a valutare le destinazioni delle attività residue. Le modifiche vanno lette insieme ai conflitti e alle metriche di copertura. La pagina **Verifica dati e vincoli** distingue la compatibilità della configurazione dalle violazioni della bozza. Con zero lezioni, la scheda Bozza mostra **Bozza vuota**: non elenca i blocchi mattutini o le ore mancanti come violazioni. Questo vale anche dopo una generazione fallita che non ha scritto un risultato. **Chiudi** chiude il pannello: non trasferisce alla bozza le violazioni incontrate durante la ricerca. Vedere [Verifica dei dati e della bozza](/orario/comprendere-orario/verifica.md) per interpretare i rapporti. La verifica per l'approvazione controlla copertura del curricolo, cattedre, profili e conflitti. Le condizioni rigide impediscono l'approvazione; gli avvisi flessibili sono riportati separatamente e non rendono da soli la bozza non approvabile. Vanno valutati prima della decisione esplicita. ## 6. Pubblicare una fotografia approvata L'approvazione è esplicita e distinta dalla generazione. Il server ripete i controlli in transazione e confronta le impronte ricevute dalla verifica: se la bozza o i dati sono cambiati, non approva una fotografia diversa da quella appena valutata. La nuova pubblicazione sostituisce quella attiva conservando lo storico. Le route di consultazione richiedono una sessione valida e leggono lezioni e contesto della versione approvata. Le correzioni successive della bozza diventano visibili solo dopo una nuova approvazione. Se non esiste una pubblicazione attiva, il portale non espone la bozza come ripiego. Qui “pubblicazione” riguarda **l'orario scolastico nell'applicazione**. La pubblicazione di questa guida su GitBook è un'operazione distinta. ## Come leggere un esito problematico | Esito | Interpretazione utile | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Incompatibilità dei dati | Correggere la domanda prima di cercare le posizioni | | Impossibilità rilevata dal risolutore | La combinazione dei vincoli rigidi non ammette un orario completo; la verifica preventiva può non spiegare la combinazione responsabile | | Tempo esaurito | Il budget non è bastato; non equivale a impossibilità dimostrata | | Bozza parziale | Ci sono attività residue; valutare il tentativo prima di conservarlo | | Risultato superato | Dati o bozza sono cambiati rispetto alla ricerca | | Preferenze residue | Esaminare qualità e pesi, separatamente dai blocchi rigidi | | Errore tecnico | Distinguere il guasto del processo da un esito del problema scolastico | ## Riscontri nel repository * [Avvio, applicazione e approvazione](https://github.com/lsponta/orario/blob/3bf5b58/src/routes/timetable.js). * [Stati e decisioni sui risultati](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/generationOperationManager.js), [fasi disponibili](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/generationPipelineConfig.js), [pipeline](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/solver/GenerationPipeline.js). * [Verifica della bozza](https://github.com/lsponta/orario/blob/3bf5b58/src/services/scheduleApprovalService.js) e [consultazione isolata](https://github.com/lsponta/orario/blob/3bf5b58/src/services/publicScheduleService.js). Torna alla [mappa dell'architettura](/orario/comprendere-orario/architettura.md) per individuare il componente da approfondire.