ITCCA Allievi — WordPress plugin per iscrizioni Tai Chi

Stack Docker locale + plugin WordPress che estende l'utente con i campi del CSV INSARRI, espone un form pubblico di iscrizione e sincronizza i dati con un Google Sheet privato selezionabile da Drive.

Il piano completo del progetto vive in .cursor/plans/itcca_allievi_wp_plugin.plan.md.

Requisiti

• Docker Desktop (o Docker Engine + Compose v2)
• Porte libere 8080 (WordPress) e 8081 (phpMyAdmin) — modificabili in .env
• Un account Google con accesso al foglio di gestione iscrizioni

Avvio rapido

cp .env.example .env       # se vuoi cambiare credenziali/porte di sviluppo
docker compose up -d

Poi:

• WordPress: http://localhost:8080 (completa il wizard di installazione: lingua italiana, titolo sito a piacere, utente admin)
• phpMyAdmin: http://localhost:8081 (utente root / password da .env)
• Attiva il plugin in Plugin → Allievi ITCCA (dopo aver installato le dipendenze, vedi sotto)

Installazione dipendenze del plugin

Il plugin usa la libreria google/apiclient. Si installa con Composer dentro un container temporaneo, in modo da non dover avere PHP/Composer sul tuo Mac:

docker compose run --rm composer install

I file finiscono in plugin/itcca-allievi/vendor/ (escluso da git).

Comandi utili

docker compose ps                                # stato dei container
docker compose logs -f wordpress                 # log live
docker compose down                              # ferma tutto (DATI PRESERVATI nei volumi)
docker compose down -v                           # ferma e CANCELLA TUTTO (DB + WP)

docker compose run --rm composer update          # aggiorna dipendenze del plugin
docker compose run --rm wpcli wp user list       # esempio WP-CLI
docker compose run --rm wpcli wp plugin activate itcca-allievi

Configurazione Google Cloud Console

Per usare la sincronizzazione con Google Sheets serve un OAuth Client ID e una API Key del progetto Google Cloud.

1. Creare il progetto

1. Vai su https://console.cloud.google.com/projectcreate
2. Crea un nuovo progetto (es. "ITCCA Allievi")
3. Selezionalo nel selettore in alto

2. Abilitare le API necessarie

In API e servizi → Libreria abilita:

• Google Sheets API
• Google Drive API
• Google Picker API

3. Configurare la schermata di consenso OAuth

In API e servizi → Schermata di consenso OAuth:

• Tipo utente: Esterno (anche se userai solo il tuo account)
• Nome app: "ITCCA Allievi" (o quello che preferisci)
• Email di supporto: la tua
• Domini autorizzati: puoi lasciare vuoto in sviluppo locale
• Scope: aggiungi .../auth/spreadsheets e .../auth/drive.file
• Utenti di test: aggiungi la tua email Google (necessario perché l'app è in modalità "test")

4. Creare l'OAuth Client ID

In API e servizi → Credenziali → Crea credenziali → ID client OAuth:

• Tipo: Applicazione web
• Nome: "ITCCA Allievi WordPress"
• URI di reindirizzamento autorizzati: http://localhost:8080/wp-admin/admin.php?page=itcca-allievi-oauth
• Salva e copia Client ID e Client Secret

5. Creare la API Key (per il Picker)

In API e servizi → Credenziali → Crea credenziali → Chiave API:

• Copia la chiave
• Clicca su "Limita chiave" e:
  • Restrizioni applicazioni: HTTP referrer → aggiungi http://localhost:8080/*
  • Restrizioni API: limita a Google Picker API + Google Drive API

6. Inserire le credenziali nel plugin

WordPress admin → Allievi ITCCA → Impostazioni → Sezione Google:

• OAuth Client ID
• OAuth Client Secret
• Picker API Key

Clicca "Connetti Google" e autorizza il tuo account. Poi clicca "Seleziona foglio da Drive" e scegli il foglio dell'anno corrente.

Struttura del progetto

Itcca-allievi/
├── .cursor/
│   └── plans/
│       └── itcca_allievi_wp_plugin.plan.md   # piano del progetto
├── docker-compose.yml
├── .env                                       # credenziali dev (NON committare)
├── .env.example
├── .gitignore
├── README.md                                  # questo file
└── plugin/
    └── itcca-allievi/                         # plugin WordPress (montato in wp-content/plugins)
        ├── itcca-allievi.php
        ├── composer.json
        ├── includes/
        ├── assets/
        └── templates/

Persistenza dei dati

Lo stack usa due volumi Docker nominati:

• itcca-allievi_db_data — database MariaDB (tutte le iscrizioni, le impostazioni, gli utenti)
• itcca-allievi_wp_data — tutti i file di WordPress (config, uploads, temi, plugin di terze parti)

docker compose down ferma i container ma conserva i volumi. docker compose down -v cancella anche i volumi (azzera l'ambiente).

Il codice del plugin sta in ./plugin/itcca-allievi/ come bind-mount: modifiche immediate, niente rebuild.

Troubleshooting

• "Errore database" al primo avvio: il container DB ci mette qualche secondo a inizializzarsi. Aspetta 30s e ricarica.
• Conflitto porta 8080: cambia WP_PORT in .env e rilancia docker compose up -d. Ricorda di aggiornare anche l'URI di redirect OAuth in Google Cloud Console se cambi porta.
• Reset totale: docker compose down -v && docker compose up -d
• Permessi sui file del plugin: i container girano come www-data (uid 33). Se vedi errori di scrittura, da host: sudo chown -R $USER:staff plugin/.