Modelo de permissões para níveis de cliente: planos, limites e flags

Por que times precisam de um modelo de permissões

Se você vende mais de um nível, tarde ou cedo vai receber o mesmo ticket de suporte: “O Cliente X pagou pelo Pro, mas não consegue acessar a Funcionalidade Y.” Sem um sistema claro, o suporte não consegue corrigir diretamente. Uma mudança simples de acesso vira tarefa de engenharia.

O problema maior é a inconsistência. Regras de acesso acabam espalhadas pelo produto: uma checkbox na tela administrativa, uma checagem hardcoded na API, uma anotação numa planilha e uma atualização pontual no banco de dados feita no último trimestre. Os clientes veem comportamentos diferentes em lugares distintos, e ninguém tem certeza de qual regra é a verdadeira.

Um modelo de permissões lhe dá uma fonte única de verdade sobre quem pode fazer o quê, com base no plano e em exceções aprovadas. Mantém os níveis previsíveis (para que o preço permaneça crível), ao mesmo tempo que deixa espaço para a vida real: um upgrade temporário, um aumento de cota ou um recurso piloto para uma conta específica.

“Alterar sem engenharia” deve ser concreto. Na prática:

• O suporte altera acesso em uma ferramenta administrativa editando dados, não solicitando deploy.
• O produto lê os mesmos dados de permissões em todos os lugares (backend, web app, mobile).
• Exceções podem ter prazo e serem reversíveis, não hacks permanentes.
• Mudanças são registradas com quem fez, quando e por quê.

Por exemplo, um cliente no nível Business atinge o limite de usuários ativos durante uma temporada cheia. O suporte deveria poder conceder +10 assentos por 14 dias, e o sistema deve reverter automaticamente quando o período terminar. A engenharia só entra quando você adiciona uma capacidade totalmente nova, não em ajustes rotineiros de acesso.

As peças básicas: clientes, planos e permissões

Um bom modelo de permissões começa com alguns objetos claros e propriedade definida. Se esses básicos estiverem confusos, o suporte acaba pedindo para a engenharia “só mais uma exceção” toda semana.

Aqui vai um conjunto simples de blocos de construção:

• Customer (account/tenant): a empresa ou pessoa que usa seu produto.
• Subscription: a relação comercial (trial, ativa, cancelada), muitas vezes ligada a um sistema de cobrança.
• Plan: o nível nomeado (Free, Pro, Enterprise) que define o acesso padrão.
• Entitlement: o comportamento efetivo permitido, derivado do plano mais quaisquer overrides.

A avaliação de permissões não é faturamento. Faturamento responde “o que devemos cobrar e quando?” Permissões respondem “o que este cliente pode fazer agora?” Um cliente pode estar inadimplente mas ainda em período de carência, ou totalmente pago mas temporariamente bloqueado por compliance. Mantenha essas decisões separadas para que o financeiro possa ajustar faturas sem alterar acidentalmente o acesso ao produto.

Vários grupos dependem dessa configuração:

• Produto define o que os planos significam.
• Suporte precisa de controles seguros para conceder ou remover acesso.
• Sales ops precisa de regras consistentes para acordos e renovações.
• Finance precisa de um mapeamento confiável entre o que foi vendido e qual acesso foi fornecido.

Defina limites cedo. Torne o conteúdo dos planos e os overrides de clientes configuráveis (para que o suporte possa agir), mas mantenha o comportamento central no código. Exemplos de “comportamento central” incluem como calcular cota restante, como lidar com trials expirados e quais ações precisam ser auditadas.

Flags, limites e quotas: escolha o tipo certo

A maioria dos problemas de nivelamento fica mais fácil quando você nomeia a permissão corretamente. Há três tipos comuns, e cada um responde a uma pergunta diferente:

• Boolean flags: algo está ligado ou desligado? Exemplo: export_enabled = true.
• Limites numéricos: quanto é permitido de uma vez? Exemplo: max_seats = 10.
• Quotas: quanto pode ser usado ao longo do tempo? Exemplo: api_calls_per_month = 100000.

Flags são melhores para funcionalidades que não devem funcionar parcialmente. Se export está desligado, esconda o botão e bloqueie o endpoint também. Limites funcionam bem para configurações de “capacidade” que não resetam, como assentos, projetos ou visualizações salvas.

Quotas exigem cuidado extra porque o tempo importa. Tickets de suporte caem rápido quando a regra de reset está documentada e visível na UI administrativa.

Escopo é a outra decisão que previne confusão. Uma flag como “SAML SSO enabled” costuma ser em nível de conta. “Max projects” pode ser em nível de workspace. “Can run reports” pode ser em nível de usuário se você vender add-ons baseados em função.

Para quotas, escolha uma regra de reset por quota e mantenha-a:

