Modello di entitlements per livelli clienti: piani, limiti, flag

Perché i team hanno bisogno di un modello di entitlements

Se vendi più di un livello, prima o poi riceverai lo stesso ticket di supporto: “Il cliente X ha pagato per Pro, ma non può accedere alla Funzionalità Y.” Senza un sistema chiaro, il supporto non può risolverlo direttamente. Una semplice modifica di accesso diventa un task per l'ingegneria.

Il problema più grande è l'incoerenza. Le regole di accesso finiscono disperse nel prodotto: una casella da spuntare in una schermata admin, un controllo hardcoded nell'API, una nota in un foglio di calcolo e un aggiornamento one-off al database dell'ultimo trimestre. I clienti vedono comportamenti diversi in posti diversi e nessuno è sicuro di quale regola sia quella vera.

Un modello di entitlements ti dà una singola fonte di verità su chi può fare cosa, basata sul loro piano e su eventuali eccezioni approvate. Mantiene i livelli prevedibili (così i prezzi restano credibili), lasciando però spazio alla realtà: un upgrade temporaneo, un aumento di quota o una funzionalità pilota per un solo account.

“Modificare senza ingegneria” dovrebbe essere concreto. In pratica:

• Il supporto cambia l'accesso in uno strumento admin modificando i dati, non chiedendo un deploy.
• Il prodotto legge gli stessi dati di entitlements ovunque (backend, web app, mobile).
• Le eccezioni possono essere limitate nel tempo e reversibili, non scelte permanenti.
• Le modifiche sono registrate con chi le ha fatte, quando e perché.

Per esempio, un cliente sul livello Business raggiunge il limite di utenti attivi durante una stagione intensa. Il supporto dovrebbe poter concedere +10 posti per 14 giorni e il sistema dovrebbe ripristinare automaticamente lo stato quando il periodo termina. L'ingegneria dovrebbe intervenire solo quando si aggiunge una nuova funzionalità, non per gli aggiustamenti di routine.

Gli elementi di base: clienti, piani ed entitlements

Un buon modello di entitlements parte da pochi oggetti chiari e una proprietà ben definita. Se queste basi sono sfocate, il supporto finirà per chiedere all'ingegneria “solo un'altra eccezione” ogni settimana.

Ecco un set semplice di mattoni:

• Customer (account/tenant): l'azienda o la persona che usa il tuo prodotto.
• Subscription: la relazione commerciale (trial, attiva, annullata), spesso collegata a un sistema di fatturazione.
• Plan: il livello nominativo (Free, Pro, Enterprise) che definisce l'accesso di default.
• Entitlement: il comportamento effettivamente consentito, derivato dal piano più eventuali override.

La valutazione degli entitlements non è fatturazione. La fatturazione risponde a “cosa dobbiamo addebitare e quando?” Gli entitlements rispondono a “cosa può fare questo cliente adesso?” Un cliente potrebbe non aver pagato ma essere ancora in un periodo di tolleranza, o essere pagato ma temporaneamente bloccato per conformità. Tieni separate queste decisioni così la finanza può correggere fatture senza cambiare accidentalmente l'accesso al prodotto.

Diverse aree contano su questo setup:

• Product definisce cosa significano i piani.
• Support ha bisogno di controlli sicuri per concedere o rimuovere accesso.
• Sales ops ha bisogno di regole coerenti per offerte e rinnovi.
• Finance ha bisogno di una mappatura affidabile tra ciò che è stato venduto e l'accesso fornito.

Stabilisci confini presto. Rendi il contenuto dei piani e gli override cliente configurabili (così il supporto può agire), ma mantieni il comportamento core nel codice. Esempi di “comportamento core” includono come calcoli la quota rimanente, come gestisci i trial scaduti e quali azioni devono essere sottoposte ad audit.

Flag, limiti e quote: scegli il tipo giusto

La maggior parte dei problemi di tiering si risolve meglio quando dai il nome corretto all'entitlement. Ci sono tre tipi comuni, e ognuno risponde a una domanda diversa:

