Architettura - Nonprofit Membership Workflow

I componenti

Ventitré moduli

Il codice è suddiviso in moduli con responsabilità chiare: la configurazione è separata dalla logica e i dati sensibili vivono in un unico file. Non servono tutti: quelli marcati come opzionali si possono non installare, e il sistema degrada in modo pulito senza di loro.

Fondamenta

Configurazione, segreti e strumenti trasversali: ciò su cui poggia tutto il resto.

0_Secrets.gs

Contenitore unico dei valori sensibili. Nei sorgenti pubblici è tutto segnaposto; nel pacchetto configurato contiene le tue chiavi. Da non condividere mai.

Core

1_CONFIG_V8.gs

Configurazione globale: identità dell'ente, mappa delle colonne del foglio, design system delle email, cause di cessazione, installazione dei trigger.

Core

11_Tracer.gs

Diario di bordo su uno spreadsheet dedicato, con mascheramento automatico di chiavi e segreti prima di ogni scrittura.

Opzionale

12_footer

Footer di attribuzione aggiunto automaticamente alle email dirette fuori dall'ente. Le email interne al dominio non vengono marcate.

Core

13_TestFeedback.gs

Prova dell'email di benvenuto con dati fittizi, per controllare la resa grafica senza toccare pratiche reali.

Opzionale

Ciclo di vita dell'associato

Dalla domanda in arrivo all'account creato, fino alla tessera e alle comunicazioni.

2_TriggerAmmissione.gs

Il cuore del workflow: ammissione, rifiuto, lavori differiti, onboarding completo e funzioni di recupero.

Core

7_RouterModuli.gs

Prende in carico le nuove domande, riconosce i doppi invii, manda la prima email e verifica il legame fra volontario e genitore.

Core

4_WorkspaceAdmin.gs

Creazione e sospensione degli account Google Workspace e Microsoft 365, con gestione dei gruppi di dominio.

Opzionale

5_TesseraGenerator.gs

Tessera personale in PDF generata da un template Google Slides, con QR verso la scheda contatto.

Opzionale

6_Mail.gs

Tutti i template delle email transazionali: circa venticinque messaggi, dalla conferma di ricezione alla delibera di espulsione.

Core

10_GmailFirma.gs

Imposta la firma Gmail istituzionale tramite delega a livello di dominio, e offre una pagina per copiarla a mano.

Opzionale

8_NotificheChat.gs

Notifiche su Google Chat con finestra oraria, coda differita e collegamento diretto alla pratica.

Opzionale

9_MembroPortal.gs

Portale di consultazione per i membri. È un progetto Apps Script separato, con un proprio deployment.

Opzionale

Denaro

Quote, rinnovi e il ponte verso la contabilità dell'ente.

3_StripeAdmin.gs

Ciclo di vita degli abbonamenti: ricezione degli eventi di pagamento, rinnovi, controllo delle morosità, annullamenti e rimborsi.

Opzionale

14_IntegrazioneFinanza.gs

Genera la ricevuta in PDF della quota e scrive una riga nel registro dei movimenti del sistema contabile, con un riferimento che evita i doppioni.

Opzionale

Interfacce

Le pagine che vedono le persone: chi si iscrive, chi paga, chi decide, chi firma.

15_ModuloIscrizioneWebApp.gs

Il router unico di tutte le web app, e la Fase 1: raccolta della domanda, allegati su Drive, assegnazione dell'ID Pratica.

Core

16_ModuloPagamentoWebApp.gs

La Fase 2: identificazione con ID Pratica e codice fiscale, poi avvio del pagamento della quota.

Opzionale

17_PresidenzaAdmin.gs

Il pannello della Presidenza: ammissione, rifiuto, ratifica, proposta ed esecuzione dell'espulsione, cessazione, note e cronologia.

Core

18_PresidenzaAdminAPI.gs

Le stesse azioni del pannello esposte in JSON per l'app mobile, autenticando ogni singola chiamata.

Opzionale

22_LiberatoriaWebApp.gs

Liberatoria firmata per foto, video, audio ed esecuzione musicale: pagina con token, doppia firma dei genitori, PDF e catena delle firme.

Opzionale

Registri e ponti

Gli obblighi di legge e i collegamenti verso l'esterno.

20_LibriSociali.gs

Estrae il libro degli associati e il registro dei volontari dal foglio delle domande, con numerazione stabile e conservazione dei cessati.

Core

21_RegistroEventi.gs

Registro degli eventi in sola aggiunta: conserva la storia dei calendari con una catena di impronte SHA-256, verifica, ancora esterna ed estratto in PDF.

Opzionale

19_SupabaseSync.gs

Ponte verso l'app mobile. Per progetto non può mai far fallire un'ammissione o un pagamento: se non è configurato, viene saltato.

Opzionale

Il nucleo minimo. Con i moduli 0, 1, 2, 6, 7, 12, 15, 17 e 20, più le pagine del modulo di iscrizione e del pannello, si ha già un sistema completo: domanda online, delibera della Presidenza, libro degli associati ed email. Sono nove moduli, e non richiedono né Google Workspace né un servizio di pagamento.