• Nunca (créditos vitalícios)
• Mensal (mês calendário)
• Janela móvel (últimos 30 dias)
• Por período de faturamento (coincide com o ciclo da fatura)

Se a regra de reset muda por plano, trate a própria regra como parte da permissão, não como conhecimento tribal.

Um esquema de banco de dados prático para permissões

Um modelo de permissões amigável ao suporte geralmente funciona melhor quando se mantém simples: poucas tabelas, chaves claras e registros com limite de tempo que você pode auditar. O objetivo é permitir que administradores mudem acesso editando dados, não entregando código.

Comece com quatro tabelas centrais: plans, plan_entitlements, customers e customer_overrides.

• Plans descrevem tiers (Free, Pro, Enterprise).
• Plan entitlements descrevem o que cada plano inclui.
• Customers apontam para um plano.
• Overrides cobrem exceções para um único cliente sem mudar o plano de todos.

Uma forma relacional compacta que funciona bem:

• 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

Os campos de permissão devem ser consistentes entre tabelas. Use uma key estável como seats, api_calls ou sso_enabled. Use type para manter a avaliação simples (por exemplo: flag, limit, quota). Armazene unit explicitamente (como users, requests, GB). Para quotas, mantenha reset_policy sem ambiguidade (como monthly, daily, never).

Overrides devem se comportar como allowlist com datas. Se um cliente tem uma override ativa para sso_enabled=true, ela deve vencer sobre o valor do plano, mas apenas dentro de effective_from e effective_to. Isso é o que torna “conceder 10 assentos extras por 14 dias” uma mudança de uma única linha que expira automaticamente.

Como a avaliação de permissões deve funcionar

A avaliação de permissões é o pequeno pedaço de código (ou serviço) que responde a uma pergunta: “Este cliente está autorizado a fazer isso agora?” Se essa parte for previsível, todo o resto fica mais fácil de operar.

Use uma ordem de precedência clara e não desvie: customer override > plan value > system default. Isso permite que o suporte conceda exceções temporárias sem mudar o plano, e dá à engenharia padrões seguros quando nada está configurado.

Um fluxo de avaliação prático:

• Identifique o cliente/conta a partir da sessão autenticada (não a partir do corpo da requisição).
• Carregue o plano ativo do cliente e quaisquer overrides ativas.
• Para uma determinada chave, retorne a override se presente; caso contrário retorne o valor do plano; caso contrário retorne o padrão do sistema.
• Se a chave estiver ausente em todos os lugares, falhe fechado para checagens de acesso (trate como “não permitido”) e use um padrão sensato para UI somente para exibição.
• Se a chave for desconhecida (não está no seu catálogo), trate como erro de configuração, falhe fechado e registre para acompanhamento.

Cache importa porque permissões são verificadas constantemente. Cacheie as permissões resolvidas por cliente com um TTL curto e um número de versão explícito. Invalide quando qualquer uma destas mudar: atribuição de plano, definição do plano, overrides do cliente ou status do cliente (trial, grace, blocked). Um padrão simples é “cache por customer_id + entitlements_version”, onde edições do suporte incrementam a versão para que mudanças apareçam rapidamente.

Segurança multi-tenant é inegociável. Toda consulta deve filtrar pelo id do cliente/conta atual, e toda entrada de cache deve ser chaveada por esse id. Não procure permissões por email, domínio ou nome do plano sozinho.

Passo a passo: um fluxo amigável ao suporte para ajustar acesso

Um fluxo amigável ao suporte mantém o modelo flexível sem transformar cada caso extremo em tarefa de engenharia. O objetivo é fazer mudanças com segurança, deixar rastro e confirmar a experiência do cliente.

Um fluxo seguro para suporte

Comece encontrando o registro do cliente correto e confirmando o que estão pedindo, e por quê. “Precisamos de dois assentos a mais por uma semana” é diferente de “assinamos um aditivo para um nível superior.” Uma boa UI administrativa facilita ver, em um lugar, o plano atual, status do cliente e quaisquer overrides ativas.

Antes de mudar qualquer coisa, verifique o uso real contra o limite ou quota atual. Muitos pedidos desaparecem assim que você vê que a conta não está no limite, ou que o problema está em outro lugar (por exemplo, rastreamento de uso não sendo atualizado).

Quando for preciso ajustar acesso, prefira uma override explícita em vez de editar o plano. Mantenha as overrides estreitas (uma flag ou um limite), inclua um responsável e um motivo, e padronize uma data de expiração. Exceções temporárias são comuns e fáceis de esquecer.

Uma checklist simples dentro da sua ferramenta administrativa costuma ser suficiente:

• Confirme identidade do cliente, plano atual e motivo da solicitação.
• Revise uso atual vs o limite relevante.
• Aplique uma override escopada e defina uma expiração.
• Adicione notas e referência ao ticket ou caso.
• Verifique o resultado na UI do produto usando personificação ou conta de teste.

Sempre verifique a mudança do jeito que o cliente vai vivenciar. Se você suporta impersonation, deixe óbvio quando ela está ativada e registre esse uso.

Upgrades, downgrades, trials e períodos de carência

A maioria dos problemas de permissões aparece durante mudanças: um cliente faz upgrade no meio do ciclo, um cartão falha ou um trial termina em um fim de semana. Se as regras são vagas, o suporte acaba chutando e a engenharia é acionada.

Para upgrades, mantenha simples: o acesso geralmente muda imediatamente, enquanto os detalhes financeiros ficam no billing. Seu modelo de permissões deve escutar um evento de cobrança como “plan changed” e aplicar as entitlements do novo plano na hora. Se o billing fizer proration, ótimo, mas não entoupe a lógica de permissões com matemática de proration.

Downgrades são onde surgem surpresas. Escolha um comportamento claro e deixe-o visível para suporte:

• Grace period: mantenha o acesso superior até o fim do termo pago.
• Somente leitura: permitir visualização/exportação, mas bloquear novas escritas.
• Parada imediata: bloquear a funcionalidade imediatamente (reservado para recursos de risco).
• Comportamento over-limit: permitir uso, mas bloquear criação quando o cliente estiver acima da cota.
• Retenção de dados: manter os dados, mas desabilitar acesso até upgrade.

Trials funcionam melhor como um plano próprio, não um booleano no cliente. Dê ao plano trial flags e limites explícitos, mais uma regra de expiração automática. Quando o trial terminar, mova o cliente para um plano padrão (frequentemente “Free”) e aplique o comportamento de downgrade que você definiu.

Períodos de carência também são úteis para falhas de pagamento. Uma janela curta de “past due” (por exemplo, 3 a 7 dias) dá tempo para resolver pagamentos sem perder acesso no meio do expediente. Trate a carência como uma override com prazo, não como um nome de plano customizado.

Uma dica prática: não amarre permissões aos nomes de marketing como “Pro” ou “Enterprise.” Mantenha IDs de plano estáveis internamente (como plan_basic_v2) para poder renomear níveis sem quebrar regras.

Auditabilidade e controles de segurança

Se o suporte pode alterar acesso sem engenharia, você precisa de trilha. Um bom modelo trata toda mudança como decisão registrada, não um ajuste silencioso.

Para cada override, capture o ator, o motivo de negócio e timestamps. Se a organização exigir, adicione uma etapa de aprovação para mudanças sensíveis.

O que registrar para cada mudança

Mantenha o log simples para que seja usado de fato:

• created_by e created_at
• approved_by e approved_at (opcional)
• reason (texto curto como “paid add-on” ou “incident credit”)
• previous_value e new_value
• expires_at

Controles de segurança evitam acidentes antes de chegarem à produção. Ponha guardrails na UI administrativa e no banco de dados: limite valores máximos, bloqueie números negativos e exija data de expiração quando a mudança for grande (por exemplo, elevar as chamadas de API em 10x).

Reversão e prontidão para auditoria

O suporte vai cometer erros. Dê a eles uma ação única “reverter para padrões do plano” que limpe overrides a nível de cliente e retorne a conta ao plano atribuído.

Para auditorias, facilite a exportação do histórico por cliente e intervalo de datas. Um CSV básico que inclua motivo e aprovador resolve a maioria das questões sem puxar a engenharia.

Exemplo: um cliente no “Pro” precisa de 30 assentos extras para um evento de uma semana. O suporte define seats_override=60 com expires_at na próxima sexta, adiciona o motivo “evento” e obtém aprovação do gerente. Após a expiração, o sistema volta automaticamente para 30, e o histórico completo está disponível caso a cobrança questione depois.

Erros comuns que tornam permissões penosas

A forma mais rápida de quebrar um modelo de permissões é deixá-lo crescer por acidente. Alguns atalhos iniciais podem virar meses de tickets de suporte e fogo cruzado de “por que este cliente pode fazer isso?”.

Um problema comum é espalhar checagens de recurso por toda a aplicação. Se partes diferentes do app decidirem acesso de formas distintas, você entregará contradições. Centralize a avaliação de permissões atrás de uma função ou serviço e faça com que toda UI e API o utilizem.

Outra armadilha é misturar estado de cobrança com acesso. “Pago” não é o mesmo que “permitido”. Faturamento tem tentativas, chargebacks, trials e faturas que se resolvem depois. Mantenha eventos de billing separados e traduza-os em permissões com regras claras (incluindo períodos de carência) para que casos extremos não bloqueiem usuários ou permitam acesso indefinidamente.

