Schema di gamification PostgreSQL: 5 tabelle, 12 livelli

Punti chiave da ricordare: Un solido sistema di gamification si basa su uno schema PostgreSQL dedicato con 5 tabelle, RPC atomiche transazionali e una progressione calibrata su 12 livelli. Il segreto: isolare la gamification nel proprio schema, limitare le serie a 365 giorni per evitare la dipendenza e rendere tutto atomico per garantire la coerenza dei dati.

La gamification sembra semplice in superficie. Punti, badge, una classifica — sembra facile, no? In realtà, non appena si inizia a modellare seriamente, la complessità esplode. Per TAMSIV, volevo un sistema completo: livelli, badge, serie, sfide quotidiane, cronologia dei punti e un feed di attività. Tutto in PostgreSQL, con garanzie transazionali.

Ecco come ho progettato lo schema di gamification di TAMSIV, tabella per tabella, decisione per decisione.

Perché uno schema PostgreSQL dedicato per la gamification?

TAMSIV utilizza già due schemi in Supabase: privat per i dati utente (attività, memo, eventi) e collaborative per le funzionalità di gruppo. Avrei potuto aggiungere le tabelle di gamification in privat. Ma non l'ho fatto.

Lo schema gamification è uno schema dedicato e isolato. Perché?

• Separazione delle responsabilità: la gamification ha le proprie politiche RLS (Row Level Security), le proprie funzioni RPC, i propri indici. Nessuna mescolanza con la logica di business.
• Evoluzione indipendente: posso modificare il sistema di punti o aggiungere badge senza rischiare di rompere la creazione di attività.
• Performance: le query di gamification (classifica, ranking, statistiche) non condividono gli indici con le tabelle di contenuto.
• Sicurezza: le politiche RLS di gamification sono più semplici — un utente vede solo le proprie statistiche. Nessun permesso di gruppo da gestire.

Questo approccio segue il principio di separazione degli schemi raccomandato da PostgreSQL. Ogni schema è un namespace che isola tabelle, funzioni e politiche di sicurezza.

Quali sono le 5 tabelle dello schema di gamification?

Lo schema completo si basa su 5 tabelle interconnesse:

1. user_stats — il pannello di controllo di ogni giocatore

Questa è la tabella centrale. Memorizza lo stato attuale di ogni utente:

• total_points: il punteggio cumulato dall'inizio
• current_level: il livello attuale (da 1 a 12+)
• current_streak: il numero di giorni consecutivi di attività
• max_streak: il record personale di serie
• last_activity_date: la data dell'ultima attività (per il calcolo della serie)
• streak_freeze_count: il numero di "blocchi" di serie disponibili

Perché memorizzare il livello invece di calcolarlo al volo? Perché la verifica del livello implica un confronto con le soglie, e questa verifica deve essere atomica con l'aggiunta di punti. Se il calcolo fosse fatto lato client, si rischierebbero incoerenze.

2. user_badges — la collezione di successi

Una relazione many-to-many tra utenti e badge. Ogni riga registra:

• L'ID del badge (tra i 10 badge disponibili)
• La data di ottenimento
• Il contesto di ottenimento (quale azione ha attivato il badge)

I badge in TAMSIV premiano comportamenti specifici: primo memo vocale, 10 attività completate, 7 giorni di serie, ecc. Non vengono mai rimossi — un badge ottenuto è per sempre.

3. points_history — il registro di ogni guadagno

Ogni guadagno di punti viene registrato individualmente. Questa tabella è essenziale per:

• L'analisi (quali azioni generano più punti?)
• Il debugging (un utente contesta il suo punteggio? Abbiamo la traccia)
• Le sfide quotidiane (verifica delle condizioni)
• Il feed di attività (visualizzazione cronologica dei guadagni)

4. daily_challenges — una sfida al giorno

Ogni giorno, ogni utente riceve una sfida personalizzata. La tabella memorizza:

• Il tipo di sfida (creare X attività, usare la voce, completare un memo, ecc.)
• L'obiettivo numerico (3 attività, 5 memo, ecc.)
• La progressione attuale
• Lo stato (in corso, completato, scaduto)

Le sfide sono generate da una funzione RPC che tiene conto del livello dell'utente — un principiante riceve sfide più semplici di un giocatore di livello 10.

