RBAC detalhado

→ Conceito de RBAC — leia primeiro.

Onde gerenciar

Roles

Settings → Acesso → Papéis e Permissões

Usuários e atribuições

Settings → Acesso → Usuários

Membros de projeto

Dentro de cada empreendimento → Equipe (Empreendimento → Configurações → Membros)

Criar role customizado

1. Settings → Acesso → Papéis → Novo papel
2. Nome (ex: "Comprador Sênior"), slug (ex: comprador-senior)
3. Hierarchy level — escolha número entre 0-7 (menor = mais poderoso)
4. Selecione permissões em checkboxes agrupados por módulo

Hierarquia de ações

Lembrar:

• manage ⊃ write ⊃ read
• Marcar manage automaticamente concede write e read

Atribuir role a usuário

Role global (org-wide)

Settings → Acesso → Usuários → [usuário] → Editar:

• "RBAC Role" — escolhe role principal
• Vale para toda a organização

Role por projeto

Em cada projeto:

• Empreendimento → Configurações → Membros → Adicionar membro
• Role ali define o que ele pode no contexto daquele projeto

Hierarquia (escopo)

• Role global vale em todo lugar
• Role de projeto sobrescreve para aquele projeto
• Quem tem hierarchy_level ≤ 1 (proprietário/diretor) tem acesso a TODOS os projetos automaticamente
• Os demais precisam estar explicitamente em project_members

Casos de uso comuns

Comprador da matriz

• Role: comprador-senior (custom)
• Permissões: compras:read, compras_cotacao:write|manage, compras_pedido:write, fornecedores:write
• Escopo: global (acesso a todas as obras da org)

Engenheiro só de uma obra

• Role: engenheiro (padrão)
• Vinculado a project_members apenas no Bloco A da Obra X
• Não enxerga outros projetos

Diretor que precisa enxergar tudo (sem alterar)

• Role: visualizador (padrão)
• Mas com hierarchy_level alto não terá poder. Para diretor de fato:
• Role: diretor (padrão) — hierarchy 1, vê tudo

Auditor externo (ex: contador, banco)

• Crie role custom auditor-externo
• Apenas permissões :read em todos os módulos
• Escopo: global

Almoxarife terceirizado

• Role custom almoxarife
• Permissões: compras_recebimento:write, compras_estoque:write
• Escopo: project (só nas obras dele)

Verificações no código

Para devs/integradores:

Frontend:

import { usePermissions } from "@/hooks/use-permissions";
const { hasGlobal, hasProject } = usePermissions();
if (hasGlobal("compras:read")) { /* ... */ }

Backend (API routes):

const auth = await getAuthenticatedContext();
if (auth.ok) {
  auth.ctx.requireGlobalPermission("compras_cotacao:write");
  // ou:
  if (!auth.ctx.hasProjectPermission(projectId, "compras_recebimento:read")) { /* 403 */ }
}

Auditoria de mudanças

Toda mudança em role_permissions ou organization_members gera evento. Settings → Acesso → Histórico (se habilitado).