# Guida dettagliata di installazione e uso **Portale Inclusione — anteprima tecnica** IIS “Antonio Stradivari” — documento da validare con DPO e Dirigente Scolastico ## 1. Avvertenza iniziale Questa repository contiene una demo funzionante, ma non un servizio pronto per trattare PDP reali. Tutti i dati mostrati sono fittizi. I pulsanti di firma e consegna sono simulazioni: nessuna CIE viene letta, nessun PDF viene firmato e nessun documento viene trasmesso alla segreteria. Prima dell’esercizio reale devono essere completati backend, autenticazione, autorizzazioni, cifratura, gestione delle chiavi, DPIA, regole di conservazione, verifica delle firme e accordi con i fornitori. ## 2. Requisiti Per la demo servono: - macOS, Windows o Linux; - un browser aggiornato, preferibilmente Chrome, Edge, Firefox o Safari; - Python 3 oppure un altro server HTTP locale; - un file XLS/XLSX/CSV di prova, senza dati reali; - per provare il flusso CieSign reale in futuro: CIE 3.0 attiva, PIN, NFC o lettore contactless e applicazione ufficiale CIE. - per il percorso 104/PEI: modello PEI dell’istituto, GLO, profilo/diagnosi riportata dal tutor e progettazione disciplinare dei singoli docenti; Non aprire `index.html` con doppio clic (`file://`) per testare il flusso completo: usare un server HTTP locale consente di verificare correttamente caricamento script, sessione e collegamenti. ## 3. Installazione della demo ### macOS/Linux Aprire Terminale ed eseguire: ```bash cd "/Users/claudionuzzo/Dev/portale-inclusione" python3 -m http.server 8765 ``` Aprire quindi: ```text http://127.0.0.1:8765/index.html ``` Lasciare il terminale attivo mentre si usa la demo. Per arrestare il server premere `Ctrl+C`. ### Windows Aprire PowerShell nella cartella del progetto: ```powershell py -m http.server 8765 ``` Aprire `http://127.0.0.1:8765/index.html`. ### Pubblicazione della sola anteprima È possibile pubblicare il front-end su hosting statico gratuito, ma soltanto se il repository non contiene dati, chiavi private, token o file di PDP. Prima della produzione l’hosting deve usare HTTPS, policy di sicurezza, dipendenze verificate e nessun endpoint protetto incorporato nel JavaScript pubblico. ## 4. Accesso alla demo 1. Aprire il portale. 2. Usare l’accesso ospite/demo per la presentazione. 3. Per il test Google, usare esclusivamente un account di prova autorizzato. 4. L’accesso Google attuale identifica il profilo nel browser, ma non equivale alla verifica server-side necessaria in produzione. 5. Non incollare token, nomi reali, diagnosi o file riservati nella demo. La demo salva alcuni dati nel browser per permettere di interrompere e riprendere la simulazione. In produzione questa persistenza deve essere sostituita con sessione server-side, database protetto e controlli di autorizzazione a ogni richiesta. ## 5. Caricamento dell’elenco annuale Il referente apre la sezione **Elenco PDP e assegnazione tutor** nella Dashboard. ### 5.1 Foglio PDP Il primo foglio deve contenere almeno: | Colonna | Obbligatoria | Esempio | |---|---:|---| | `alunno` | sì | L. M. (demo) | | `classe` | sì | 4A Moda/Arredo | | `anno` | no | 2026/27 | | `tipo_pdp` | no | DSA oppure BES | | `tutor` | sì | prof. Claudio Nuzzo | | `email_tutor` | no | tutor@scuola.it | ### 5.2 Foglio CdC Il secondo foglio può chiamarsi `Docenti-Materie-Classi`, `CDC` o contenere “docenti” nel nome. Deve contenere: | Colonna | Obbligatoria | Esempio | |---|---:|---| | `docente` | sì | prof.ssa Elena Pagliari | | `materia` | sì | Italiano | | `classe` | sì | 4A Moda/Arredo | | `ruolo` | no | Docente CdC | | `email_docente` | no | docente@scuola.it | L’elenco docente-materia-classe è modificabile dalla schermata di anteprima con i pulsanti **Aggiungi** e **Rimuovi**. Le modifiche sono soltanto locali alla demo; quando sarà disponibile `anagrafica-api`, la fonte primaria dovrà essere l’API istituzionale. ### 5.3 Regole di sicurezza dell’import La demo applica controlli didattici di base: - accetta solo XLS, XLSX e CSV; - rifiuta file oltre 5 MB; - rifiuta file con macro XLSM; - rifiuta fogli nascosti inattesi; - rifiuta formule e collegamenti esterni; - rifiuta duplicati PDP e duplicati docente-materia-classe; - richiede alunno, classe e tutor; - genera un identificativo tecnico casuale; - non conserva la password inserita nel file; - non mostra il codice tecnico all’utente che lavora sul PDP. In produzione il file deve essere validato e importato dal backend, sottoposto a scansione antimalware quando disponibile, registrato con hash e cancellato dopo il tempo tecnico stabilito. Il referente non deve caricare diagnosi, testo del PDP, PIN, password o chiavi nel foglio. ## 6. Apertura e compilazione del PDP 1. Dalla tabella importata scegliere **Apri gestione PDP**. 2. Il tutor vede il fascicolo assegnato e completa la bozza. 3. Le parti diagnostiche/documentali sono riportate dal tutor e non sono modificabili dai singoli docenti. 4. Le aree disciplinari sono suddivise per materia. 5. Un docente può intervenire soltanto nella propria materia e nella classe assegnata. 6. Il docente non deve conoscere né digitare il codice tecnico: il portale lo collega automaticamente al fascicolo autorizzato. 7. Il sistema salva la bozza. Nella demo il salvataggio è locale; in produzione deve essere una richiesta autenticata e autorizzata al backend. La compilazione può essere interrotta in qualsiasi momento. Il portale salva automaticamente i dati e la posizione raggiunta; al rientro il tutor ritrova la bozza nello stesso punto e può continuare. **Salva ed esci** rende esplicita la chiusura della sessione. In produzione il salvataggio deve essere transazionale, versionato e associato al fascicolo corretto, senza conservare token o password nel browser. Il nome dell’alunno viene mostrato soltanto agli utenti autorizzati che ne hanno bisogno per svolgere il compito. Il codice casuale serve invece a ridurre la presenza dei nominativi in log, URL, file tecnici, backup e depositi. ## 7. Dichiarazione dei docenti Nel flusso **Firme digitali del Consiglio di Classe**: 1. ogni docente apre la propria sezione; 2. modifica o conferma le misure della propria materia; 3. salva la modifica; 4. seleziona **Ho completato le modifiche**; 5. il tutor controlla il quadro generale. La spunta non è una firma: è una dichiarazione di completamento che abilita il passaggio successivo. Il tutor non può avviare la raccolta firme finché non risultano presenti tutte le dichiarazioni. ## 8. Aggiornamento annuale Il pulsante **Aggiorna PDP** crea una nuova annualità e propone la classe successiva secondo i dati restituiti da `anagrafica-api` oppure dal fallback della demo. Il rinnovo annuale non ripete la compilazione completa: il contenuto già approvato viene mantenuto come base. Il sistema aggiorna anno, classe, docenti e materie e riapre, di norma, soltanto le aree disciplinari e le misure. Eventuali modifiche più ampie al PEI derivanti da un GLO devono essere registrate nel percorso GLO e autorizzate dal tutor secondo la procedura dell’istituto. Sono disponibili due scelte: ### Riproponi senza modifiche - mantiene il contenuto dell’anno precedente come base; - conserva lo stato delle misure nella simulazione; - porta il nuovo CdC direttamente alla sola conferma delle proprie sezioni; - non richiede di riscrivere il PDP/PEI; - richiede poi la firma dei docenti abilitati per la nuova annualità; - crea una nuova versione e una nuova raccolta firme. ### Apri alle modifiche di materia - mantiene il documento precedente come base di lavoro; - riapre soltanto le aree disciplinari e le misure assegnate; - richiede ai docenti una nuova modifica/conferma; - crea una nuova versione indipendente dalla precedente. Il passaggio automatico di classe deve essere verificato nei casi di cambio sezione, indirizzo, trasferimento o fine ciclo. Una versione già firmata non deve essere modificata: si apre una nuova versione. ### Formula maturità — solo PDP DSA/BES di classe quinta Quando il campo classe inizia con `5`, nei modelli PDP DSA e PDP BES compare la sezione **Formula maturità** con una spunta di conferma. Il testo inserito nel riepilogo è: > Per l’esame di maturità si confermano tutte le misure messe in atto in questi > anni. Eventuali schemi saranno consegnati in segreteria e allegati ai fascicoli > personali per la commissione d’esame. La sezione non viene generata per le classi dalla prima alla quarta e, in questa versione, non viene applicata al PEI. Prima delle conferme il tutor esegue **Controllo materie della nuova classe**. Il portale confronta l’elenco precedente con quello restituito per la nuova classe da `anagrafica-api` (docente + materia), mostra le materie aggiunte e rimosse e blocca spunte e firme finché il tutor non conferma il quadro. In caso di materia nuova, il docente non riceve una falsa riproposizione: deve compilare la propria area; le materie rimaste uguali possono invece essere soltanto confermate. ## 9. Raccolta firme CIE/CieSign — simulazione Il tutor seleziona **Il tutor avvia raccolta firme CIE** soltanto dopo avere verificato tutte le spunte. Da questo momento: 1. il documento definitivo viene congelato; 2. il PDF nominativo non deve essere rigenerato; 3. il tutor abilita un docente alla volta; 4. ciascun docente scarica la versione corretta; 5. la firma reale avviene localmente con CieSign o Software CIE; 6. il docente ricarica il PDF firmato; 7. il portale verifica documento e firma; 8. si passa al docente successivo. Nella demo il pulsante è **Simula firma CIE** e registra solo un evento fittizio. ### 9.1 Correzione di un errore Se il tutor rileva un errore dopo l’avvio delle firme, può usare **Annulla firme e riapri**. Il comando richiede due conferme, azzera le firme e le dichiarazioni della versione in corso e riporta il documento alla compilazione, mantenendo il fascicolo e il Consiglio di Classe. Se è necessario ripartire da zero, il tutor può usare **Elimina documento e ricomincia**. Il comando richiede la digitazione esatta di `ELIMINA` e una seconda conferma. Nella demo elimina la bozza locale del tipo di piano corrente. In produzione non deve significare cancellazione incontrollata: il backend deve applicare retention, audit, eventuale conservazione del documento firmato e procedura autorizzata di rettifica/scarto. Il pulsante deve essere visibile solo al tutor o a un ruolo amministrativo delegato. ## 10. Uso reale di CieSign La procedura dettagliata è in: [Guida anteprima CIE/CieSign](guida-ciesign-anteprima.md) Riferimenti ufficiali: - [CieSign — sito CIE](https://www.cartaidentita.interno.gov.it/pa-e-imprese/firma-elettronica-cie-ciesign/); - [Software CIE ufficiale](https://www.cartaidentita.interno.gov.it/pa-e-imprese/software-cie/); - [CieSign su Google Play](https://play.google.com/store/apps/details?id=it.ipzs.ciesign); - [CieSign su App Store](https://apps.apple.com/it/app/ciesign/id1539026284?platform=ipad). Il docente deve mantenere sotto il proprio controllo CIE, PIN e dispositivo. Il PIN non deve essere comunicato al tutor, alla segreteria o al supporto tecnico. Il formato PDF/PAdES e l’accettabilità giuridica della firma devono essere approvati prima dell’uso reale. ## 11. Cifratura e invio automatici Nel flusso definitivo, dopo la verifica dell’ultima firma, il portale deve: 1. calcolare hash e versione del PDF firmato; 2. cifrare automaticamente il contenuto con una chiave casuale; 3. proteggere la chiave del documento con la chiave pubblica della segreteria; 4. creare un pacchetto cifrato con nome tecnico casuale; 5. depositare soltanto il pacchetto nel contenitore istituzionale; 6. registrare esito, versione, hash e identificativo tecnico; 7. notificare la segreteria senza allegare il PDF in chiaro. Il docente non deve gestire password, archivi, cartelle o chiavi. La chiave privata deve restare fuori dal front-end e dal deposito, con backup cifrato, custodia separata, inventario, rotazione e test di ripristino. La cartella Drive/Nextcloud è una seconda barriera, non la sola misura. Il portale non deve caricare il PDF in chiaro confidando nella cifratura server-side della cartella. ### 11.1 Archivio cifrato della segreteria Per la conservazione automatica si raccomanda questa struttura, senza attività manuali da parte dei docenti: portale → PDF firmato → cifratura applicativa → deposito istituzionale └──────→ volume cifrato della segreteria La cartella di archivio deve contenere esclusivamente pacchetti cifrati, con nomi tecnici casuali. Deve stare su un volume cifrato del server o del computer istituzionale della segreteria, con permessi limitati al servizio di deposito e agli operatori autorizzati. Il PDF in chiaro deve esistere solo nel tempo tecnico necessario ad aprire, verificare e stampare il documento secondo la procedura approvata. Opzioni senza costi di licenza aggiuntivi, da scegliere in base all’infrastruttura già presente: | Scenario | Protezione locale | Nota operativa | |---|---|---| | Server Linux istituzionale | volume dati LUKS + directory con permessi del servizio | soluzione preferibile se la scuola dispone già di un server | | PC/server Windows istituzionale | BitLocker sul volume dati, se incluso nell’edizione disponibile | la chiave di ripristino va custodita dall’istituto, non nel portale | | Mac istituzionale | FileVault sul disco e account separati | adatto a un archivio locale, meno adatto a un servizio multiutente | | Archivio portabile o multipiattaforma | Cryptomator o contenitore equivalente open source | richiede una procedura disciplinata per chiavi, backup e montaggio | La cifratura del volume non sostituisce la cifratura applicativa: protegge il disco a riposo, mentre il pacchetto cifrato protegge il documento anche durante trasporto, sincronizzazione e backup. Se viene usato un NAS, Drive o Nextcloud, il servizio deve ricevere solo i pacchetti cifrati e il backup deve avere versioning, accesso ristretto e almeno una copia offline o logicamente immutabile. La disponibilità di un software gratuito non equivale da sola a conformità: DPO e Dirigente devono approvare titolare, responsabili, ruoli, retention, chiavi, backup e ripristino. ### 11.2 Configurazione consigliata con Drive condivisa Creare una Drive condivisa separata, ad esempio “Inclusione — Deposito crittografato”, amministrata dall’istituto e non da un account personale. La configurazione minima è: | Identità | Ruolo Drive | Cosa può fare | |---|---|---| | Account tecnico del portale | Contributor | caricare i pacchetti cifrati; nessuna chiave privata e nessun PDF in chiaro | | Segreteria autorizzata | Viewer | vedere/scaricare il pacchetto cifrato e aprirlo localmente con la procedura approvata | | Amministratore tecnico/DSGA | Manager | gestire membri, restrizioni e recupero, ma visualizza solo cifrati | Il ruolo Contributor è sufficiente se il sistema deve solo creare i file e non spostarli o cancellarli. Non usare Content manager se non serve. Il deposito deve avere accesso generale disattivato, condivisione esterna vietata, appartenenza limitata ad account istituzionali e audit Drive attivo. Per la segreteria la visualizzazione del file Drive non equivale alla lettura del PDP: il file scaricato è un pacchetto cifrato e viene aperto solo sulla postazione istituzionale autorizzata. Il sistema non deve essere un utente personale del referente. Deve usare un’identità tecnica istituzionale dedicata, con autorizzazione limitata alla Drive di deposito e senza permessi sul resto del patrimonio Drive. Se un’implementazione Apps Script viene eseguita come utente proprietario, quell’ account proprietario deve essere dedicato, protetto e formalmente autorizzato; non inserire credenziali o chiavi nel codice. La “delega privacy” va tradotta in atti distinti: la scuola resta titolare del trattamento; Google Workspace deve essere coperto dal Cloud Data Processing Addendum/DPA accettato dall’amministratore; eventuali altri fornitori devono avere un accordo da responsabile ex art. 28 GDPR; il Dirigente deve designare gli operatori autorizzati e il DPO deve validare DPIA, ruoli, durata, conservazione e gestione degli incidenti. Una semplice condivisione della cartella non costituisce da sola una delega né una conformità privacy. ## 12. Ruolo della segreteria La segreteria: - accede al deposito riservato; - apre il pacchetto con la chiave privata istituzionale; - verifica hash, versione e firme; - stampa o protocolla secondo la procedura approvata; - acquisisce la firma del DS; - acquisisce fisicamente la firma dei genitori; - conserva il documento secondo tempi e sistema approvati; - non invia il PDF tramite email ordinaria. Il portale non deve consentire al docente di aprire, esportare o condividere il vault nome-codice se non esiste una specifica autorizzazione. ## 13. Revisioni GLO e vista staff Per i PEI, aprire **Revisioni GLO** e selezionare il fascicolo. Per ciascuna delle quattro tappe annuali si registrano: - GLO svolto; - data; - riferimento o nota sintetica del verbale; - modifiche al PEI richieste. Se vengono richieste modifiche, il tutor riapre il PEI, aggiorna le sezioni interessate e avvia una nuova verifica prima della firma. La registrazione digitale non sostituisce il verbale GLO, la convocazione né le firme previste. La pagina **Stato staff** mostra pratica, classe, tipo, tutor, stato del workflow, stato GLO e ultimo evento. Durante il rinnovo può mostrare lo stato **Controllo materie**, che blocca le conferme finché il tutor non valida il nuovo quadro. La modalità predefinita usa iniziali e classe; il nome completo deve essere riservato ai ruoli autorizzati che devono identificare il fascicolo. Non vengono mostrati diagnosi, contenuti o codici tecnici. ## 14. Checklist di validazione DPO/dirigente Prima del pilota verificare: - [ ] DPIA approvata o formalmente aggiornata; - [ ] ruoli e autorizzazioni del personale documentati; - [ ] registro dei trattamenti e informativa aggiornati; - [ ] `anagrafica-api` con API e permessi definitivi; - [ ] autorizzazione server-side per classe, PDP, materia e stato; - [ ] codice casuale annuale e vault separato; - [ ] nessuna password reale negli XLS; - [ ] controllo upload, macro, formule, duplicati e malware; - [ ] PDF congelato prima della firma; - [ ] verifica delle firme senza rigenerare il PDF; - [ ] cifratura reale prima del deposito; - [ ] chiave privata fuori dal portale e backup testato; - [ ] audit log senza nomi, diagnosi, token o contenuti; - [ ] conservazione, cancellazione e ripristino definiti; - [ ] prova di incidente e revoca account eseguita; - [ ] pilota iniziale con dati fittizi o classe formalmente autorizzata. ## 14. Risoluzione dei problemi **Non compare l’elenco.** Usare **Carica elenco demo** oppure controllare che il primo foglio contenga alunno, classe e tutor. Verificare che il file non sia vuoto o oltre 5 MB. **L’import viene rifiutato per formula o foglio nascosto.** Aprire una copia del file, incollare solo valori, eliminare formule, collegamenti esterni, macro e fogli nascosti, quindi salvare in XLSX o CSV. **Non si può avviare la firma.** Ogni docente deve prima simulare la modifica e selezionare la spunta. In modalità “Riproponi senza modifiche” deve confermare esplicitamente la riproposizione. **Il pulsante firma è disabilitato.** La raccolta è sequenziale: deve firmare il docente indicato come prossimo. **La demo mostra l’accesso Google non disponibile in locale.** Usare l’accesso ospite per la demo oppure autorizzare l’origine locale in Google Cloud Console. Questo non sostituisce la verifica del token in produzione. ## 15. Documenti collegati - [Schema import elenco](schema-import-elenco.md); - [Guida anteprima CIE/CieSign](guida-ciesign-anteprima.md); - [Studio sicurezza e privacy](studio-sicurezza-privacy.md); - [README del progetto](../README.md).