Fork: 0
fabio / tonitalia-pluginsoci
Page History

Home

Fabio Arrigoni edited this page 1 hour ago
Pages 1
Clone this wiki locally

Wiki — Plugin TON Italia Registration

Repository: https://niphredil.duckdns.org/git/fabio/tonitalia-pluginsoci.git
Cartella WordPress: wp-content/plugins/ton-italia-registration/
Versione attuale: 1.8.2
Organizzazione: TON ITALIA ODV

1. Scopo del plugin

Gestisce il processo di domanda di ammissione a socio e tesseramento TON ITALIA ODV:

  • Form pubblico fedele al modulo PDF (campi anagrafici, dichiarazioni, privacy).
  • Creazione utente WordPress Subscriber (senza accesso wp-admin).
  • Notifiche email admin e richiedente.
  • Pannello back-office per ammissione, documenti e GDPR.
  • CAPTCHA integrato (nessun servizio esterno).

2. Requisiti

Requisito Valore
WordPress 6.0+
PHP 8.0+ (8.1+ consigliato in produzione Aruba)
Permessi admin manage_options per gestione iscrizioni
SMTP / mail wp_mail funzionante (hosting o plugin SMTP)

3. Installazione

  1. Copiare ton-italia-registration in wp-content/plugins/.
  2. Plugin → Plugin installati → Attiva “TON Italia Registration”.
  3. All’attivazione: creazione tabella DB {prefisso}ton_registrations, cartella upload Documenti Iscritti, opzioni default (testi da PDF).
  4. Creare pagina (es. “Iscrizione socio”) e inserire:
[ton_registration_form]
  1. TON Iscrizioni → Impostazioni: verificare testi, IBAN, email, CAPTCHA.

Attributo shortcode opzionale

[ton_registration_form class="mia-classe-css"]

Aggiunge una classe al wrapper .ton-reg-form per stili custom nel tema.

4. Flusso utente (frontend)

flowchart TD
    A[Utente apre pagina con shortcode] --> B[Compila form]
    B --> C[CAPTCHA + validazione]
    C --> D{OK?}
    D -->|No| E[Messaggio errore sulla pagina]
    D -->|Sì| F[Crea utente Subscriber]
    F --> G[Salva riga DB + meta]
    G --> H[Email admin + email utente]
    H --> I[Messaggio successo]

4.1 Sezioni del form (ordine)

  1. Quota associativa — testo informativo (bonifico, IBAN, quota) da impostazioni; checkbox opzionale “Ho effettuato il bonifico”.
  2. Dati anagrafici — cognome, nome, nascita, CF, residenza, telefono, email.
  3. Dichiarazione — testo statuto (editabile), luogo/data, checkbox accettazione (sostitutivo firma).
  4. Privacy — informativa breve, checkbox privacy obbligatoria, newsletter (opzionale o obbligatoria da settings).
  5. Verifica anti-spam — se CAPTCHA attivo: somma matematica + honeypot.

4.2 Formato date

Le date (nascita e dichiarazione) sono in formato gg-mm-aaaa (es. 25-05-1990).
In database vengono salvate come aaaa-mm-gg.

4.3 Dopo l’invio

  • Redirect alla stessa pagina con ?ton_reg=success (messaggio HTML da impostazioni).
  • Creazione account con email univoca; login generato dalla parte locale dell’email (mario, mario1, … se collisioni).
  • Email utente con link reimposta password (WordPress standard).
  • Ruolo: subscriber — bloccato su /wp-admin/ e barra admin nascosta.

5. Sicurezza form

Meccanismo Descrizione
Nonce WordPress ton_reg_nonce su ogni submit
Honeypot Campo nascosto ton_reg_website — se compilato, rifiuto
Tempo minimo Form non inviabile prima di ~3 secondi dal caricamento
CAPTCHA matematico Domanda casuale (es. 4+7), risposta in transient legata al token
Rate limit IP Default: max 5 tentativi / 15 min (impostazioni)
Validazione server CF, CAP 5 cifre, province 2 lettere, email, date, checkbox obbligatori
Duplicati Blocco se email o CF già in iscrizione pending o admitted