• Boolean flags: qualcosa è attivo o no? Esempio: export_enabled = true.
• Limiti numerici: quanto è permesso contemporaneamente? Esempio: max_seats = 10.
• Quote: quanto può essere usato nel tempo? Esempio: api_calls_per_month = 100000.

I flag sono ideali per funzionalità che non devono funzionare parzialmente. Se l'export è disattivato, nascondi il pulsante e blocca anche l'endpoint. I limiti sono migliori per impostazioni di “capacità” che non si azzerano, come posti, progetti o viste salvate.

Le quote richiedono attenzione in più perché il tempo conta. I ticket di supporto calano rapidamente quando la regola di reset è documentata e visibile nell'UI admin.

Lo scope è l'altra decisione che evita confusione. Un flag come “SAML SSO enabled” è di solito a livello di account. “Max projects” potrebbe essere a livello di workspace. “Può eseguire report” potrebbe essere a livello di utente se vendi add-on basati sul ruolo.

Per le quote, scegli una sola regola di reset per quota e mantienila coerente:

• Mai (crediti a vita)
• Mensile (mese calendario)
• Finestra rolling (ultimi 30 giorni)
• Per periodo di fatturazione (corrisponde al ciclo di fatturazione)

Se la regola di reset cambia a seconda del piano, tratta la regola stessa come parte dell'entitlement, non come conoscenza tribale.

Uno schema di database pratico per gli entitlements

Un modello di entitlements amichevole per il supporto di solito funziona meglio se resta noioso: poche tabelle, chiavi chiare e record limitati nel tempo che si possano auditare. L'obiettivo è permettere agli admin di cambiare accesso modificando dati, non distribuendo codice.

Inizia con quattro tabelle core: plans, plan_entitlements, customers e customer_overrides.

• Plans descrivono i tier (Free, Pro, Enterprise).
• Plan entitlements descrivono cosa include ogni piano.
• Customers puntano a un piano.
• Overrides coprono eccezioni per un singolo cliente senza cambiare il piano per tutti.

Una forma relazionale compatta che funziona bene:

• plans: id, name, description, is_active
• plan_entitlements: id, plan_id, key, type, value, unit, reset_policy, effective_from, effective_to, created_by
• customers: id, name, plan_id, status, created_at
• customer_overrides: id, customer_id, key, type, value, unit, reset_policy, effective_from, effective_to, created_by

I campi degli entitlements dovrebbero essere coerenti tra le tabelle. Usa una key stabile come seats, api_calls o sso_enabled. Usa type per mantenere semplice la valutazione (per esempio: flag, limit, quota). Conserva unit esplicitamente (come users, requests, GB). Per le quote, mantieni reset_policy senza ambiguità (come monthly, daily, never).

Gli override dovrebbero comportarsi come una allowlist con date. Se un cliente ha un override attivo per sso_enabled=true, questo dovrebbe prevalere sul valore del piano, ma solo entro effective_from e effective_to. Questo è ciò che rende “concedere 10 posti extra per 14 giorni” una modifica in una sola riga che scade automaticamente.

Come dovrebbe funzionare la valutazione degli entitlements

La valutazione degli entitlements è il piccolo pezzo di codice (o servizio) che risponde a una domanda: “Questo cliente può farlo in questo momento?” Se questa parte è prevedibile, tutto il resto rimane più facile da gestire.

Usa un ordine di precedenza chiaro e non deviare: override cliente > valore del piano > default di sistema. Questo permette al supporto di concedere eccezioni temporanee senza cambiare il piano e dà all'ingegneria default sicuri quando nulla è configurato.

Un flusso di valutazione pratico:

• Identifica il cliente/account dalla sessione autenticata (non dal body della request).
• Carica il piano attivo del cliente e eventuali override attivi.
• Per una data key, restituisci l'override se presente; altrimenti restituisci il valore del piano; altrimenti restituisci il default di sistema.
• Se la key manca ovunque, nega l'accesso per i controlli di enforcement (trattala come “non consentita”) e usa un default sensato per l'UI di sola visualizzazione.
• Se la key è sconosciuta (non è nel tuo registro), trattala come un errore di configurazione, nega l'accesso e registrala per approfondimenti.

