> 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/riferimenti-della-guida/come-leggere.md). # Come leggere questa guida La guida parte dalle domande del lettore e arriva ai dettagli tecnici. Non richiede di conoscere la storia delle sessioni di sviluppo. I nomi di file e classi compaiono dove aiutano a ritrovare un comportamento nel codice. ## Versione descritta La revisione corrente è dell'**11 settembre 2026** e descrive il commit [`3bf5b58`](https://github.com/lsponta/orario/tree/3bf5b58), distribuito anche in produzione. Comprende aggiunta di tempo alla generazione, buche effettive, controlli preventivi, bozza vuota, dashboard e continuità della sessione. I collegamenti ai sorgenti sono fissati a questa versione. Il catalogo HTTP copre 127 registrazioni ricontrollate nei moduli delle route. La specifica OpenAPI copre soltanto gli otto endpoint pubblici. Gli schemi estensibili non descrivono ogni campo delle anagrafiche e non sono ancora verificati con test di contratto runtime. Le modifiche locali non ancora integrate in `main` non fanno parte di questa descrizione. La revisione è una lettura di codice, schema e documenti: non comporta una nuova esecuzione dei test applicativi o accessi ai database operativi. I controlli di documentazione riguardano collegamenti, inventario HTTP e sincronizzazione GitBook. ## Come usare le pagine * [Il progetto in breve](/orario/comprendere-orario/progetto.md) chiarisce obiettivi e confini. * [Il dominio scolastico](/orario/comprendere-orario/dominio.md) definisce il vocabolario e le relazioni. * [Mappa dell'architettura](/orario/comprendere-orario/architettura.md) collega responsabilità e moduli. * [Come nasce un orario](/orario/comprendere-orario/flusso-orario.md) segue un'operazione concreta. Gli esempi scolastici sono illustrativi, non estratti dai dati di un istituto. I diagrammi sono viste semplificate: la mappa concettuale non sostituisce lo schema del database e quella di esecuzione non elenca ogni chiamata. ## Rapporto con i documenti esistenti Il repository conserva manuali, analisi, piani e resoconti. Sono materiali utili per ricostruire contesto e intenzioni; una descrizione storica va però confrontata con il codice prima di usarla per spiegare lo stato attuale. La revisione ha recuperato i contenuti sulla riorganizzazione della codebase e sulla separazione tra bozza e pubblicazione. Ha aggiornato la descrizione dei risultati incompleti sulla base del gestore asincrono corrente. Il nome di una milestone in un commento non dimostra che una funzione sia ancora da implementare. Le fonti tecniche in fondo alle pagine rimandano al repository privato: per aprirle occorre avere accesso a GitHub. Il corpo della guida contiene le spiegazioni necessarie anche senza aprire quei collegamenti. ## Come mantenere la guida Le pagine vivono in `doc/guida/`; `SUMMARY.md` ne stabilisce la navigazione. Quando una modifica cambia un concetto, una responsabilità o una fase del flusso, aggiorna la pagina pertinente nella stessa proposta di modifica. Verifica poi i riferimenti al codice e aggiorna il riferimento di versione quando la revisione copre un nuovo stato dell'applicazione. Una correzione del codice non deve comportare la riscrittura indiscriminata delle pagine. Va modificata la spiegazione interessata, conservando i collegamenti utili e rendendo espliciti gli eventuali comportamenti ancora da verificare.