Catálogo de permissões: onde o desenho vira registro de verdade

Levei um bom tempo achando que salvar um perfil era só gravar uma lista de menus marcados. Aí apareceu um caso em que o perfil mostrava tudo certo na tela e o acesso continuava barrado, e eu não tinha explicação nenhuma para dar. Quem me explicou foi o desenvolvedor, em duas frases: o catálogo de permissões é uma coisa, o registro que o runtime consulta é outra, e existe uma conversão entre os dois. A partir dali passei a entender os chamados em vez de adivinhar.

Este texto é para quem administra o ambiente e quer parar de tratar essa camada como caixa preta. Não é obrigatório saber isso para configurar um perfil. Mas quando algo sai do esperado, é aqui que a resposta mora.

Duas estruturas, uma conversa

De um lado existe o catálogo, que é espelhado dos menus ativos e organiza o que pode ser concedido em sistema, grupo e menu. Do outro existe a estrutura legada de controle de acesso, que trabalha por controller e função e é o que a aplicação consulta quando alguém abre uma rota. O que liga os dois é a materialização: ao salvar o perfil, o desenho é convertido para a estrutura compatível com esse modelo antigo.

Essa escolha de arquitetura tem uma consequência prática que eu acho ótima: o runtime das telas existentes continua funcionando sem reescrita. Dá para migrar um grupo piloto para o modelo novo e deixar o resto da equipe no comportamento anterior, sem parar ninguém e sem fazer big bang.

• O catálogo reflete os menus ativos, então não existe item que não corresponda a algo navegável.
• Menu desativado sai do catálogo e deixa de aparecer para concessão.
• Menu novo entra disponível, nunca concedido por padrão.
• Rotas compartilhadas entre módulos carregam escopo explícito.
• O salvamento materializa o resultado na estrutura compatível com o controle de acesso legado.

Por que o catálogo de permissões precisa ser espelhado

A alternativa seria manter uma lista paralela de itens permissionáveis, escrita à mão. Já trabalhei em lugar assim e o resultado é sempre o mesmo: a lista atrasa em relação ao produto, aparecem itens que não existem mais e faltam telas novas. Espelhar os menus ativos elimina esse descompasso por construção. O que você vê na árvore é o que existe, e nada mais que isso.

O efeito colateral bom é a auditoria ficar honesta. Quando alguém pergunta o que aquele perfil concede, a resposta é uma leitura da árvore, não uma arqueologia. Se você ainda não configurou nenhum perfil, o caminho de entrada está em como configurar a árvore tri-state.

Escopo de rota: o detalhe que me custou uma tarde

Uma mesma tela pode servir a mais de um módulo. Sem escopo, conceder essa tela em um sistema poderia significar conceder em todos, e a separação entre sistemas perderia o sentido. Por isso o catálogo declara explicitamente a qual contexto aquela concessão pertence.

O erro que eu cometi foi ignorar essa informação por achar que era detalhe interno. Concedi a ocorrência do contexto errado, a tela continuou invisível para o usuário e eu passei horas conferindo perfil, empresa e conta. Hoje, quando o sintoma é "está marcado e não aparece", o escopo é a primeira coisa que eu olho.

Como eu investigo quando o acesso não bate

1. Confirme empresa e sistema do perfilMetade dos casos morre aqui. O perfil pertence aos dois, e o usuário pode estar em outro contexto.
2. Leia o escopo do itemSe a tela é compartilhada entre módulos, confira se o escopo concedido bate com o sistema do perfil.
3. Salve de novo e observeA materialização acontece no salvamento. Um perfil editado e não salvo é só uma tela bonita.
4. Verifique se o menu segue ativoMenu desativado some do catálogo espelhado e, por consequência, da navegação de todo mundo.
5. Teste com outra conta do mesmo perfilSe o comportamento se repete, o problema é do desenho. Se não, é da conta.
6. Só então suspeite do ambienteEstrutura de banco não aplicada explica muita coisa, mas é a última hipótese, não a primeira.

O que muda com o modelo legado convivendo

A convivência entre as duas camadas é o que permite migrar sem susto, e foi exatamente isso que salvou a nossa implantação. Mas ela também cria uma armadilha: como o legado continua valendo, dá para achar que o perfil novo não está fazendo nada quando, na verdade, ele está fazendo tudo e o comportamento é o mesmo de antes. Conferir com um usuário real resolve a dúvida em minutos.

O que anotar para não repetir a investigação

Toda vez que você resolver um caso desses, escreva o sintoma e a causa em duas linhas. Depois de meia dúzia de anotações você tem um guia de diagnóstico melhor do que qualquer documentação genérica, porque ele fala das telas que a sua empresa usa. Aqui esse hábito reduziu bastante o tempo de resposta, e ainda serviu de treinamento para quem entrou depois.

• O sintoma foi descrito do jeito que o usuário contou, não do jeito técnico.
• A causa real foi registrada, mesmo quando foi erro de quem configurou.
• A tela envolvida e o escopo dela ficaram anotados.
• Ficou claro se a estrutura de banco do modelo novo já está aplicada.
• A anotação está em lugar que outra pessoa encontra sozinha.

Para fechar o ciclo, vale ler os erros comuns na configuração de permissões, revisar o desenho em estruturação de perfis de acesso e confirmar os pré-requisitos técnicos em checklist de implantação. Se o seu ambiente puxa dados para painéis externos, combine o recorte por empresa com quem cuida de dados e relatórios antes de liberar qualquer consulta ampla.