Fork: 0
fabio / tonitalia-pluginsoci
Transfer to URL with SHA Find file
Newer
Older
tonitalia-pluginsoci / WIKI.md
@Fabio Arrigoni Fabio Arrigoni 2 hours ago 17 KB v1.8.2: tessere PDF, export Libro Soci, rinnovi quota e navigazione admin.
Raw Blame History

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/git/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.

Versione Novità principali
1.6 Integrazione Mailchimp su consenso newsletter
1.5 Ricevuta pagamento (3° documento)
1.4 Sezione consensi in dettaglio admin
1.3 Fix elenco iscrizioni
1.2 Date form gg-mm-aaaa
1.1 Upload documenti identità/bonifico
1.0 Release iniziale

17. Contatti tecnici

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