Pular para o conteúdo principal

Guia: como adicionar uma nova permissão

Última revisão: 19/09/2026.

  1. Escolher a chave canônica em inglês no formato modulo.acao ou modulo.recurso.acao (ex.: establishments.export).
  2. Registrar a família em backend/src/services/core/permission_canonical.php (backend_permission_families + label). Se precisar de alias PT legado, coloque na mesma família — não crie duas flags “oficiais”.
  3. Criar a linha em permissoes via migration/seed (chave, nome, modulo, acao, descricao).
  4. Incluir no escopo de plataforma (permissao_escopo_global).
  5. Se for delegável ao tenant, incluir em white_label_permissao (e na tela de escopo do WL).
  6. Se a flag for só de plataforma, adicionar em backend_permission_is_platform_only() (hoje: prefixo white_label.*, admin.permissions, management.default_rates).
  7. No endpoint e no service: backend_permission_require() ou backend_permission_require_any(). Não confiar só no data-permission da UI.
  8. Mutação: validar CSRF.
  9. Se o módulo puder ser desligado por tenant, respeitar tenant_modules (padrão de leads/tasks).
  10. Registrar a entrada em docs/seguranca/permissoes-matriz-endpoints.md.
  11. Testar:
    • sem login;
    • sem flag;
    • com flag e escopo do WL;
    • com flag mas fora do escopo do WL;
    • super-admin;
    • usuário de outro white label;
    • admin de plataforma (se a flag for platform-only).