6. Database

Tabella {prefisso}ton_registrations

Contiene tutti i campi del form + metadati legali:

Campo Note
registration_ip IP al momento dell’invio (finalità legali)
user_agent Troncato a 255 caratteri
privacy_text_version Versione informativa al consenso
consent_statuto_at, consent_privacy_at Timestamp UTC
consenso_statuto, consenso_privacy, consenso_newsletter 0/1
status pending \ admitted \ rejected
libro_associati_date Solo admin — data Libro Associati
doc_identita_id, doc_bonifico_id, doc_pagamento_id ID attachment Media
admin_notes, gdpr_log Note e log azioni GDPR
anonymized_at Se anonimizzato

Mirror parziale anche in user_meta con prefisso ton_reg_*.

Tabella {prefisso}ton_reg_membership_cards (v1.7+)

Tessere PDF generate per (registration_id, year).

Tabella {prefisso}ton_reg_membership_renewals (v1.8+)

Quote associative per anno: status (pending | paid), timestamp promemoria gennaio.

7. Pannello admin — TON Iscrizioni

Menu WordPress: TON Iscrizioni (icona groups).

7.1 Elenco

  • Filtri: Tutti / In attesa / Ammessi / Non ammessi / Quota da pagare.
  • Ricerca per nome, email, codice fiscale.
  • Colonne: ID, cognome, nome, email, stato, Rinnovo (quota anno corrente), data.
  • Link Dettaglio per ogni riga.
  • Pulsante Esporta CSV Libro Soci: scarica tutti i soci ammessi (esclusi anonimizzati) in CSV con anagrafica, contatti, data iscrizione e data Libro Associati. File UTF-8 con separatore ; per Excel italiano.

7.2 Dettaglio singola iscrizione

