ADR-0026 — Gestão central de acesso por perfil no ministério

Status

Aprovado

Contexto

O projeto já possui:

• RBAC com escopo hierárquico (ADR-0003);
• catálogo de papéis por ministério com hierarchyLevel;
• filtragem de visibilidade no frontend para UX (ADR-0024).

Faltava uma gestão central em BD para definir, por perfil, o nível de acesso de cada funcionalidade do ministério com um modelo único.

Decisão

O backend adota uma matriz central de permissões por ministério, com modelo híbrido:

• resourceId (recurso funcional);
• actionId opcional (ação específica);
• accessLevel com três níveis:
  • FULL — nome amigável: Completo
  • READ — nome amigável: Leitura
  • NONE — nome amigável: Nenhum

Regra de herança

Regra oficial: quem pode mais, pode menos.

Na avaliação de acesso:

1. Busca regra explícita do papel atual para resourceId/actionId.
2. Se não existir, busca regra do mesmo resourceId sem actionId.
3. Se ainda não existir, herda da hierarquia inferior (papéis com hierarchyLevel maior), priorizando o nível imediatamente inferior.
4. Sem regra aplicável, resultado é NONE.

Autoridade

• Backend é autoridade final de autorização.
• Frontend pode usar o resultado apenas para UX.

Regra combinada para Home/Ações

Para ações exibidas no frontend, aplica-se regra híbrida:

• visibilidade = elegível por minRole/minHierarchyLevel e matriz READ|FULL;
• execução leitura = matriz READ|FULL;
• execução escrita = matriz FULL;
• matriz NONE implica ocultar ação na UX e bloquear execução no backend.

Aplicação ao domínio de relatório EBD

Para recursos de relatório EBD, a autorização é composta por:

• nível de acesso na matriz (EBD / LESSON / ATTENDANCE);
• papel ativo;
• vínculo operacional (classe/igreja/ministério);
• fase atual do relatório.

Diretriz:

• autorização de papel não substitui validação de vínculo e fase no backend;
• após ENVIADO, apenas papéis de governança podem executar ações de DEVOLVER ou APROVAR;
• papéis operacionais (assistente/professor/superintendente) não editam relatório em estado final.

Rollout

Enquanto o ministério não possuir matriz em access_matrix/current, o backend pode operar em fallback compatível para evitar quebra de ambiente legado.

Precedência durante migração:

1. platform/ministrys/{ministryId}/data/access_matrix/current
2. fallback temporário em platform/ministrys/{ministryId}/data/user_roles/catalog

Persistência

Catálogo canônico por ministério (cadastro de recursos/ações e nomes amigáveis):

• platform/ministrys/{ministryId}/data/access_catalog/current

O documento current contém:

• version
• resources[] com:
  • resourceId
  • resourceName
  • actions[] com:
    • actionId
    • actionName
    • mode (READ ou WRITE)
• updatedAt
• updatedBy

Matriz canônica por ministério (somente política por papel):

• platform/ministrys/{ministryId}/data/access_matrix/current

O documento current contém:

• version
• levels[] com code + friendlyName
• entries[] com:
  • roleId
  • resourceId
  • actionId?
  • accessLevelCode
  • accessLevelName?
• updatedAt
• updatedBy

user_roles/catalog permanece como catálogo de papéis/hierarquia.

Separação oficial:

• access_catalog/current define o que existe (códigos + nomes amigáveis);
• access_matrix/current define quem pode o quê.

Gestão operacional

A edição da matriz deve ocorrer por ação dedicada na Home (“Gerenciar permissões”), consumindo API do backend com validação da própria matriz de acesso:

• leitura: ACCESS_MATRIX/GET
• escrita: ACCESS_MATRIX/UPDATE

Frontend nunca é autoridade de autorização.

Renderização da UI:

• A UI deve exibir somente nomes amigáveis vindos do backend (roleDescription, resourceName, actionName, friendlyName).
• Códigos técnicos (roleId, resourceId, actionId, accessLevelCode) são usados para persistência, integração e auditoria.

Cobertura e migração

Toda ação de negócio deve passar por backend com validação da matriz.

Enquanto existirem fluxos com acesso direto do cliente ao Firestore (sem gateway), a cobertura de autorização central não é total e deve ser tratada como etapa de migração.

Consequências

• Permissões deixam de ficar espalhadas por casos de uso isolados.
• Facilita auditoria de acesso por funcionalidade.
• Exige governança do catálogo por ministério.

Referências

• ADR-0003 — Controle de Acesso (RBAC com Escopo Hierárquico)
• ADR-0024 — Controle de visibilidade de ações por perfil
• docs/architecture/tdd/api/tdd-gestao-acesso-ministerio.md