Guia: como adicionar uma nova permissão
Última revisão: 19/09/2026.
- Escolher a chave canônica em inglês no formato
modulo.acaooumodulo.recurso.acao(ex.:establishments.export). - 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”. - Criar a linha em
permissoesvia migration/seed (chave,nome,modulo,acao,descricao). - Incluir no escopo de plataforma (
permissao_escopo_global). - Se for delegável ao tenant, incluir em
white_label_permissao(e na tela de escopo do WL). - Se a flag for só de plataforma, adicionar em
backend_permission_is_platform_only()(hoje: prefixowhite_label.*,admin.permissions,management.default_rates). - No endpoint e no service:
backend_permission_require()oubackend_permission_require_any(). Não confiar só nodata-permissionda UI. - Mutação: validar CSRF.
- Se o módulo puder ser desligado por tenant, respeitar
tenant_modules(padrão de leads/tasks). - Registrar a entrada em
docs/seguranca/permissoes-matriz-endpoints.md. - 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).