Barra navigazione: Socio precedente / Socio successivo (mantiene filtri e ordinamento dell'elenco).

Documenti (solo backend, upload admin):

Tipo Colonna DB Formati
Documento di identità doc_identita_id PDF, JPG, PNG
Ricevuta versamento tessera doc_pagamento_id PDF, JPG, PNG

File salvati in Media WordPress, percorso fisico:

wp-content/uploads/Documenti Iscritti/{nome-cognome-codicefiscale}/file.pdf

La cartella base viene creata all’attivazione plugin; la sottocartella iscritto alla prima iscrizione o al primo upload.

Tessere PDF (v1.7+) — per soci ammessi:

  • Generazione automatica al passaggio in stato Ammesso.
  • Template PDF annuale configurabile in TON Iscrizioni → Tessere.
  • Batch «Genera tessere nuovo anno» per tutti gli ammessi.
  • PDF in Documenti Iscritti/{socio}/tessere/.

Quote associative annuali (v1.8+) — checkbox «Pagata» per ogni anno solare, dall'anno iscrizione all'anno in corso (l'anno successivo compare a gennaio).

Consensi e dichiarazioni (sezione dedicata):

  • Dichiarazione statuto — Sì/No + data/ora registrata.
  • Privacy e trattamento dati — Sì/No + data/ora + versione informativa.
  • Newsletter — accettato o non espresso.
  • Bonifico dichiarato — checkbox form opzionale.
  • Luogo e data dichiarazione.

Dati anagrafici — tabella read-only dei campi inviati.

Gestione stato (Consiglio Direttivo):

  • Stato: In attesa / Ammesso / Non ammesso.
  • Data Libro Associati.
  • Note admin.

GDPR:

  • Esporta JSON / CSV.
  • Anonimizza (mantiene record, cancella PII).
  • Elimina definitivamente (utente WP + riga DB).

7.3 Impostazioni

Gruppo Opzioni
Quota Anno sociale, importo €, beneficiario, IBAN
Testi form Istruzioni bonifico (HTML), dichiarazione statuto, privacy, newsletter, minorenni, messaggio successo
Email Oggetto/corpo admin e utente; email promemoria rinnovo (1 e 25 gennaio); riepilogo admin rinnovi; email notifiche; contatto GDPR
Comportamento CAPTCHA on/off, newsletter obbligatoria, rate limit, elimina utenti alla disinstallazione
Mailchimp Integrazione attiva, API key, List ID (Audience), tag (es. «Socio TON ITALIA»), test connessione

7.4 Integrazione Mailchimp (v1.6+)

Quando un richiedente spunta il consenso newsletter nel form, l’email viene sincronizzata con Mailchimp (solo se l’integrazione è attiva e configurata). L’iscrizione socio non viene mai bloccata da errori Mailchimp.

Configurazione:

  1. Mailchimp → Account → Extras → API keys → crea chiave.
  2. Audience → Settings → Audience ID (List ID).
  3. In TON Iscrizioni → Impostazioni → Integrazione Mailchimp: attiva, inserisci API key e List ID, salva.
  4. Clic Test connessione Mailchimp (verifica credenziali e memorizza eventuali marketing permissions GDPR della lista).

Comportamento tecnico:

  • Sync asincrona (WP-Cron) dopo invio form riuscito.
  • Upsert sicuro: status_if_new: subscribed (non re-iscrive contatti unsubscribed senza nuovo consenso).
  • Se l’utente si è disiscritto in passato ma spunta di nuovo la newsletter sul form TON, viene ripristinato subscribed.
  • Contatti in stato cleaned (bounce): errore in admin, gestione manuale.
  • Tag applicati via API dedicata (max 5, separati da virgola nelle impostazioni).

Dettaglio iscrizione: sotto consenso newsletter compare lo stato sync (pending, synced, error) con pulsante Riprova iscrizione Mailchimp se necessario.

Sicurezza: API key salvata con autoload = no, campo password in admin (lasciare vuoto per non modificare), accesso solo a manage_options.

Placeholder email: {nome}, {cognome}, {email}, {codice_fiscale}, {ip}, {login_url}, {gdpr_contact}, {admin_url}

Placeholder istruzioni bonifico: {quota}, {anno}, {beneficiario}, {iban}, {nome}, {cognome}

In cima alla pagina: istruzioni per shortcode [ton_registration_form].

7.5 Profilo socio (v1.7.1+)

I Subscriber accedono solo a Profilo in wp-admin (profile.php) e possono scaricare la tessera PDF dell'anno.

  • Placeholder email {profile_url}.
  • Shortcode legacy [ton_registration_profile] mantenuto per retrocompatibilità.

8. Email

Admin

Inviata a ton_reg_admin_email (default: email amministratore sito).
Contiene riepilogo e link alla scheda iscrizione in admin.

Utente

Inviata all’email del form.
Include istruzioni bonifico, contatto GDPR, invito a impostare password via wp_lostpassword_url().
Viene anche inviata la notifica WordPress standard nuovo utente (wp_send_new_user_notifications).

Nota: configurare SPF/DKIM su Aruba o usare plugin SMTP se le mail non arrivano.

Rinnovo quota annuale (v1.8+)

La tessera associativa copre l'anno solare (1 gennaio – 31 dicembre). Il plugin traccia il pagamento della quota per ogni anno nella tabella ton_reg_membership_renewals.

Gestione admin:

  • Elenco iscrizioni: colonna Rinnovo con stato quota anno corrente (Pagato / Da pagare / Sollecito / Non pagato).
  • Filtro Quota da pagare (ammessi senza quota pagata per l'anno in corso).
  • Dettaglio iscrizione: sezione Quote associative annuali con checkbox «Pagata» per ogni anno (da anno iscrizione all'anno in corso; l'anno successivo compare automaticamente a gennaio).

Promemoria automatici (WP-Cron giornaliero):

Data Destinatari Contenuto
1 gennaio Soci ammessi senza quota pagata Primo promemoria con istruzioni bonifico
25 gennaio Stessi soci ancora senza pagamento Secondo sollecito
Stesse date Email admin (ton_reg_admin_email) Riepilogo elenco soci da pagare

Testi email configurabili in Impostazioni (oggetto/corpo primo e secondo promemoria, riepilogo admin).

Placeholder email rinnovo: {nome}, {cognome}, {email}, {anno}, {quota}, {beneficiario}, {iban}, {payment_instructions}, {profile_url}, {gdpr_contact}. Admin rinnovi: {lista_soci}, {numero_soci}, {anno}, {admin_url}.

Soci già ammessi prima dell'aggiornamento: nessun backfill automatico; risultano «da pagare» finché l'admin non spunta la checkbox o fino ai promemoria di gennaio.

Anno inizio promemoria (ton_reg_renewal_reminders_start_year, default 2027): nessuna email automatica parte all'installazione/aggiornamento del plugin; i primi invii avvengono solo dal 1 gennaio dell'anno configurato (poi sollecito il 25 gennaio). Modificabile in Impostazioni → Anno inizio promemoria rinnovo.

Affidabilità cron: WP-Cron richiede visite al sito; per invii puntuali a inizio gennaio configurare un cron di sistema che chiami wp-cron.php.

9. GDPR

Raccolta

  • Informativa visibile prima dei checkbox privacy.
  • Consensi espliciti con timestamp.
  • IP registrato (base giuridica documentata nelle impostazioni editabili).

Diritti (azioni admin)

Azione Effetto
Esporta JSON/CSV Dump dati iscrizione + meta utente WP
Anonimizza PII sostituiti con ANONIMIZZATO; mantiene ID e date consenso; utente WP con email fittizia
Elimina wp_delete_user() + cancellazione riga tabella + documenti

Contatto predefinito interessato: qeshet.tonitalia@gmail.com (modificabile).

Privacy by design

  • Nessun tracking terze parti nel form.
  • Minimizzazione campi rispetto al PDF modulo.

10. Disinstallazione

Disattivazione: non cancella dati.

Eliminazione plugin (da Plugin → Elimina):

  • Drop tabella ton_registrations e ton_reg_membership_renewals.
  • Rimozione opzioni ton_reg_* e transient ton_reg_*.
  • Eliminazione cartella wp-content/uploads/Documenti Iscritti/.
  • Gli utenti Subscriber creati dal plugin restano (default).

Opzione “Elimina utenti alla disinstallazione” in Impostazioni: se attiva prima della rimozione, cancella anche gli utenti WP collegati alle iscrizioni.

11. Struttura codice (sviluppatori)

ton-italia-registration.php    Bootstrap
includes/
  class-plugin.php             Orchestrazione, upgrade DB
  class-registration-form.php  Shortcode + HTML form
  class-registration-handler.php Submit, validazione, save
  class-captcha.php            Anti-spam
  class-user-manager.php       Subscriber + login univoco
  class-database.php           CRUD tabella
  class-mailer.php               wp_mail + promemoria rinnovo
  class-membership-renewals.php  Quote annuali per anno
  class-renewal-reminders.php    Cron promemoria gennaio
  class-membership-card.php      Generazione tessera PDF (FPDI)
  class-membership-cards.php     CRUD tessere
  class-members-export.php       Export CSV Libro Soci
  class-profile.php              Profilo subscriber + download tessera
  class-gdpr.php                 Export / anonimizza / erase
  class-documents.php          Upload Media per iscritto
  class-defaults.php           Testi default PDF
admin/
  class-admin.php              Menu, settings, dettaglio
  class-registration-list-table.php
assets/css, assets/js          Form frontend
uninstall.php                  Hook disinstallazione

12. Upgrade versione plugin

  1. Backup DB e cartella Documenti Iscritti.
  2. Sostituire cartella plugin (o git pull).
  3. Visitare qualsiasi pagina admin — maybe_upgrade() esegue dbDelta se serve nuove colonne.
  4. Verificare TON Iscrizioni → Elenco e una scheda dettaglio.

13. Risoluzione problemi

Problema Soluzione
Form non appare Pagina contiene shortcode? Plugin attivo?
Email non arrivano Test SMTP; spam; wp_mail log
“Email già registrata” Utente WP o iscrizione attiva esistente
Elenco vuoto ma conta 1 iscrizione Aggiornare a v1.3+ (fix paginazione)
PHP compatibility warning Hosting PHP ≥ 8.0
Upload documento fallisce Permessi uploads/, max upload PHP, formato PDF/JPG/PNG
Subscriber accede wp-admin Plugin blocca redirect; verificare ruolo subscriber

14. Workflow operativo consigliato (segreteria)

  1. Richiesta arriva → email admin + stato In attesa.
  2. Verificare dati e caricare documento identità / ricevute in dettaglio.
  3. Verificare bonifico su conto corrente.
  4. Consiglio Direttivo: impostare Ammesso o Non ammesso + data Libro Associati.
  5. Segnare Quota pagata per l'anno di iscrizione nella scheda socio.
  6. Nel dettaglio iscrizione usare Socio precedente / Socio successivo per scorrere l'elenco senza tornare indietro.
  7. A gennaio: verificare colonna Rinnovo / filtro Quota da pagare; i promemoria email partono il 1 e il 25 gennaio.
  8. Comunicazione esterna all'iscritto (fuori plugin o email manuale).
  9. Su richiesta cancellazione dati: Anonimizza o Elimina da scheda GDPR.

15. Repository Git

cd wp-content/plugins/ton-italia-registration
git pull origin master
git add .
git commit -m "v1.x: descrizione"
git push origin master

Pacchetti zip release in releases/ton-italia-registration-X.Y.Z.zip (nel repository GitBucket, tag vX.Y.Z).

Download ultima release (1.8.2):
https://niphredil.duckdns.org/fabio/tonitalia-pluginsoci/raw/v1.8.2/releases/ton-italia-registration-1.8.2.zip

Per generare un nuovo zip dal progetto sito: ./deploy/build-plugin-zip.sh nella root di tents-of-nations, poi copiare in releases/ del repo plugin.

Importante — struttura zip: il file zip deve contenere la cartella ton-italia-registration/ come radice. WordPress deve sostituire la cartella esistente, non crearne una nuplicata.

16. Changelog sintetico

Versione Novità principali
1.8.2 Checkbox quote solo fino all'anno in corso
1.8.1 Anno inizio promemoria 2027; navigazione socio prec/succ in dettaglio
1.8.0 Rinnovo quota annuale, promemoria email 1/25 gen, colonna Rinnovo
1.7.4 Export CSV Libro Soci
1.7.3 Nome su due righe nel PDF tessera
1.7.2 Fix upload template PDF tessera
1.7.1 Profilo socio in profile.php
1.7.0 Tessere PDF, batch annuale, FPDI
1.6.7 Date dichiarazione non future
1.6.6 Pagina conferma shortcode success
1.6.3 Rimossa ricevuta bonifico legacy
1.6.1 Fix test Mailchimp
1.6 Integrazione Mailchimp su consenso newsletter
1.5 Ricevuta versamento tessera
1.4 Sezione consensi in dettaglio admin
1.3 Fix elenco iscrizioni
1.2 Date form gg-mm-aaaa
1.1 Upload documenti identità
1.0 Release iniziale

17. Contatti tecnici

  • Sviluppo: Fabio Arrigoni
  • GDPR operativo TON: qeshet.tonitalia@gmail.com (configurabile in plugin)