Fork: 0
fabio / itcca-allievi
Page History

Home

Fabio edited this page 4 hours ago
Pages 1
Clone this wiki locally

ITCCA Allievi — Plugin WordPress per la gestione iscrizioni

Plugin WordPress per gestire le iscrizioni ai corsi di Tai Chi della scuola ITCCA. Estende l'utente WordPress con i ~40 campi del registro INSXXX (dove XXX è la sigla a 3 lettere dell'insegnante che userà il plugin), espone un form pubblico di iscrizione e sincronizza i dati con un Google Sheet privato selezionabile da Drive.

Versione corrente: 1.0.0
Requisiti: WordPress ≥ 6.0, PHP ≥ 8.1
Licenza: GPL-2.0-or-later

Indice

  1. Panoramica
  2. Modello dati
  3. Form pubblico di iscrizione
  4. Backoffice WordPress
  5. Integrazione Google (OAuth + Picker + Sheets)
  6. Sincronizzazione a due fasi
  7. Riconciliazione schema
  8. Dashboard analytics
  9. Mappa geografica e sedi
  10. Stato attivo/inattivo
  11. Storico fogli usati
  12. Sicurezza e GDPR
  13. Disinstallazione e pulizia dati
  14. Setup e sviluppo locale

Panoramica

Il plugin nasce per sostituire il workflow basato su fogli Excel/CSV annuali del registro INSXXX (XXX è la sigla a 3 lettere dell'insegnante che userà il plugin e collegherà il suo foglio personale, es. INSROS, INSBIA, ecc.) con una gestione integrata in WordPress, mantenendo però il foglio Google come fonte di backup e condivisione.

Funzionalità principali:

  • Ruolo allievo dedicato con ~40 campi custom mappati 1:1 sulle colonne del registro INSXXX.
  • Form pubblico via shortcode [itcca_iscrizione] con validazione client + server.
  • Backoffice ricco: list table filtrabile, dashboard analitica, mappa delle residenze e sedi.
  • Sincronizzazione Google Sheets bidirezionale in due fasi distinte (allineamento iniziale + push continuo).
  • Riconciliazione schema per gestire colonne aggiunte/rinominate/ rimosse sul foglio senza perdere dati WordPress.
  • Geocodifica indirizzi via OpenStreetMap Nominatim.
  • Disinstallazione pulita che rimuove tutti i dati del plugin (con opt-out per conservarli).

Modello dati

Tutti i campi sono salvati come user_meta con prefisso itcca_, più l'email che usa il campo nativo user_email di WordPress.

Le 41 colonne del registro INSXXX sono raggruppate in sezioni:

  • Anagrafica: ins, cognome, nome, sesso (M/F), nascita_data, nascita_luogo, cf (Codice Fiscale)
  • Residenza: indirizzo, civico, comune, cap
  • Contatti: user_email, cellulare
  • Calcolati (read-only): X (età), Anno (anni di pratica)
  • Tesseramento: sede_u, centro, ruolo, grado, inizio (anno)
  • Quote (decimal): quota_uisp, quota_itcca, quota_ado
  • Ricevuta/pagamento: pag_chi, pag_il, ric_il, ric_n, att, pag, pro, ric, onl (gli ultimi 5 sono flag booleani)
  • Stato: r (R=rinnovo / N=nuovo), a (A=attivo / D=disattivo), active (derivato dal tab del foglio)
  • UISP card: uisp_n, uisp_d
  • Altro: doc, animale, elem, el_sx, el_dx, note

Il registro è centralizzato in class-fields.php come unica fonte di verità: list table, edit page, form pubblico e push su Sheet leggono sempre da lì (label, tipo, validatore, sezione, visibilità nel form).

Il valore del campo ins (sigla insegnante, es. INSXXX) è configurabile dalle impostazioni del plugin e viene impostato come default su ogni nuovo allievo creato dal form pubblico.

Calendario cinese (Animale + Elementi)

  • Animale è un dropdown con i 12 segni dello zodiaco cinese, auto-calcolato dall'anno di nascita ma sovrascrivibile manualmente.
  • Elemento / Elemento sinistro / Elemento destro sono dropdown con i 5 elementi (Terra, Metallo, Acqua, Legno, Fuoco), ciascuno con un pallino colorato accanto alla label (acqua azzurro, metallo grigio, terra ocra, legno verde, fuoco rosso).

Form pubblico di iscrizione

Shortcode: [itcca_iscrizione] (da inserire in una pagina o articolo).

Tutti i campi sono obbligatori (asterisco rosso, attributo HTML required, ricontrollo server-side). Campi visibili al pubblico:

  • Cognome, Nome
  • Sesso (radio M / F)
  • Data di nascita (date picker)
  • Comune di nascita
  • Codice fiscale
  • Indirizzo di residenza, numero civico, comune di residenza, CAP
  • Email, cellulare
  • Checkbox consenso privacy + liberatoria (testo configurabile)

Tutti gli altri campi del registro vengono compilati dall'admin nel backoffice (sede, quote, ricevuta, flag, ecc.).

Validazioni

  • Codice fiscale: regex ^[A-Z]{6}[0-9]{2}[A-Z][0-9]{2}[A-Z][0-9]{3}[A-Z]$ client-side + checksum ministeriale server-side. Controllo unicità.
  • Email: regex HTML5 + is_email() di WordPress, controllo unicità.
  • CAP: esattamente 5 cifre.
  • Cellulare: regex ^\+?[0-9]{9,15}$ (spazi rimossi).
  • Data di nascita: nel passato, non oltre 120 anni fa.

Protezioni

  • Nonce WordPress
  • Honeypot anti-bot nascosto
  • Rate limiting per IP (max 5 invii / ora) via transient
  • Errori inline sotto ogni campo (sia da JS sia da PHP dopo submit)

Flusso di submit

  1. Validazione client-side
  2. Validazione server-side (sempre, indipendentemente dal client)
  3. Crea utente WordPress con ruolo allievo, username = slug di cognome.nome, password random
  4. Salva tutti i meta
  5. Email di benvenuto all'utente con link per impostare la password
  6. Email di notifica all'admin
  7. Push riga su Google Sheet (con retry differito via WP-Cron se fallisce)
  8. Redirect a pagina di conferma (configurabile nelle impostazioni)

Tema grafico

Il CSS usa variabili CSS (--itcca-primary), currentColor e classi WP standard per ereditare dal tema attivo. Il colore primario è sovrascrivibile dalle impostazioni del plugin.

Backoffice WordPress

Pagina utente standard

/wp-admin/user-edit.php?user_id=X

Sezioni a fisarmonica per ogni gruppo di campi (Anagrafica, Residenza, Tesseramento, Quote, Ricevuta, Stato, UISP, Note). Età e anni di pratica sono mostrati read-only come valori calcolati.

Pagina "Allievi ITCCA"

/wp-admin/admin.php?page=itcca-allievi-list

  • WP_List_Table con tutte le colonne principali, ordinabili
  • Views: Attivi / Inattivi / Tutti (filtro per itcca_active)
  • Filtri rapidi: Centro, R (rinnovi/nuovi), A (attivi/disattivi), anno Inizio
  • Ricerca per cognome, nome, CF
  • Azioni bulk: Sincronizza con Google Sheet, Imposta A=D, Imposta A=A
  • Bottoni: Aggiungi allievo, Esporta CSV, Allinea da foglio (Fase A), Pusha tutti su foglio (Fase B forzata)
  • Animale + Elementi visibili come pallini colorati direttamente in lista (senza dover entrare in edit)

Integrazione Google

Tre passi: credenziali su Google Cloud Console → connessione OAuth → selezione del foglio via Picker.

Wizard di setup OAuth

Sotto Allievi ITCCA → Impostazioni trovi un wizard guidato in 5 step con istruzioni in italiano e link diretti alle pagine giuste di Google Cloud Console:

  1. Crea/seleziona il progetto Cloud
  2. Abilita le API Google Sheets, Google Drive, Google Picker
  3. Configura la schermata di consenso OAuth
  4. Crea un OAuth Client ID di tipo "Web application" con il Redirect URI indicato dal plugin (basta copia/incolla)
  5. Crea una API Key per il Picker (frontend-only)

Validazione live della forma di Client ID/Secret/API Key con badge di stato per ogni step.

Scope richiesti

  • https://www.googleapis.com/auth/spreadsheets (lettura/scrittura del foglio scelto)
  • https://www.googleapis.com/auth/drive.file (accesso ai soli file aperti tramite Picker — privacy-friendly rispetto a drive.readonly)
  • https://www.googleapis.com/auth/userinfo.email (per mostrare con quale account sei connesso)

I token (access + refresh) vengono salvati in wp_options e rinnovati automaticamente alla scadenza.

Selezione del foglio (Google Picker)

Bottone "Seleziona foglio da Drive" → apre il Picker nativo di Google con ricerca/recenti/Drive condivisi, filtrato sui soli Google Sheets.

Una volta scelto il foglio, il plugin:

  1. Memorizza spreadsheet_id, nome, URL Drive
  2. Auto-seleziona il primo tab "ragionevole" (ignora ZZZ*, pivot)
  3. Auto-rileva il tab ZZZ degli allievi inattivi (case-insensitive)
  4. Confronta lo schema delle colonne con quello WP — se diverge, redirect alla pagina di Riconciliazione Schema (vedi sotto)

Sincronizzazione a due fasi

Fase A — Allineamento iniziale (foglio → WordPress)

Quando: ogni volta che colleghi un foglio nuovo (cambio anno) o rilanci manualmente "Allinea da foglio". Sempre disponibile.

  1. Il plugin legge entrambi i tab (attivi + ZZZ) via Sheets API
  2. Per ogni riga cerca un match con un utente WP tramite Codice Fiscale
  3. Calcola un diff cella per cella e mostra una pagina di preview con quattro sezioni:
    • Pannello diagnostico: colonne riconosciute/ignorate per ogni tab, righe scartate (CF mancante/invalido), CF in comune
    • Modifiche di cella da applicare: tabella con checkbox a livello di singola cella, di riga (tutte le celle di un allievo) e globale (seleziona/deseleziona tutto)
    • Solo sul foglio (potenziali nuovi allievi): per ognuno una checkbox "crea utente WP"
    • Solo in WP (mancano sul foglio): per ognuno una scelta:
      • Lascia stare (default)
      • Imposta A=D (disattivo)
      • Pusha sul foglio comunque
  4. Cliccando "Applica selezionati" il plugin:
    • Aggiorna le celle scelte (bulk con cache sospesa e batch insert dei meta tramite meta_input di wp_insert_user)
    • Crea i nuovi utenti flaggati
    • Applica le azioni "Solo in WP"
    • Popola itcca_sheet_row e itcca_sheet_tab
    • Marca il foglio come allineato (aligned_at)
    • Logga l'operazione in itcca_phase_a_log (storico ultime 50)

Durante l'operazione viene mostrato un overlay full-screen con spinner e messaggio rassicurante.

Fase B — Push continuo (WordPress → foglio)

Quando: attiva automaticamente dopo la prima Fase A su un foglio.

  • Hook su profile_update / user_register / salvataggio dalla pagina admin → enqueue di un task di push
  • La mappatura user_id ↔ riga è in itcca_sheet_row
  • Riga esistente → spreadsheets.values.update di tutta la riga
  • Riga mancante → spreadsheets.values.append + aggiorna sheet_row
  • Match di fallback per CF se manca sheet_row
  • Tab di destinazione scelto dal meta itcca_active (1 → tab attivi, 0 → tab ZZZ); il push non sposta righe tra tab, lo spostamento si fa a mano sul foglio
  • Errori loggati in itcca_sync_errors, retry orario via WP-Cron
  • Bottone "Pusha tutti su foglio" per forzare un re-push completo

Cambio anno

  1. Picker → memorizza nuovo spreadsheet_id
  2. Sposta il foglio precedente nello Storico fogli con timestamp di disconnessione
  3. Reset di tutti gli itcca_sheet_row (la mappatura vecchia non vale più)
  4. Disabilita temporaneamente la Fase B
  5. Header diff → eventuale Riconciliazione Schema
  6. Banner persistente: "Foglio nuovo connesso — esegui Fase A prima di abilitare il push automatico"

Riconciliazione schema

Il foglio Google evolve nel tempo: colonne aggiunte, rinominate, rimosse. Il plugin gestisce queste mutazioni preservando i dati WordPress.

Registro campi dinamico

Fields::baseline() contiene i 42 campi INSXXX di partenza. Fields::overrides() (salvato in wp_options['itcca_schema_overrides']) contiene gli scostamenti:

```php [ 'renames' => [ 'animale' => ['csv' => 'Zodiaco', 'renamed_at' => '...'] ], 'deletes' => [ 'el_dx' => ['original_csv' => 'El Dx', 'deleted_at' => '...'] ], 'additions' => [ 'allergie' => ['csv'=>'Allergie','label'=>'...','type'=>'textarea','section'=>'altro','public'=>false,'added_at'=>'...'] ], ]