5. feed_activity — il flusso sociale

Il feed di attività mostra le azioni recenti: badge ottenuti, livelli raggiunti, serie notevoli. È la dimensione sociale della gamification — vedere che altri utenti progrediscono motiva.

Come funzionano i 12 livelli di progressione?

Il sistema di livelli è il cuore della gamification. Le soglie di punti per ogni livello:

[0, 100, 250, 500, 1000, 2000, 3500, 5500, 8000, 12000, 17500, 25000]

Questa progressione segue una curva esponenziale attenuata. I primi livelli sono volutamente facili:

• Livelli 1-3 (da 0 a 250 punti): raggiungibili in 2-3 giorni di utilizzo normale. Questa è la fase di onboarding — l'utente scopre il sistema e riceve gratificazioni rapide.
• Livelli 4-7 (da 500 a 3500 punti): la fase di coinvolgimento. Da 1 a 4 settimane. L'utente ha integrato TAMSIV nella sua routine.
• Livelli 8-10 (da 5500 a 12000 punti): la fase di padronanza. Diversi mesi. Questi livelli sono un segnale di forte ritenzione.
• Livelli 11-12 (da 17500 a 25000 punti): i "conquistatori". Meno del 5% degli utenti li raggiunge.

Oltre il livello 12? Una formula matematica prende il sopravvento: soglia = 25000 + (livello - 12) * 10000. Questo evita di codificare centinaia di livelli consentendo una progressione infinita.

Questa calibrazione si ispira ai lavori di Yu-kai Chou sul framework Octalysis, che raccomanda ricompense immediate all'inizio del percorso e una difficoltà progressiva per mantenere l'impegno a lungo termine.

Perché le funzioni RPC devono essere atomiche?

Quando un utente completa un'attività in TAMSIV, ecco cosa deve succedere lato gamification:

1. Aggiungere i punti corrispondenti
2. Verificare se la soglia del livello successivo è stata raggiunta
3. Aggiornare la serie (giorno consecutivo di attività)
4. Verificare se sono stati sbloccati nuovi badge
5. Aggiornare la progressione della sfida quotidiana
6. Registrare la cronologia dei punti

Se il passaggio 3 fallisce dopo che il passaggio 1 è riuscito, i dati sono incoerenti. Ecco perché tutte queste operazioni sono incapsulate in funzioni PostgreSQL transazionali. O tutto riesce, o tutto fallisce.

La funzione principale record_task_completed orchestra tutto in un'unica transazione:

• add_gamification_points — aggiunge i punti e registra la cronologia
• check_and_update_streak — aggiorna la serie con gestione dei fusi orari
• check_and_unlock_badges — verifica le condizioni di ogni badge

Lato frontend, il GamificationService (singleton) chiama queste RPC e gestisce le notifiche locali per badge, livelli e traguardi di serie.

Come gestire le serie senza rendere gli utenti dipendenti?

Le serie sono il meccanismo di gamification più potente — e il più pericoloso. Una serie di 100 giorni crea un'enorme pressione per non "romperla". Ecco perché ho posto dei limiti:

• Limite a 365 giorni: oltre un anno, la serie si resetta. Una serie di 500 giorni non è più gamification — è dipendenza per design.
• Blocchi di serie: l'utente può "bloccare" la sua serie per un giorno (vacanze, malattia). Il numero di blocchi disponibili aumenta con il livello.
• Nessuna punizione: perdere una serie non rimuove punti o badge. Si limita a resettare il contatore.

La gestione dei fusi orari è un rompicapo tecnico. Un utente a Parigi e un utente a Tokyo non hanno lo stesso "giorno". La rilevazione della rottura della serie avviene confrontando last_activity_date con la data attuale nel fuso orario dell'utente, non in UTC.

Come il frontend consuma la gamification?

Il GamificationService è un singleton che centralizza tutte le interazioni frontend con lo schema di gamification:

• Chiamate RPC: ogni completamento di attività o creazione di memo attiva una chiamata a record_task_completed o record_memo_created.
• Notifiche locali: tramite NotificationService.notifyAchievement(), l'utente viene notificato di badge, level up e traguardi di serie.
• Cache ottimizzata: le statistiche utente sono memorizzate localmente per evitare una chiamata Supabase ad ogni visualizzazione del profilo.
• Feed in tempo reale: il feed di attività utilizza Supabase Realtime per visualizzare i successi degli altri utenti in diretta.

L'integrazione nel Dittafono è trasparente: quando l'IA crea un'attività tramite voce, l'hook useTaskDetail chiama automaticamente il GamificationService al completamento. L'utente non deve fare nulla — i punti arrivano naturalmente.

Quali metriche monitorare per regolare la gamification?

La tabella points_history consente di analizzare finemente:

• Distribuzione dei livelli: se l'80% degli utenti è bloccato al livello 3, le soglie sono troppo alte.
• Tasso di completamento delle sfide: al di sotto del 30%, le sfide sono troppo difficili. Al di sopra del 90%, troppo facili.
• Serie media: un indicatore diretto di ritenzione quotidiana.
• Badge più rari: i badge che nessuno ottiene devono essere rivalutati.

Tutto è visibile nella dashboard admin con grafici Recharts. Questo permette di regolare le soglie in produzione senza ridistribuire.

Come evitare le trappole classiche della gamification?

La gamification mal concepita fa più male che bene. Ecco le trappole che ho evitato:

• Nessuna classifica pubblica: le classifiche pubbliche demoralizzano il 95% degli utenti per motivare il 5% dei migliori. TAMSIV mostra la progressione personale, non la competizione.
• Nessuna gamification punitiva: perdere punti per inattività è un dark pattern. In TAMSIV, l'inattività non ha alcuna conseguenza negativa.
• Punti significativi: ogni punto corrisponde a un'azione reale (attività creata, memo registrato, serie mantenuta). Nessun punto gratuito per "accedere".
• Feedback immediato: le notifiche di badge e level up arrivano istantaneamente, non a fine giornata.

Come applicare questo schema al tuo progetto?

Se vuoi implementare un sistema di gamification simile, ecco i principi:

1. Isola lo schema: non mescolare gamification e logica di business. Uno schema dedicato facilita le migrazioni e il debugging.
2. Tutto atomico: ogni azione utente che impatta la gamification deve essere una transazione unica.
3. Calibra la progressione: testa le soglie di livello con dati reali. I primi livelli devono essere raggiungibili in giorni, non in settimane.
4. Prevedi la manutenzione: la tabella points_history cresce rapidamente. Prevedi una politica di conservazione o archiviazione.
5. Misura tutto: senza analytics, non saprai se la tua gamification motiva o frustra i tuoi utenti.

FAQ

Quanto tempo ci vuole per implementare un sistema di gamification completo?

Per TAMSIV, lo schema e le RPC hanno richiesto circa 4 giorni. L'integrazione frontend (GamificationService, notifiche, UI) ha aggiunto altri 3 giorni. La parte più lunga è la calibrazione delle soglie di livello, che richiede dati di utilizzo reali.

PostgreSQL è adatto per la gamification o è necessario Redis?

PostgreSQL è più che sufficiente per un'app delle dimensioni di TAMSIV. Le funzioni transazionali garantiscono la coerenza e gli indici su user_stats rendono le query veloci. Redis sarebbe utile solo per una classifica in tempo reale con milioni di utenti — il che non è il caso qui.

Come evitare che la gamification diventi un dark pattern?

Tre regole: nessuna punizione per l'inattività, nessuna pressione sociale tramite classifica pubblica e un limite alle serie. La gamification deve premiare l'azione, non punire l'assenza. Il blocco della serie è un meccanismo di sicurezza essenziale.

I punti devono essere gli stessi per tutte le azioni?

No. In TAMSIV, completare un'attività vale più che creare un memo, e usare la voce dà un bonus. La scala riflette il valore di ogni azione per l'utente. Una scala piatta (tutto vale 10 punti) non crea alcuna gerarchia di comportamento.

È necessario visualizzare i punti in tempo reale o in differita?

In tempo reale, sempre. Il feedback immediato è la base di una gamification efficace. In TAMSIV, i punti vengono visualizzati istantaneamente dopo ogni azione, con un'animazione e un suono opzionale. Il ritardo uccide la dopamina.