Requisiti reali

Funziona anche se non hai…

Le pagine di questo tipo danno spesso per scontato che un'associazione abbia Google Workspace, Microsoft 365 e un conto per i pagamenti online. La maggior parte delle APS non ha nessuno dei tre. Il sistema è costruito per spegnere i pezzi che mancano, non per rifiutarsi di partire.

Se l'ente non ha…	Si spengono	Che cosa succede
Google Workspace	account istituzionali, firma Gmail	Nessuna casella `@tuodominio` da assegnare. Il socio resta socio: l'email di benvenuto arriva al suo indirizzo personale.
Microsoft 365	provisioning delle utenze Office	Già oggi non è bloccante: l'errore viene annotato sulla pratica e l'onboarding prosegue.
un servizio di pagamento	quota online, ricevuta, modulo di pagamento	La quota si incassa fuori dal sistema e la Presidenza la segna come regolare dal pannello. Il flusso resta a due fasi.
tessere associative	generazione del PDF	L'email di benvenuto parte senza allegato: il codice lo prevede già.
Google Chat	notifiche allo staff	Nessuna notifica push; il pannello resta la fonte di verità.
un'app mobile	API JSON e sincronizzazione	Nessun effetto: la sincronizzazione si salta da sé se non è configurata.
immagini da pubblicare	liberatorie	Nessuna liberatoria da raccogliere né da conservare.
calendari da storicizzare	registro degli eventi	Nessun registro da mantenere.

Le interfacce

Un URL, sei pagine

Un progetto Apps Script può avere una sola funzione di ingresso per le richieste in lettura e una sola per quelle in scrittura. Tutte le pagine del sistema vivono quindi sullo stesso indirizzo e si distinguono per parametro: è il motivo per cui esiste un router unico.

Indirizzo	Pagina
`/exec`	Modulo di iscrizione (Fase 1) — è il link da pubblicare
`/exec?pagina=paga`	Modulo di pagamento della quota (Fase 2)
`/exec?pagina=presidenza`	Pannello della Presidenza
`/exec?pagina=presidenza&formato=json`	Le stesse azioni in JSON, per l'app mobile
`/exec?pagina=liberatoria`	Pagina della liberatoria immagini, raggiunta con un token personale
`/exec?nome=…&cognome=…`	Pagina «copia la tua firma Gmail»
`POST /exec`	Ingresso degli eventi di pagamento, in arrivo dal Worker

Due eccezioni. Il portale dei membri è un progetto Apps Script separato, con un proprio indirizzo. E l'ingresso degli eventi di pagamento non riceve direttamente da Stripe, ma dal Worker che fa da tramite: il perché è spiegato nella guida all'installazione.

Le quattro pagine HTML

File	Cosa contiene	Ruolo
`ModuloIscrizioneHTML`	Il modulo di iscrizione: multilingua, firma sul touch, allegati compressi nel browser.	Core
`ModuloPagamentoHTML`	Il modulo di pagamento della quota (Fase 2).	Opzionale
`PresidenzaAdminHTML`	L'interfaccia del pannello della Presidenza.	Core
`LiberatoriaHTML`	La pagina della liberatoria, con la doppia firma dei genitori.	Opzionale

Automazioni

Trigger ed eventi

Sette trigger installati una volta sola, più tre che il sistema crea e distrugge da sé quando deve aspettare.

Funzione	Tipo	Quando scatta
`RouterModuli`	onChange · nuova riga	All'arrivo di una nuova domanda
`TriggerAmmissione`	onEdit · stato della domanda	Quando la Presidenza imposta Ammesso o Rifiutato dal foglio
`TriggerCancellazioneAbbonamento`	onEdit · stato del pagamento	Quando l'abbonamento viene segnato come cancellato
`TriggerStorico`	onEdit · colonne sorvegliate	Ad ogni modifica di una delle colonne gestionali
`controlloScadenzeGiornaliero`	Giornaliero · 08:00	Controllo delle quote scadute oltre i trenta giorni
`processaCodaNotifiche`	Giornaliero · 09:00	Invio delle notifiche accodate durante la notte
`sincronizzaRegistroEventi`	Giornaliero	Storicizzazione dei calendari nel registro degli eventi

Una trappola della piattaforma. I trigger legati alle modifiche scattano solo per ciò che una persona digita nell'interfaccia del foglio, mai per le scritture fatte da uno script. È per questo che il pannello della Presidenza, dopo aver scritto le celle, richiama direttamente la logica di onboarding invece di aspettare un trigger che non arriverebbe mai.

Il database

Dove vivono i dati

Otto fogli in tutto, di cui tre su spreadsheet separati. La separazione non è ordine formale: tenere i log e i registri fuori dal foglio operativo evita che ogni scrittura faccia scattare i trigger.

