Guida — Amministratore¶
L'Admin ha accesso completo alla piattaforma: crea altri Admin e Segreteria, configura l'autenticazione, gestisce le edizioni e supervisiona tutto il sistema.
L'Admin deve configurare l'autenticazione a due fattori (MFA) al primo accesso.
Home page e lista utenti¶
Da Gestione → Utenti l'Admin vede tutti gli utenti inclusi gli altri Admin.
Pannello Django Admin¶
Da Gestione → Pannello admin (/admin/) è possibile accedere all'interfaccia Django
per operazioni di basso livello su qualsiasi modello del database.
Usalo solo per operazioni di emergenza o debug che non sono esposte nell'UI normale.
Configurazione autenticazione a due fattori (MFA)¶
Al primo accesso la piattaforma richiede di configurare un'app authenticator TOTP (Google Authenticator, Aegis, Authy, ecc.).
- Scansiona il QR code mostrato con la tua app authenticator.
- Inserisci il codice a 6 cifre generato per confermare.
- Salva i codici di recupero in un posto sicuro: servono se perdi l'accesso all'app.
La pagina Sicurezza (MFA) nel menu utente (in alto a destra) permette di gestire i dispositivi TOTP e rigenerare i codici di recupero.
Obbligo MFA per Segreteria e Incaricati EG¶
Per impostazione predefinita la MFA è obbligatoria anche per Segreteria e Incaricati EG. Un Admin può renderla facoltativa in Impostazioni → Sicurezza → MFA obbligatoria per Segreteria e Incaricati EG.
- Attivato (default): Segreteria e Incaricati EG devono configurare la MFA al primo accesso.
- Disattivato: Segreteria e Incaricati EG possono accedere senza MFA. Per gli Admin resta sempre obbligatoria.
Passkey (accesso senza password)¶
Oltre al TOTP, è possibile aggiungere una passkey per accedere con Face ID, Touch ID, Windows Hello o una chiave hardware (YubiKey) — senza inserire email e password.
Come aggiungere una passkey:
- Accedi normalmente e vai nel menu utente (in alto a destra) → Sicurezza (MFA).
- Trovi la sezione Passkey → clicca Aggiungi passkey.
- Inserisci un nome per il dispositivo (es. "iPhone 16", "MacBook Pro").
- Lascia spuntata l'opzione "Usa come passkey" per poter accedere senza password.
- Clicca Registra passkey — il browser apre la procedura di registrazione biometrica: sblocca con impronta, viso o PIN e segui le istruzioni a schermo.
Come accedere con la passkey:
Nella pagina di login compare il pulsante "Accedi con passkey". Cliccandolo il browser propone le passkey registrate — sblocca il dispositivo e accedi direttamente, senza email né password né TOTP.
Gestione passkey:
Da Sicurezza (MFA) → clicca il numero di passkey configurate → apri la lista per: - Rinominare una passkey (icona matita) - Eliminare una passkey non più usata (icona cestino)
Nota: le passkey sono legate al browser/dispositivo su cui vengono create. Prima di cambiare dispositivo, aggiungi una nuova passkey dal vecchio e poi elimina quella obsoleta.
Configurazione autenticazione social (Google, Microsoft, Apple)¶
Per abilitare i pulsanti "Accedi con Google / Microsoft / Apple" nella pagina di login
segui la guida completa: docs/guide/social_auth.md
In sintesi:
- Ottieni le credenziali OAuth dal provider (Google Cloud Console, portale Azure, Apple Developer Program) — vedi §4 della guida.
- Imposta le variabili d'ambiente nel file
.env.prod: - Aggiorna il record Sites con il dominio di produzione:
- Riavvia l'applicazione. I pulsanti social appaiono automaticamente nel login
solo se la variabile
CLIENT_IDdel provider è valorizzata.
Il social login non crea nuovi utenti da solo: l'email del provider deve corrispondere a un account già esistente in piattaforma (creato tramite invito da Segreteria/Admin).
Configurazione Google Drive OAuth¶
Plancia può caricare automaticamente PDF e file Excel su Google Drive al termine dell'archiviazione di un'edizione. Richiede un'applicazione OAuth separata da quella del social login.
Perché due applicazioni Google OAuth?¶
| Scopo | Variabili env | Scope richiesti |
|---|---|---|
| Social login (accedi con Google) | SOCIAL_GOOGLE_CLIENT_ID/SECRET |
email, profile, openid |
| Google Drive (upload file) | GOOGLE_OAUTH_CLIENT_ID/SECRET |
drive (lettura/scrittura Drive) |
Le due app possono usare lo stesso progetto Google Cloud ma devono avere credenziali OAuth separate perché i permessi (scope) sono diversi.
Passo 1 — Crea le credenziali OAuth per Drive¶
- Vai su console.cloud.google.com → seleziona il progetto già usato per il social login (o creane uno dedicato).
- API e servizi → Libreria → cerca Google Drive API → Abilita.
- API e servizi → Credenziali → Crea credenziali → ID client OAuth 2.0:
- Tipo applicazione: Applicazione web
- Nome:
Plancia Drive - URI di reindirizzamento autorizzati:
- Dev:
http://localhost:8000/drive/oauth/callback/ - Produzione:
https://plancia.agescicampania.org/drive/oauth/callback/
- Dev:
- Copia ID client e Secret client.
Passo 2 — Imposta le variabili d'ambiente¶
Nel file .env.prod (o .env.dev per il test locale):
GOOGLE_OAUTH_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-xxxxx
GOOGLE_OAUTH_REDIRECT_URI=https://plancia.agescicampania.org/drive/oauth/callback/
In dev la redirect URI può essere http:// — la piattaforma imposta automaticamente
OAUTHLIB_INSECURE_TRANSPORT=1 solo nel callback di sviluppo.
Passo 3 — Collega un account Drive a un'edizione¶
Il flusso OAuth Drive non è globale ma per edizione: ogni edizione può usare un account Google Drive diverso.
- Vai su Gestione → Elenco edizioni → clicca sull'edizione da configurare.
- Nel pannello Google Drive clicca Collega account Drive.
- Vieni reindirizzato a Google per autorizzare l'accesso a Drive con l'account Google che contiene le cartelle dell'edizione.
- Dopo il consenso torni alla pagina dell'edizione con l'email dell'account collegato.
- Usando il folder picker puoi selezionare (o creare) le cartelle:
- Cartella allegati: cartella principale dove vengono create le sottocartelle delle foto
- Cartella output: cartella principale dove vengono depositate le sottocartelle PDF/Excel
- Imposta il formato del nome delle sottocartelle per i diari (vedi sezione successiva).
- Clicca Salva e blocca configurazione.
Passo 3b — Formato delle sottocartelle per diario¶
Per ogni diario viene creata automaticamente una sottocartella univoca dentro la cartella allegati e una dentro la cartella output. Il nome della sottocartella è calcolato dal formato configurato nell'edizione.
Variabili disponibili:
| Variabile | Contenuto | Obbligatoria |
|---|---|---|
{id_univoco} |
ID numerico del diario (5 cifre, es. 00042) |
✅ Sì |
{edizione} |
Anno dell'edizione (es. 2026) |
No |
{nome_gruppo} |
Nome del gruppo scout | No |
{nome_zona} |
Nome della zona | No |
{nome_reparto} |
Nome del reparto | No |
{nome_squadriglia} |
Nome della squadriglia | No |
{specialita} |
Specialità di squadriglia (se compilata) | No |
Formato di default:
Esempio di cartella generata: 00042_2026_Salerno1_Reparto1_Aquile_Campismo
I caratteri non validi (spazi, accenti, simboli) vengono sostituiti automaticamente con underscore al momento della creazione.
⚠️ Attenzione — configurazione irreversibile: una volta salvate le due cartelle principali e il formato, non è più possibile modificarli. Le sottocartelle vengono create automaticamente la prima volta che viene caricata una foto o generato un PDF per ciascun diario. Verifica attentamente i valori prima di salvare.
La pagina mostra un'anteprima live del nome che verrebbe generato e, sotto ciascun ID cartella, il nome reale su Drive come link cliccabile.
Passo 4 — Test dell'upload¶
Dopo aver collegato l'account, puoi verificare il funzionamento generando un PDF di prova da un diario completato e controllando che compaia nella cartella Drive configurata.
Note di sicurezza¶
- Le credenziali OAuth Drive (access token + refresh token) sono memorizzate nella tabella
storage_drive_drivecredenzialidel database. Il database è cifrato a riposo in produzione. - Un refresh token scade se l'app Google non viene usata per 6 mesi o se l'utente revoca l'accesso dal proprio account Google. In quel caso basta ripetere il flusso di collegamento (passo 3).
- Lo scope richiesto è
https://www.googleapis.com/auth/drive(accesso completo al Drive dell'account autorizzato). Considera di usare un account Google dedicato (es.archivio@agescicampania.it) per limitare l'esposizione dei file personali.
Pagina Impostazioni¶
La pagina Impostazioni (/impostazioni/) è divisa in sezioni indipendenti, ognuna
con il proprio pulsante Salva. Un errore in una sezione non blocca il salvataggio
delle altre.
| Sezione | Contenuto |
|---|---|
| Identità | Titolo e sottotitolo della piattaforma |
| Footer | Testo HTML del footer (supporta {{ titolo }}, {{ versione }}, {{ commit }}); link laterali |
| Posta elettronica | Modalità invio, backend SMTP / provider transazionale, Gmail OAuth2, test invio |
| Sicurezza | MFA, protezione brute-force (axes) |
| Allegati | Dimensione massima immagini in upload |
| Diagnostica | Manutenzione, debug-toolbar; link rapidi a Flower e Mailpit |
| IP bloccati | Lista IP bloccati da django-axes con sblocco singolo o massivo |
| Strumenti | Link a Cache PDF (/impostazioni/cache-pdf/) e Log export (/impostazioni/log-export/) |
| Import tracciati | Carica CSV Co.Ca. / Squadriglie / Ragazzi; storico import |
| Pagine legali | Modifica Privacy Policy e Condizioni del Servizio; carica contenuto predefinito |
| Template email | Visualizza e personalizza i template delle email automatiche |
Sezione Posta elettronica¶
- Nome mittente: testo visualizzato come mittente (es. "Plancia AGESCI Campania"). Combinato
con il campo Mittente (from) produce il formato
Nome <email@dominio.it>. - Modalità invio: Invio reale, Simulato, Simulato + invio reale, Mailpit. In modalità Simulato + invio reale le email vengono scritte sia su file che inviate davvero — utile per testare in produzione senza rischiare.
- Test SMTP / Test provider transazionale: invia un'email di prova alla tua casella usando il rispettivo backend (ignora la modalità simulato).
- Gmail OAuth2: se collegato, i campi SMTP manuali vengono nascosti e sostituiti dall'autenticazione OAuth2.
Sezione Sicurezza¶
- Tentativi prima del blocco (default 5): dopo quanti tentativi falliti l'IP viene bloccato.
- Minuti di blocco automatico (default 10): il blocco si scioglie automaticamente. 0 = blocco permanente fino allo sblocco manuale.
- Scadenza tentativi (default attivo): i tentativi falliti scadono dopo il periodo di blocco e non vengono più conteggiati.
- IP bloccati: lista degli IP attualmente bloccati con possibilità di sblocco singolo o massivo.
Sezione Allegati¶
- Dimensione massima immagini: lato maggiore in pixel. Al caricamento, le immagini più grandi vengono ridimensionate e salvate come JPEG quality 85. Il valore si applica agli allegati, non alle immagini nel footer o nei template email.
Cache PDF e generazione massiva¶
Da Gestione → Cache PDF (o dal link in Impostazioni → Strumenti) è possibile:
- Lista PDF in cache: per ogni edizione vengono mostrati i PDF già generati e caricati su Drive, con dimensione e data di caricamento.
- Invalidazione singola: elimina il PDF di una squadriglia dalla cache (il prossimo PDF sarà rigenerato).
- Invalidazione per edizione o totale: svuota la cache di un'edizione o di tutte.
- Generazione massiva: avvia un task Celery che genera i PDF di tutti i diari inviati dell'edizione selezionata, li carica su Drive e invia aggiornamenti via email ogni 10 diari. Durante la generazione i PDF singoli per quella edizione sono disabilitati.
- Interrompi: ferma ordinatamente una generazione massiva in corso. Il task completa il diario corrente e poi si arresta; il log riporta "Interrotta" con il conteggio parziale.
Durante una generazione massiva attiva il selettore mostra "(generazione in corso…)" e l'opzione è disabilitata per evitare doppie esecuzioni. Il lock viene rilasciato automaticamente al termine o dopo 2 ore.
Log generazione PDF/Excel¶
Da Gestione → Log export (o dal link in Impostazioni → Strumenti) è disponibile lo storico completo dei task di generazione PDF e Excel:
- Stato del task (completato / errore), tipo di export, data e richiedente.
- Per i task in errore: traceback completo apribile in un modale.
- I task di generazione massiva vengono registrati con il tipo
PDF massivo — Edizione XXXX. - Gli errori generano automaticamente una notifica email al richiedente e agli Admin.
Strumenti di sviluppo nel menu Gestione¶
Il menu Gestione (in alto a destra, visibile a tutto lo staff) contiene la sezione Strumenti di sviluppo con accesso diretto a:
- Flower (
/celery/): dashboard Celery con task attivi, coda, worker e cronologia. - Mailpit (
/mailadmin/): web UI per le email di debug in sviluppo/staging.
Flower deve essere avviato con il profilo opzionale:
Configurazione email: dual-backend e Gmail OAuth2 SMTP¶
Plancia supporta due backend email indipendenti: SMTP (anche Gmail via OAuth2) e provider transazionale (Brevo, Mailgun, ecc.). I due backend vengono usati automaticamente in base al tipo di invio, oppure puoi sceglierli manualmente prima di ogni invio bulk.
Guida completa: docs/guide/email_provider.md
Routing automatico¶
| Tipo di invio | Backend predefinito |
|---|---|
| Email di sistema (password reset, MFA, notifiche) | SMTP |
| Inviti bulk Capi Reparto / Capi Squadriglia | Provider transazionale |
Modificabile in Impostazioni → Posta elettronica → campi Backend email standard e Backend invii massivi.
Gmail OAuth2 SMTP¶
Se usi Gmail come SMTP, configura l'autenticazione OAuth2 invece di username e password.
Setup rapido:
-
Nelle credenziali OAuth del tuo progetto Google Cloud (stesse usate per il Drive), aggiungi il redirect URI:
https://plancia.agescicampania.org/impostazioni/gmail-smtp/oauth/callback/ -
In
.env.prodaggiungi: -
In Impostazioni → Posta elettronica → Backend SMTP → clicca Collega Gmail → autorizza l'account Google da cui vuoi inviare.
Il token di accesso viene rinnovato automaticamente. Puoi scollegare l'account in qualsiasi momento.
Vedi la guida completa per i dettagli su Gmail API, verifica dell'app e revoca.
Archiviazione di un'edizione¶
Al termine dell'edizione:
# Genera PDF di tutti i diari + Excel esiti e carica su Drive
uv run python manage.py archivia_edizione --edizione 1 --genera
# (Dopo verifica) elimina le foto, marca l'edizione archiviata
uv run python manage.py archivia_edizione --edizione 1 --purga --conferma
Il comando --purga elimina fisicamente le foto caricate (trattamento dati minori)
mantenendo i link esterni come testo. I PDF e l'Excel rimangono su Drive.
Backup¶
Il backup notturno è configurato via cron (vedi deploy/crontab.example):
Il backup include dump PostgreSQL + archivio media/log con retention 30 giorni.
Cambio referenti dei diari¶
L'Admin ha accesso alle stesse funzionalità di cambio referenti descritte nella Guida Segreteria:
- Cambia Capo Reparto sul singolo diario (dalla pagina di dettaglio)
- Cambia Capo Reparto in bulk per un intero reparto (dalla lista diari)
In aggiunta, l'Admin può sempre accedere al pannello Django Admin per modifiche di emergenza su qualsiasi diario indipendentemente dallo stato.
Crea utente staff¶
Da Gestione → Persone → Crea utente staff Admin e Segreteria possono creare direttamente utenti con ruolo Admin, Segreteria o Incaricato EG senza passare per il codice socio AGESCI. Questa funzione è pensata per i gestori della piattaforma che non sono necessariamente soci registrati.
Il form richiede: nome, cognome, email e ruolo. Al salvataggio viene inviata automaticamente un'email di reset password all'indirizzo indicato, consentendo all'utente di impostare la propria password al primo accesso.
Solo gli Admin possono creare altri Admin. La Segreteria può creare Segreteria e Incaricati EG.
Pagine legali¶
Da Impostazioni → Pagine legali è possibile modificare i contenuti di Privacy Policy
(/privacy/) e Condizioni del Servizio (/termini/).
Per ogni pagina sono disponibili tre azioni: - Apri (icona esterna): visualizza la pagina pubblica in una nuova scheda. - Predefinito: carica il testo di base fornito dalla piattaforma (con confirm di sovrascrittura). Il testo predefinito è pensato come punto di partenza per la Privacy Policy GDPR e le Condizioni del Servizio dell'AGESCI Campania — personalizzalo prima di pubblicarlo. - Modifica: apre l'editor HTML per personalizzare il contenuto.
Gestione Inviti e primo accesso utenti¶
L'Admin ha accesso alla pagina Gestione Inviti (stessa della Segreteria). Vedi la sezione corrispondente nella Guida Segreteria per il dettaglio del flusso inviti Capi Reparto e Capi Squadriglia.
Impersonazione¶
L'Admin può impersonare qualsiasi utente compresa la Segreteria. Ogni impersonazione viene registrata nel log di audit. La Segreteria non può impersonare l'Admin.