Capacidades e limites num SaaS PHP sem condicionais por plano

Quando a lógica de um SaaS começa com condições como if ($tenant->plan === 'pro'), parece uma solução direta. O problema surge na segunda alteração do catálogo: um plano é renomeado, uma capacidade é vendida em separado, um cliente mantém condições antigas ou o suporte precisa de ativar algo temporariamente. Então, o nome comercial deixa de descrever uma regra estável e acaba distribuído entre controladores, tarefas agendadas, consultas, API e interface.

A gestão de capacidades em SaaS PHP deve traduzir a oferta comercial em decisões de domínio verificáveis. O código não deve perguntar se uma empresa é “Pro”, mas sim se pode realizar uma ação concreta, com que limite, em que condições e até quando. Esta separação permite alterar preços ou pacotes sem reescrever regras operacionais.

Separar plano, capacidade, limite, permissão e configuração

Estes conceitos relacionam-se, mas não são intermutáveis. Um plano é um pacote comercial. Uma capacidade ativa uma funcionalidade do produto, como exportar dados, criar automações ou usar uma integração. Um limite define uma quantidade ou ritmo permitido, por exemplo, projetos ativos, utilizadores faturáveis ou pedidos à API por período.

Uma permissão responde a outra pergunta: que identidade pode realizar uma ação dentro de uma empresa. O facto de uma organização ter a capacidade de exportar dados não significa que qualquer utilizador possa exportá-los. Por fim, a configuração do cliente são opções válidas para uma empresa concreta, como o fornecedor de identidade escolhido, uma política de retenção ou um modelo de notificações. Não convém usar configuração livre para ocultar decisões comerciais ou de autorização.

• Plano: composição comercial de direitos e limites.
• Capacidade: regra funcional expressa em termos do produto.
• Limite: limiar quantificável associado a uma capacidade ou recurso.
• Permissão: autorização de um ator para executar uma ação.
• Configuração: parâmetro de comportamento disponível dentro das regras já concedidas.

Uma decisão pode exigir todas as camadas. Para criar uma automação, a empresa precisa da capacidade correspondente, deve estar abaixo do limite de automações ativas e o utilizador deve ter permissão de administração. Depois, o fluxo pode validar a configuração de destino.

Modelar regras de domínio, não nomes de planos

Mantenha um catálogo estável de capacidades com identificadores técnicos independentes do marketing: automation.create, data.export ou api.webhooks. O catálogo pode incluir o tipo de valor esperado: booleano, inteiro, conjunto de opções ou política estruturada. O identificador expressa uma necessidade do produto; não deve incorporar o nome de um plano nem de uma campanha.

A atribuição comercial pode ser resolvida numa camada separada. Um plano em vigor fornece um conjunto de concessões, mas também podem existir complementos, migrações herdadas e exceções explícitas. O resultado para cada empresa é uma resolução de direitos efetiva com proveniência.

capacidade: automation.create
valor efetivo: true
proveniência: complemento de automações
vigência: até ao cancelamento

Esta proveniência é essencial. Se uma capacidade estiver ativa, produto, suporte e faturação precisam de saber se provém do plano atual, de uma cláusula herdada ou de uma exceção com data de expiração. Evite guardar apenas um campo plan na empresa e deduzir todo o restante em cada ponto de utilização.

Um único serviço de decisão

Em PHP, exponha um serviço de domínio, por exemplo EntitlementResolver ou CapabilityGate, que receba a empresa, a capacidade e o contexto necessário. Deve devolver uma decisão explicável, e não apenas um booleano: permitido ou rejeitado, valor resolvido, motivo, regra de origem e data de avaliação. Esta data representa o instante em que o resolvedor determinou a decisão e permite interpretar corretamente vigências, expirações e alterações posteriores de plano. Os controladores, comandos, listeners e workers assíncronos consultam esse serviço; não reconstroem as suas próprias consultas de subscrição.

Definir limites mensuráveis antes de os programar

Um limite ambíguo gera conflitos e erros de implementação. “Até 100 utilizadores” exige responder ao que conta como utilizador: convidado pendente, suspenso, membro eliminado durante o ciclo, conta de serviço? “Mil exportações” requer definir o período, o fuso horário, as tentativas e se uma exportação falhada consome quota.

Para cada limite, documente pelo menos:

• O recurso, evento ou consumo que é contabilizado.
• O âmbito: empresa, projeto, utilizador ou integração.
• A janela: total em vigor, dia de calendário, mês de faturação ou janela móvel.
• O momento de controlo: antes de criar, ao ativar, ao enviar ou após consolidar.
• A reação: bloquear, permitir com aviso, colocar em fila, degradar ou exigir aprovação.
• O tratamento de concorrência, tentativas, cancelamentos e reversão.

Os limites de objetos ativos costumam ser validados com uma operação transacional ou uma reserva que evite ultrapassar o limiar sob concorrência. Os limites de consumo precisam de um contador com semântica clara e idempotência através de uma chave de evento. Não confie apenas num contador mostrado na interface: dois pedidos simultâneos podem passar numa verificação prévia e ultrapassar o máximo.