Foglio	Dove	A cosa serve
`Risposte`	foglio principale	Tutte le domande ricevute e il loro stato. È l'archivio delle domande, non il libro dei soci.
`Storico`	foglio principale	Ogni modifica alle colonne gestionali, con valore vecchio e nuovo. Alimenta la cronologia del pannello.
`Note Presidenza`	foglio principale	Annotazioni interne per pratica, tenute a parte per non disturbare le colonne sorvegliate.
`Libro degli Associati`	foglio principale	Il libro dei soci vero e proprio: solo chi è diventato membro, compresi i cessati, in ordine di ammissione e con numero d'iscrizione.
`Registro Volontari`	foglio principale	Il registro dei volontari non occasionali, con gli estremi della copertura assicurativa.
`Diario di bordo`	spreadsheet separato	Il log in tempo reale del workflow. Separato di proposito: scrivere log nel foglio operativo farebbe scattare i trigger.
`Registro Movimenti`	spreadsheet contabile	Una riga per ogni quota incassata, con riferimento al PDF della ricevuta.
`Registro Eventi`	spreadsheet separato	La storia dei calendari in sola aggiunta, con la catena di impronte e le ancore di verifica.

La pratica

Le colonne del foglio

Ogni domanda è una riga che cresce nel tempo: alle colonne compilate dal richiedente si aggiungono quelle gestionali, create dallo script e sorvegliate dai trigger. Si arriva a circa settanta colonne, fino alla BV.

Blocco	Contenuto
Apertura	Data di invio, tipo di associato, anagrafica del richiedente
Anagrafica del minore	Per le pratiche di tipo Volontario, i dati del musicista minorenne
Pratica	ID Pratica, email istituzionale assegnata, stato della domanda, data di ammissione, gruppo
Pagamento	Stato della quota, riferimenti della transazione e dell'abbonamento, scadenza
Esiti	Membro ufficiale, esiti della creazione degli account, tracciamento delle email inviate
Liberatoria	Consenso per ciascun canale, versione del testo firmato, data dell'ultimo aggiornamento
Ciclo di vita	Proposta di espulsione, delibera dell'Assemblea, cessazione e relativa causa

Attenzione a una particolarità. Per una pratica di tipo Volontario, le colonne dell'anagrafica «socio» contengono i dati del genitore firmatario che ha compilato il modulo, mentre l'anagrafica del minore sta in un blocco successivo. Il pannello della Presidenza mostra le due cose separate; chi legge il foglio a mano deve saperlo. La mappa completa è definita in 1_CONFIG_V8.gs.

Affidabilità

Perché niente viene fatto due volte

Un sistema che crea account e muove denaro non può permettersi di ripetersi. Due meccanismi lo impediscono: le attese volute e i segni scritti prima di agire.

Le attese, e il motivo di ciascuna

Attesa	Perché
5 minuti dopo l'ammissione dal foglio	Dà il tempo di compilare data, gruppo e stato del pagamento prima che l'onboarding legga la riga. Dal pannello, che li raccoglie in un solo passaggio, non c'è nessuna attesa.
5 minuti dopo il rifiuto	Dà il tempo di scrivere il motivo, che è obbligatorio: senza, il rifiuto non parte e arriva un avviso.
15 minuti dopo l'onboarding	L'account appena creato deve propagarsi prima che la firma Gmail e il QR della tessera funzionino davvero.

I lavori in attesa sono salvati fra le proprietà del progetto e ricontrollati quando maturano: se nel frattempo lo stato è cambiato, il lavoro viene semplicemente annullato. Ogni esecuzione smaltisce tutti i lavori pendenti, non solo l'ultimo, e i trigger rimasti orfani si autoeliminano.

I segni scritti prima di agire

Un socio già diventato membro non può essere sottoposto a un secondo onboarding.
I doppi invii del modulo vengono riconosciuti e marcati come duplicati.
Il segno del rimborso viene scritto prima di chiamare il servizio di pagamento, non dopo.
Gli eventi di pagamento sono registrati per identificativo e ignorati se già visti: il servizio li ripete per giorni, il registro locale si ripulisce da sé.
Ogni email inviata lascia traccia sulla propria colonna, così non parte due volte.

Servizi collegati

Integrazioni esterne

Il workflow orchestra diversi servizi Google e di terze parti tramite le loro API. Solo i primi quattro sono indispensabili; gli altri si attivano se servono.

Google Sheets

Database operativo, storico e libri sociali.

Gmail

Invio delle email transazionali dal dominio dell'ente.

Workspace Admin SDK

Utenze, gruppi di dominio e autorizzazione del pannello.

Slides e Drive

Tessere, ricevute, liberatorie e archivio degli allegati.

Stripe

Quote, abbonamenti, rinnovi e rimborsi.

Cloudflare Workers

Il tramite obbligatorio fra Stripe e Apps Script.

Microsoft 365

Utenze Office e licenze, non bloccanti.

Google Chat

Notifiche interne allo staff su due canali distinti.

Google Calendar

Link alle riunioni e storicizzazione degli eventi.

Supabase

Ponte dati verso l'app mobile. Mai bloccante.

Google People

Risoluzione del contatto per il QR della tessera.

Pronto a installarlo?

Segui la guida passo-passo per configurare il workflow sul dominio della tua associazione, oppure leggi come tratta i dati delle persone.

Guida all'installazione Conformità e dati