Concedendo permissões

Permissões são os verbos pequenos que a plataforma realmente confere. Este usuário pode registrar uma doação? Pode excluir um membro? Pode aprovar um relatório? Cada verbo tem uma chave como giving.record ou members.delete, e a resposta é sim se alguma das funções do usuário tem essa chave ativada em role_permissions_v2.

São 68 chaves. Elas vêm com a plataforma — você não pode adicionar novas, não pode renomear as existentes, e elas não mudam entre igrejas. O que você controla é a fiação: quais funções concedem quais chaves. Essa fiação vive na matriz de permissões.

Abrindo a matriz

Em Usuários e Funções, clique na aba Funções e Permissões. A matriz aparece sob a lista de funções, com uma linha por permissão e uma coluna por função. A caixa de filtro no canto superior esquerdo restringe as linhas visíveis por recurso, ação, chave ou descrição — digite giving para ver apenas as sete chaves de doações, ou delete para ver toda permissão destrutiva em todos os módulos de uma vez.

Como a matriz é organizada

As permissões são agrupadas por recurso — members, giving, reports, events, e assim por diante. Dentro de cada grupo são ordenadas por ação (view antes de edit antes de delete). O agrupamento é puramente visual; sob o capô cada permissão é uma chave plana. A taxonomia completa:

Recurso	Ações que você verá
dashboard	view
members	view, create, edit, delete, merge
attendance	view, mark
giving	view, record, manage, donate
reports	view, view_all, submit, manage, delete, export, approve, unlock
org_units	view, create, edit, delete, manage
schools	view, manage
demographics	view
map	view, manage
ministries	view, manage
groups	view, manage
events	view, create, edit
messaging	view, send
notifications	view, send
users	manage
custom_fields	view, manage
config	manage
billing	manage
website	manage, publish, blog, sermons
podcast	manage
workflows	view, manage, execute, enroll
forms	submit, manage, view_submissions
zapier	view, manage

Isso dá 68 no total. A lista canônica vive em src/shared/lib/access-policy.ts no frontend e em supabase/functions/_shared/access-policy.ts no backend — ambos os arquivos são mantidos em sincronia.

Alternando uma permissão

Encontre a linha (a permissão) e a coluna (a função), e acione o interruptor. A alteração grava em role_permissions_v2 imediatamente — sem botão de salvar, sem etapa de confirmação. Usuários com essa função adotam o novo comportamento na próxima navegação de página ou refetch do React Query (tipicamente em segundos).

O toggle é simétrico: desligar remove a linha de role_permissions_v2; ligar a insere. Ambas as ações são gravadas no registro de auditoria com o e-mail do ator e o carimbo de hora, então você sempre pode reconstruir quem mudou o quê.

Combinações comuns

A maioria das funções úteis empacota algumas chaves juntas. Uma referência para os padrões que vemos com mais frequência:

Ler + escrever um recurso

members.view + members.edit — o par mais comum. Permite que alguém atualize números de telefone e endereços sem poder adicionar ou excluir ninguém. Bom para um membro de equipe de qualidade de dados.

giving.view + giving.record — registrar doações e ver histórico. A forma clássica do Tesoureiro. Adicione giving.manage se ele também cria fundos; deixe desligado se você quer um gerente de fundos separado.

attendance.view + attendance.mark — exatamente o que o voluntário do check-in precisa. Combine com permissões limitadas para restringi-lo a um culto ou campus.

Criar + editar mas sem excluir

members.create + members.edit (sem members.delete). Comum para líderes de ministério — podem adicionar visitantes e atualizar cadastros existentes mas não podem apagar ninguém. Exclusões tipicamente exigem um admin.

events.create + events.edit (sem delete) — mesma forma para trabalho de calendário. Permite que um líder de louvor adicione a série de ensaios sem poder remover o arquivo do ano passado.

Apenas visualização em tudo

Cada chave view sem mais nada é a função Viewer. Útil para membros do conselho, auditores e equipe em probação. Há um dashboard.view dedicado para que um Viewer possa cair em algum lugar que pareça significativo.

Manage vs verbos menores

Para alguns recursos, manage é um superconjunto que implica os verbos menores. giving.manage inclui a capacidade de registrar e visualizar na interface mas as permissões explícitas giving.record e giving.view ainda precisam estar ligadas para que as edge functions e RLS permitam as operações. Sempre conceda os verbos menores junto com manage — a matriz não os concede automaticamente.

config.manage é a única grande exceção: é um único interruptor que controla cada página de configurações (canais, módulos, PWA, configuração de visitantes, logs de dados). Não há chaves separadas de leitura/escrita para essas.

Onde a verificação realmente roda

Uma permissão não é verificada uma vez — é verificada em três lugares, nesta ordem:

1. A UI usa usePermissions().has("giving.record") para esconder botões. Isso é puramente cosmético; uma requisição forjada do cliente ainda pode chamar a API.
2. A edge function chama assertPermission(ctx, "giving.record") de _shared/caller-context.ts. Se o usuário não tem a chave, a função retorna 403 antes de tocar no banco de dados.
3. Row-Level Security no Postgres reconfere via o helper SQL has_permission() para a camada final de defesa.

Essa verificação em três camadas significa que uma função mal configurada nunca pode vazar dados acidentalmente — mesmo que a UI fique fora de sincronia com o banco de dados, a edge function e RLS rejeitarão a requisição.

Filtrando a matriz

Para igrejas com muitas funções personalizadas, a matriz pode ficar larga. A entrada de filtro a restringe ao digitar:

• giving — apenas a seção de doações.
• delete — toda ação destrutiva na plataforma.
• members.merge — encontra uma chave específica.
• report — também corresponde a reports.

O filtro confere recurso, ação, chave e descrição — o que acerta primeiro vence.

Próximo

• Permissões limitadas — combine uma concessão de permissão com um limite de unidade organizacional.
• Registro de auditoria de mudanças de função — veja quem ativou o quê.
• Funções padrão — o que as funções iniciadas incluem.