Evite depender de uma única string de tier como “basic” ou “pro” como fonte de verdade. Tiers mudam com o tempo e exceções acontecem. Armazene flags e limites explícitos para que o suporte possa conceder uma capacidade sem, acidentalmente, conceder tudo o que vem com o nome de um tier.

Overrides manuais são necessários, mas overrides ilimitadas sem guardrails tornam-se dívida invisível. Exija um responsável, um motivo e referência ao ticket. Incentive datas de expiração ou revisão. Mantenha overrides estreitas (uma chave por vez) e fáceis de auditar.

Quotas também dão errado quando regras de reset são vagas. Defina o que “por mês” significa (mês calendário vs últimos 30 dias), o que acontece em upgrade e se quota não utilizada acumula. Enforce essas regras na lógica do backend, não apenas na UI, para que mudanças do suporte não criem comportamentos inconsistentes entre web e mobile.

Checklist rápido antes de lançar

Antes de liberar um modelo de permissões, faça uma última checagem com quem vai usá-lo todo dia: suporte, success e quem está de plantão.

Garanta que cada feature mapeie para uma chave de permissão estável com um dono claro. Evite duplicatas como reports_enabled vs reporting_enabled. Assegure que cada plano tenha padrões explícitos para as chaves que você lançar. Se uma chave estiver faltando, falhe seguro (normalmente negar acesso) e alerte internamente para correção.

Para operações, confirme que o fluxo é realmente utilizável:

• Suporte pode ver o acesso efetivo (padrão do plano + override) sem SQL.
• Overrides são registradas com quem mudou o quê, por quê e quando expira.
• Quotas têm uma regra de reset visível e uma forma clara de mostrar uso atual.

Um teste de realidade: peça ao suporte para conceder um add-on de 14 dias a um cliente e depois removê-lo. Se eles conseguirem fazer isso com confiança em menos de dois minutos, você está perto.

Cenário exemplo: níveis com exceção temporária

Imagine que você oferece três níveis, e cada nível define algumas permissões claras que aparecem no produto e são aplicadas no backend.

• Free: 1 projeto, 3 usuários, 200 exports/mês, limite básico de API, logs de auditoria por 7 dias.
• Team: 10 projetos, 25 usuários, 2.000 exports/mês, limite de API maior, logs de auditoria por 30 dias.
• Business: projetos ilimitados, 200 usuários, 10.000 exports/mês, maior limite de API, logs de auditoria por 180 dias, SSO habilitado.

Agora um cliente Team diz: “Temos um esforço de fim de trimestre e precisamos de 8.000 exports este mês. Podem ajudar por 30 dias?” Isso é exatamente onde uma override temporária é melhor do que movê-los para outro plano.

O suporte abre o registro do cliente, adiciona uma override como export_monthly_limit = 8000 e define expires_at para 30 dias a partir de hoje. Eles adicionam a nota: “Aprovado por Alex (Sales), exceção de 30 dias para relatórios de Q4.”

Do lado do cliente, duas coisas devem acontecer:

• A UI reflete o novo limite (por exemplo, o medidor de uso e o rótulo “Exports restantes” atualizam).
• Exports continuam funcionando até atingirem 8.000 no mês.

Se ultrapassarem, veem uma mensagem clara como: “Limite de export reached (8.000/mês). Contate suporte ou faça upgrade para aumentar seu limite.”

Após a data de expiração, a override deixa de se aplicar automaticamente e o cliente volta ao limite do plano Team sem que ninguém precise lembrar de desligar nada.

Próximos passos: implementar e iterar sem desacelerar o suporte

Comece transformando “features” em um pequeno catálogo de permissões. Dê a cada item uma chave clara, um tipo (flag vs limite vs quota) e um valor padrão por plano. Esse catálogo vira a linguagem compartilhada entre produto, suporte e engenharia, então mantenha nomes específicos e estáveis.

Decida onde a aplicação será forçada. Uma regra segura é: aplique no API para tudo que muda dados ou custa dinheiro, use jobs em background para parar trabalhos longos quando limites forem excedidos, e trate a UI como orientação (botões desabilitados, mensagens úteis) mas não o único bloqueio.

Mantenha a primeira versão enxuta. Foque nas permissões que geram mais dúvidas, adicione checagens nas ações de maior risco e lance uma visão administrativa que mostre cliente, plano, overrides e histórico em um só lugar.

Se quiser construir o painel administrativo e a lógica subjacente rapidamente sem codificar tudo à mão, AppMaster (appmaster.io) é uma opção prática para esse tipo de trabalho: você pode modelar planos e overrides como dados, implementar checagens como processos de negócio e entregar uma UI de suporte consistente entre backend e apps.