Distinga também entre aviso e bloqueio. Um alerta aos 80% melhora a previsibilidade, mas não substitui uma proteção real no ponto em que o recurso é criado ou executado.

Aplicar as regras em todos os caminhos de execução

Ocultar um botão é uma melhoria de experiência, não um controlo de acesso. A validação deve existir no caso de uso do servidor que executa a ação. Assim, abrange a interface web, a API pública, as integrações e as chamadas internas.

Os processos assíncronos requerem uma decisão adicional: verificar ao colocar em fila e voltar a verificar ao executar quando o trabalho possa demorar. Se uma empresa perder uma capacidade entre ambos os momentos, a política deve definir se o trabalho é cancelado, concluído por ter sido aceite antes ou se requer revisão. A escolha depende do tipo de operação, mas deve ser consistente e registada.

As ferramentas de suporte e administração não devem contornar as regras silenciosamente. Podem operar com uma autorização administrativa distinta, mas têm de deixar rastreabilidade e indicar se geram uma concessão formal, uma correção de dados ou uma ação excecional.

Gerir alterações, direitos herdados e exceções sem bifurcar o produto

Uma alteração de plano não consiste apenas em atualizar uma etiqueta. Pode reduzir um limite abaixo da utilização atual ou retirar uma capacidade que sustenta processos ativos. Defina políticas por tipo de recurso: impedir novas criações e conservar o existente, desativar excedentes de forma explícita, conceder um período de transição ou solicitar uma escolha ao administrador da empresa.

As exceções temporárias devem ser concessões de primeira classe com âmbito, valor, motivo, emissor e expiração. Um campo manual como is_vip é difícil de interpretar e costuma sobreviver à causa original. Para clientes herdados, modele uma atribuição de migração com regras precisas e data de revisão, em vez de criar ramos permanentes de código.

Uma exceção sustentável é um dado auditável que o mesmo resolvedor interpreta; uma exceção perigosa é um condicional especial adicionado a um fluxo concreto.

Combinar capacidades, funções e isolamento multiempresa

Numa plataforma multiempresa, toda a consulta de direitos, consumo e configuração deve ser delimitada pela empresa correta. Não derive o contexto apenas de valores enviados pelo cliente. Resolva-o a partir da autenticação, do domínio solicitado ou do contexto interno validado, e propague-o para trabalhos em fila e eventos.

A decisão final costuma ser uma interseção: a empresa dispõe da capacidade, o limite não se esgotou e o ator tem a permissão necessária. Centralizar capacidades não substitui um modelo de funções; evita que funções e planos se misturem. Uma função pode conceder quem administra automações, enquanto a capacidade determina se a empresa pode usar automações.

Dados, auditoria e testes que permitem explicar decisões

Conserve atribuições de direitos com vigência e precedência, juntamente com eventos de consumo quando um agregado não for suficiente. Registe decisões relevantes: empresa, ator ou processo, capacidade, valor avaliado, resultado, origem e correlação do pedido. Não guarde dados pessoais desnecessários nestes registos e estabeleça retenção de acordo com as suas obrigações.

A auditoria deve responder por que motivo uma ação foi rejeitada sem obrigar à leitura de código histórico. É especialmente útil perante alterações comerciais, incidentes de faturação e operações de suporte.

Os testes devem incluir uma matriz de capacidades e valores, limites no limiar exato, concorrência, alterações de plano, expiração de exceções e tentativas de eventos. Execute os mesmos casos através de HTTP, API e workers em fila quando partilharem o caso de uso. Adicione testes de isolamento para confirmar que uma empresa não pode consultar nem consumir direitos de outra.

Plano gradual para centralizar uma plataforma PHP existente

1. Inventarie nomes de planos, condições, contadores e exceções manuais no código e nas operações.
2. Escolha uma capacidade ou limite de elevado impacto e defina a sua semântica completa antes de o migrar.
3. Introduza o resolvedor como fachada, inicialmente compatível com as fontes atuais.
4. Mova os pontos de aplicação para o caso de uso central, não apenas para a interface.
5. Registe decisões e compare o novo comportamento com o anterior antes de remover ramos antigos.
6. Migre plano a plano para atribuições explícitas e elimine referências comerciais do domínio.

Lista de verificação antes de publicar uma alteração

• A capacidade tem um identificador estável e uma definição de negócio inequívoca?
• O limite especifica unidade, âmbito, período, concorrência e reação ao excesso?
• A regra é aplicada no servidor, na API e em processos assíncronos?
• As funções, capacidades e o contexto da empresa são validados em separado?
• As alterações de plano e as exceções têm vigência, proveniência e auditoria?
• Existem testes para o limiar do limite, a revogação e o isolamento multiempresa?

Com este modelo, o catálogo comercial pode evoluir sem transformar cada modificação numa procura de condicionais. A plataforma mantém regras compreensíveis, mensuráveis e defensáveis tanto para produto como para engenharia.