La cache conta perché gli entitlements vengono controllati costantemente. Cachea gli entitlements risolti per cliente con un TTL breve e un numero di versione esplicito. Invalidali quando cambia qualcosa: assegnazione del piano, definizione del piano, override cliente o stato del cliente (trial, grace, blocked). Un pattern semplice è “cache per customer_id + entitlements_version”, dove le modifiche del supporto incrementano la versione così i cambi mostrano rapidamente.

La sicurezza multi-tenant non è negoziabile. Ogni query deve filtrare per l'id del cliente/account corrente e ogni entry della cache deve essere indicizzata da quell'id. Non cercare entitlements per email, dominio o solo per nome del piano.

Step by step: un flusso amichevole per il supporto per regolare l'accesso

Un flusso pensato per il supporto mantiene il modello flessibile senza trasformare ogni caso limite in un task per l'ingegneria. L'obiettivo è fare cambiamenti in sicurezza, lasciare una traccia e confermare l'esperienza del cliente.

Un flusso sicuro per il supporto

Inizia trovando il record cliente giusto e confermando cosa richiedono e perché. “Servono due posti in più per una settimana” è diverso da “abbiamo firmato un emendamento per un livello superiore.” Una buona UI admin rende facile vedere in un unico posto il piano corrente, lo stato del cliente e eventuali override attivi.

