# 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]
```

5. **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)

```mermaid
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

```bash
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.

---

## 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)