Pular para o conteúdo principal

RBAC multi-tenant por White Label

Última revisão contra o código: 19/09/2026.

Este documento descreve o modelo que está no ar. O desenho antigo com a tabela white_label_permission_scope não foi criado — o runtime usa white_label_permissao + permissao_escopo_global.


Regra central​

Um usuário de White Label só exerce uma permissão se:

  1. a flag estiver em permissao_usuario, e
  2. a mesma flag estiver autorizada em white_label_permissao daquele WL.

Usuário de plataforma (users.white_label_id nulo/0) usa o catálogo permissao_escopo_global.

Super-admin tem bypass total em backend_permission_user_can().

Flags platform-only (white_label.*, admin.permissions, management.default_rates) nunca passam para usuário tenant.


Tabelas reais​

TabelaPapel
permissoesCatálogo (chave canônica EN)
permissao_usuarioGrants do usuário
white_label_permissaoEscopo delegável do WL (white_label_id, permissao_id)
permissao_escopo_globalEscopo da equipe de plataforma
tenant_modulesLiga/desliga módulo (leads, tasks) por tenant — não é grant de flag
usersrole, white_label_id
setores / user_setoresFiltro de menu (antes do RBAC de item)

Código: backend/src/services/core/permission_service.php e permission_canonical.php. Política B documentada em permission_scope_policy_b.php.

Constante BACKEND_PERMISSION_ALLOW_FALLBACK_WITHOUT_SCOPE_TABLES default false (fail-closed se as tabelas de escopo sumirem).


Papéis​

Canônicos em authorization_service.php:

RoleRankUso
super-admin100Bypass de flag; visão global
admin80Governança do escopo
gestor50Gestão de time/carteira
colaborador20Operação no próprio vínculo

Legado normalizado para colaborador: marketplace, representante, rep, ec, operador, visualizador, etc.

Atribuição: super-admin atribui qualquer nível de cadastro; admin pode atribuir admin; demais só níveis inferiores.


Flags canônicas​

Formato: modulo.acao ou modulo.recurso.acao, em inglês.

Exemplos: users.edit, establishments.change_representative, leads.stage.change, tasks.read.

Aliases PT (usuarios.editar, estabelecimentos.trocar_representante) ainda resolvem para a canônica. Código novo deve pedir a chave EN. Catálogo de UI deve mostrar só a canônica.

Fonte da verdade: backend_permission_families() em permission_canonical.php.


Runtime (can)​

backend_permission_user_can($conn, $userId, $permissionKey):

  1. recusa userId inválido ou chave vazia;
  2. libera se super-admin;
  3. recusa flag platform-only para tenant;
  4. expande aliases;
  5. exige linha em permissao_usuario + condição de escopo (white_label_permissao ou permissao_escopo_global);
  6. tenta implicação (backend_permission_is_implied_by_holders) se o COUNT for 0.

backend_permission_require() / require_any() existem e devolvem 403, mas os endpoints quase não as chamam — a checagem está nos services (_assert_can, backend_leads_assert_can, backend_tasks_*, temPermissao()).

Adaptador legado: backend/includes/permissoes.php → temPermissao().


Fluxos na UI​

Escopo do WL​

Tela frontend/pages/white-label/escopo-permissoes.php + API backend/api/permissoes/*. Admin de plataforma define o que o WL pode distribuir. Hard enforcement: se a flag sai do escopo, can() falha mesmo com grant residual.

Permissões de usuário​

Tela frontend/pages/permissoes/usuarios.php. Admin WL só enxerga/atribui flags do próprio escopo (Policy B).

components/menu-lateral.php: setor → flags de sessão → tenant_modules (comercial/tarefas). data-permission é só UX.


O que o desenho antigo propunha e não entrou​

  • Tabela white_label_permission_scope — não existe.
  • permission_templates por tipo_precificacao — não existe.
  • Colunas scope_level / delegavel_para_wl no catálogo — a governança equivalente veio pelo par white_label_permissao + permissao_escopo_global + backend_permission_is_platform_only().
  • Serviço em config/permissoes/authorization_service.php — o runtime está em backend/src/services/core/.

Não recriar essas tabelas sem migrar os grants atuais.


Checklist (estado)​

  • Admin WL não vê flag de plataforma.
  • API de atribuição valida escopo (Policy B).
  • Remoção do escopo WL corta o acesso na hora (can).
  • Super-admin com governança total.
  • Tentativa negada vai para log (permission_denied).
  • CSRF e backend_permission_require em todos os endpoints mutáveis.
  • Testes automatizados role × flag × escopo.