Prima di cambiare qualsiasi cosa, controlla l'uso reale rispetto al limite o alla quota corrente. Molte richieste spariscono quando vedi che l'account non è al cap, o che il problema è altrove (per esempio, il tracciamento dell'uso non si aggiorna).

Quando è necessario modificare l'accesso, preferisci un override esplicito invece di modificare il piano. Mantieni gli override ristretti (un flag o un limite), includi un owner e una motivazione e preimposta una data di scadenza. Le eccezioni temporanee sono comuni e facili da dimenticare.

Una checklist semplice dentro lo strumento admin è di solito sufficiente:

• Conferma l'identità del cliente, il piano corrente e la motivazione della richiesta.
• Controlla l'uso corrente rispetto al cap rilevante.
• Applica un override mirato e imposta una scadenza.
• Aggiungi note e un riferimento ticket o case.
• Verifica il risultato nell'UI del prodotto usando l'impersonazione o un account di test.

Verifica sempre la modifica nel modo in cui il cliente la vivrà. Se supporti l'impersonazione, rendi ovvio quando è abilitata e registrala.

Upgrade, downgrade, trial e periodi di grazia

La maggior parte dei problemi con gli entitlements emerge durante i cambiamenti: un cliente effettua un upgrade a metà ciclo, una carta fallisce o un trial scade in un weekend. Se le regole sono vaghe, il supporto finisce per indovinare e l'ingegneria viene coinvolta.

Per gli upgrade, mantienilo semplice: l'accesso dovrebbe cambiare di solito immediatamente, mentre i dettagli monetari restano in fatturazione. Il tuo modello di entitlements dovrebbe ascoltare un evento di fatturazione come “plan changed” e applicare subito i nuovi entitlements del piano. Se la fatturazione fa proration, ottimo, ma non inserire la logica della proration negli entitlements.

I downgrade sono dove succedono le sorprese. Scegli un comportamento di downgrade chiaro e rendilo visibile al support:

• Periodo di grazia: mantieni l'accesso superiore fino alla fine del termine pagato.
• Sola lettura: permetti di visualizzare/esportare dati ma blocca nuove scritture.
• Stop immediato: blocca subito la funzionalità (da usare per feature rischiose).
• Comportamento over-limit: permetti l'uso, ma blocca la creazione quando il cliente è sopra la quota.
• Conservazione dati: conserva i dati ma disabilita l'accesso fino all'upgrade.

I trial funzionano meglio come un piano a sé, non come un booleano sul cliente. Dai al piano trial flag e limiti espliciti, più una regola di scadenza automatica. Quando il trial finisce, sposta il cliente su un piano di default (spesso “Free”) e applica il comportamento di downgrade che hai definito.

I periodi di grazia sono utili anche per i fallimenti di pagamento. Una finestra breve “past due” (per esempio, 3–7 giorni) dà tempo ai team di risolvere il pagamento senza perdere accesso a metà giornata. Tratta il periodo di grazia come un override limitato nel tempo, non come un nome di piano personalizzato.

Un consiglio pratico: non legare gli entitlements ai nomi di marketing come “Pro” o “Enterprise.” Mantieni ID piano interni stabili (come plan_basic_v2) così puoi rinominare i tier senza rompere le regole.

Auditabilità e controlli di sicurezza

Se il support può cambiare l'accesso senza l'ingegneria, hai bisogno di una traccia. Un buon modello di entitlements tratta ogni modifica come una decisione registrata, non come una modifica silenziosa.

Per ogni override cattura l'attore, la motivazione di business e i timestamp. Se l'organizzazione lo richiede, aggiungi un passaggio di approvazione per le modifiche sensibili.

Cosa registrare per ogni modifica

Mantieni il log semplice così viene effettivamente usato:

• created_by e created_at
• approved_by e approved_at (opzionale)
• reason (testo breve come “paid add-on” o “incident credit”)
• previous_value e new_value
• expires_at

I controlli di sicurezza prevengono errori prima che raggiungano la produzione. Metti dei guardrail nell'UI admin e nel database: limita i valori massimi, blocca numeri negativi e richiedi una data di scadenza quando un cambiamento è grande (per esempio, aumentare le chiamate API di 10x).

Rollback e prontezza per l'audit

Il support farà errori. Fornisci un'azione singola “revert to plan defaults” che cancelli gli override a livello cliente e riporti l'account al piano assegnato.

Per gli audit, rendi facile esportare la cronologia per cliente e per intervallo di date. Un export CSV di base che includa motivazione e approvatore risponde alla maggior parte delle domande senza coinvolgere l'ingegneria.

Esempio: un cliente su “Pro” ha bisogno di 30 posti extra per una settimana. Il support imposta seats_override=60 con expires_at il prossimo venerdì, aggiunge la motivazione “evento” e ottiene l'approvazione del manager. Dopo la scadenza, il sistema torna automaticamente a 30, e la traccia completa è disponibile se la fatturazione la contesta in seguito.

Errori comuni che rendono gli entitlements dolorosi

Il modo più veloce per rompere un modello di entitlements è lasciarlo crescere accidentalmente. Alcune scorciatoie iniziali possono trasformarsi in mesi di ticket di supporto e di firefighting su “perché questo cliente può fare ciò?”.

Un problema comune è disperdere i controlli delle funzionalità ovunque. Se parti diverse dell'app decidono l'accesso in modi differenti, finirai per lanciare contraddizioni. Centralizza la valutazione degli entitlements dietro una funzione o un servizio e fai in modo che ogni UI e chiamata API lo usi.

Un'altra trappola frequente è mescolare lo stato di fatturazione con l'accesso. “Pagato” non è lo stesso di “consentito”. La fatturazione ha ritentativi, chargeback, trial e fatture che si risolvono dopo. Tieni la fatturazione separata e traduci gli eventi di fatturazione in entitlements con regole chiare (inclusi periodi di grazia) così i casi limite non bloccano gli utenti o non li lasciano dentro per sempre.

Evita di affidarti a una singola stringa “tier” come unica fonte di verità. I tier cambiano nel tempo e le eccezioni accadono. Conserva flag e limiti espliciti così il supporto può concedere una capacità senza dare tutto ciò che è incluso in un'etichetta di livello.

Gli override manuali sono necessari, ma override illimitati senza guardrail diventano debito invisibile. Richiedi un owner, una motivazione e un riferimento ticket. Incoraggia date di scadenza o di revisione. Mantieni gli override ristretti (una key alla volta) e rendili facili da auditare.

Le quote falliscono anche quando le regole di reset sono vaghe. Definisci cosa significa “al mese” (mese calendario vs rolling 30 giorni), cosa succede in caso di upgrade e se la quota non utilizzata si accumula. Applica queste regole nella logica backend, non solo nell'UI, così le modifiche del supporto non creano comportamenti incoerenti tra web e mobile.

Checklist rapida prima del rilascio

Prima di rilasciare un modello di entitlements, fai un ultimo passaggio con le persone che lo useranno ogni giorno: support, success e chi è on-call.

Assicurati che ogni funzionalità sia mappata a una chiave di entitlements stabile con un owner chiaro. Evita duplicati come reports_enabled vs reporting_enabled. Assicurati che ogni piano abbia default espliciti per le chiavi che rilasci. Se una key manca, fail safe (di solito negando l'accesso) e avvisa internamente così viene sistemata.

Per le operations, conferma che il flusso sia davvero utilizzabile:

• Il support può vedere l'accesso effettivo (default di piano più override) senza SQL.
• Gli override sono registrati con chi ha cambiato cosa, perché e quando scade.
• Le quote hanno una regola di reset visibile e un modo chiaro per mostrare l'uso corrente.

Un test di realtà: chiedi al support di concedere un add-on di 14 giorni a un singolo cliente, poi rimuoverlo. Se può farlo con fiducia in meno di due minuti, sei vicino.

Scenario di esempio: livelli con un'eccezione temporanea

Immagina di offrire tre livelli e che ogni livello imposti alcuni entitlements chiari che compaiono nel prodotto e sono applicati nel backend.

• Free: 1 progetto, 3 utenti, 200 export/mese, limite API base, log di audit di 7 giorni.
• Team: 10 progetti, 25 utenti, 2.000 export/mese, limite API più alto, log di audit di 30 giorni.
• Business: progetti illimitati, 200 utenti, 10.000 export/mese, limite API più alto, log di audit di 180 giorni, SSO abilitato.

Ora un cliente Team dice: “Abbiamo un picco di fine trimestre e ci servono 8.000 export questo mese. Potete aiutarci per 30 giorni?” Qui una eccezione temporanea è esattamente quello che serve invece di spostarli su un nuovo piano.

Il support apre il record cliente, aggiunge un override come export_monthly_limit = 8000 e imposta expires_at a 30 giorni da oggi. Aggiungono una nota: “Approvato da Alex (Sales), eccezione di 30 giorni per report Q4.”

Dal lato cliente, due cose dovrebbero accadere:

• L'UI riflette il nuovo limite (per esempio, il misuratore d'uso e l'etichetta “Esportazioni rimanenti” si aggiornano).
• Le esportazioni continuano a funzionare fino a raggiungere 8.000 nel mese.

Se superano, vedranno un messaggio chiaro come: “Limite export raggiunto (8.000/mese). Contatta il supporto o esegui l'upgrade per aumentare il limite.”

Dopo la scadenza, l'override smette automaticamente di applicarsi e il cliente ritorna al limite del piano Team senza che nessuno debba ricordarsi di disattivarlo.

Prossimi passi: implementare e iterare senza rallentare il supporto

Inizia trasformando le “feature” in un piccolo catalogo di entitlements. Dai a ogni elemento una chiave chiara, un tipo (flag vs limit vs quota) e un valore di default per piano. Questo catalogo diventa il linguaggio condiviso tra product, support e engineering, quindi tieni i nomi specifici e stabili.

Decidi dove risiede l'enforcement. Una regola prudente è: fai enforcement nell'API per tutto ciò che modifica dati o comporta costi, usa job in background per fermare lavori di lunga durata quando i limiti sono superati, e tratta l'UI come guida (pulsanti disabilitati, messaggi utili) ma non come unica barriera.

Mantieni la prima versione contenuta. Concentrati sugli entitlements che generano più domande, aggiungi controlli per le azioni a rischio più alto e rilascia una vista admin che mostri cliente, piano, override e cronologia in un unico posto.

Se vuoi costruire il pannello admin e la logica sottostante velocemente senza scrivere tutto a mano, AppMaster (appmaster.io) è una soluzione pratica per questo tipo di lavoro: puoi modellare piani e override come dati, implementare i controlli come processi di business e rilasciare un'interfaccia di supporto che resta coerente tra backend e app.