Skip to content
EBDbe

ADR-0024 — Controle de visibilidade de ações por perfil

Status

Section titled “Status”

Aprovado

Contexto

Section titled “Contexto”

A aba Ações da página inicial (PRD-0002) exibe uma lista de ações disponíveis ao usuário (ex.: Registrar presença, Preencher relatório de EBD, Abrir perfil). Nem todas as ações devem ser visíveis ou executáveis por qualquer perfil. É necessário definir um mecanismo padronizado para controlar:

  1. Visibilidade — quais ações aparecem na lista
  2. Privilégio de escrita — se a ação permite alteração de dados ou apenas leitura

O catálogo de papéis (ADR-0019) já fornece hierarchyLevel por roleId (menor = mais poder). O perfil do usuário (ADR-0013) contém roleAssignments com papéis aprovados.

Decisão

Section titled “Decisão”

O sistema adotará controle híbrido de visibilidade para as ações da aba Ações:

  1. Elegibilidade de papel (hierarchyLevel / minRole) para contexto funcional da ação;
  2. Matriz de acesso (FULL/READ/NONE) para liberação de leitura/escrita.

1. Definição de ação (catálogo Home)

Section titled “1. Definição de ação (catálogo Home)”

Cada ação possui:

  • id — identificador único
  • title — título exibido
  • subtitle — descrição curta (opcional)
  • icon — ícone (opcional)
  • minHierarchyLevel (ou minRoleId) — menor (mais alto) nível hierárquico que pode ver a ação. Ex.: nível 5 permite EBD_TEACHER e todos os cargos acima (4, 3, 2, 1, 0, -1)
  • writeAllowed — se a ação permite escrita (alteração de dados); false = apenas leitura

2. Regra de visibilidade

Section titled “2. Regra de visibilidade”

Uma ação é visível para o usuário quando:

  • O usuário possui ao menos um papel com status = APPROVED em roleAssignments
  • O hierarchyLevel desse papel (consultado no catálogo) é menor ou igual a minHierarchyLevel da ação
  • A matriz de acesso para o recurso/ação correspondente é READ ou FULL
  • O perfil está carregado (usuário autenticado)

Melhor nível do usuário: entre todos os papéis aprovados, considera-se o menor hierarchyLevel (maior poder). Se o usuário tem EBD_TEACHER (5) e EBD_SECRETARY (4), seu nível efetivo é 4.

3. Regra de execução (autoridade backend)

Section titled “3. Regra de execução (autoridade backend)”
  • Leitura: backend exige matriz READ ou FULL.
  • Escrita: backend exige matriz FULL.
  • NONE: backend sempre bloqueia.

writeAllowed no frontend é apenas metadado de UX; não substitui validação backend.

4. Sem perfil

Section titled “4. Sem perfil”

Quando o usuário não está logado ou o perfil não está carregado, apenas ações que não exigem perfil (ex.: Abrir perfil que leva ao login) podem ser exibidas, conforme regra específica de cada ação.

Consequências

Section titled “Consequências”
  • A aba Ações deve consumir um serviço central que retorna a lista filtrada de ações (HomeActionsService ou equivalente).
  • Novas ações devem ser registradas com minHierarchyLevel/minRole e mapeamento para recurso/ação da matriz.
  • O catálogo de papéis deve estar disponível (RoleCatalogService) para resolver hierarchyLevel por roleId.
  • Backend permanece autoridade final; visibilidade no frontend é otimização de UX.
  • Ações ainda não migradas para backend gateway devem ser tratadas como dívida técnica de segurança.

Referências

Section titled “Referências”
  • ADR-0003 — Controle de Acesso (RBAC)
  • ADR-0019 — Catálogo de papéis em memória no cliente
  • ADR-0013 — Perfil de usuário e ciclo de vida
  • ADR-0026 — Gestão central de acesso por perfil no ministério
  • PRD-0002 — Página inicial (aba Ações)