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

Vai su https://console.cloud.google.com/projectcreate
Crea un nuovo progetto (es. "ITCCA Allievi")
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/.