TDD — Gestão de permissões (Access Matrix)

Status

Planejado

Contexto

Será adicionada uma interface de gestão de permissões por papel no contexto do ministério, com backend como autoridade.

Documento de dados-alvo:

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

Objetivo

Permitir que usuários autorizados consultem e alterem níveis de acesso (FULL, READ, NONE) por papel/recurso/ação, respeitando a própria matriz.

Entrada da funcionalidade

Nova ação na aba Ações da Home:

• ID: manage_access_matrix
• Título: Gerenciar permissões
• Descrição: Alterar níveis de acesso por perfil

Regras de acesso

• Para abrir a tela: ACCESS_MATRIX/GET com nível mínimo READ.
• Para salvar alterações: ACCESS_MATRIX/UPDATE com nível FULL.
• Usuário com apenas READ visualiza a matriz em modo somente leitura.
• Usuário com NONE não deve ver a ação e, se tentar acessar por rota direta, backend deve bloquear.
• Exibição da ação na Home segue regra híbrida: minRole/minHierarchyLevel + matriz READ|FULL.

Interface de usuário (UI)

Estrutura da tela:

1. Cabeçalho com ministério, versão e data de atualização.
2. Filtros:
   • papel (roleId)
   • recurso (resourceId)
   • texto livre para ação (actionId)
3. Grid de permissões:
   • linhas: combinações de roleId + resourceId + actionId
   • coluna editável: nível amigável (Completo/Leitura/Nenhum) com persistência em accessLevelCode
4. Rodapé:
   • botão Descartar
   • botão Salvar alterações (habilitado somente quando há diff + permissão de escrita)

Fluxo técnico

1. Home -> ação manage_access_matrix -> abre página de gestão.
2. Frontend chama USER_ACCESS_MATRIX_GET.
3. Backend retorna matriz + metadados (version, updatedAt, updatedBy) e catálogo para a UI (roles, resources, actions, levels).
4. Usuário altera células da grade.
5. Frontend monta diff e chama USER_ACCESS_MATRIX_UPDATE.
6. Backend valida permissão de escrita, normaliza dados e persiste current.
7. Frontend recarrega matriz e exibe confirmação.

Impacto em UX da Home

Mudanças na matriz devem refletir na aba Ações:

• NONE remove o card da lista;
• READ mantém card visível para operações de leitura;
• FULL mantém card visível e habilita escrita quando aplicável.

Contratos planejados

USER_ACCESS_MATRIX_GET

Request:

{
  "version": "v1",
  "action": "USER_ACCESS_MATRIX_GET",
  "payload": {},
  "meta": { "request_id": "..." }
}

Response (data):

{
  "version": 1,
  "levels": [
    { "code": "FULL", "friendlyName": "Completo" },
    { "code": "READ", "friendlyName": "Leitura" },
    { "code": "NONE", "friendlyName": "Nenhum" }
  ],
  "entries": [],
  "updatedAt": "2026-03-11T00:00:00.000Z",
  "updatedBy": "system"
}

Cada item de entries pode incluir:

• resourceName
• actionName

O payload inclui também:

{
  "catalog": {
    "roles": [
      { "roleId": "EBD_SECRETARY", "roleDescription": "Secretário EBD", "hierarchyLevel": 50 }
    ],
    "resources": [
      {
        "resourceId": "LESSON",
        "resourceName": "Classes e aulas",
        "actions": [
          { "actionId": "LIST", "actionName": "Listar minhas aulas", "mode": "READ" }
        ]
      }
    ]
  }
}

USER_ACCESS_MATRIX_UPDATE

Request (payload):

{
  "version": 1,
  "entries": [
    {
      "roleId": "EBD_TEACHER",
      "resourceId": "USER_PROFILE",
      "actionId": "GET",
      "accessLevelCode": "READ",
      "accessLevelName": "Leitura"
    }
  ],
  "reason": "Ajuste de governança"
}

Regras:

• normalizar para uppercase em roleId/resourceId/actionId/accessLevelCode;
• validar accessLevelCode em {FULL, READ, NONE};
• deduplicar por chave (roleId, resourceId, actionId?);
• atualizar updatedAt/updatedBy.
• permitir criação e remoção de entradas pela UI, mantendo persistência via envio completo de entries.

Erros esperados

• FORBIDDEN_ACCESS_LEVEL — sem permissão para ler/escrever a matriz.
• INVALID_PAYLOAD — estrutura inválida.
• FORBIDDEN_SCOPE_MISMATCH — tentativa fora do ministério do ator.

Testes necessários

Backend:

• GET com READ retorna matriz.
• GET com NONE bloqueia.
• UPDATE com FULL persiste.
• UPDATE com READ bloqueia.
• validação/deduplicação de payload.

Frontend:

• ação visível só quando autorizado.
• modo read-only sem botão salvar.
• diff aplicado corretamente.
• feedback de sucesso/erro após salvar.
• renderização da grade com nome amigável (sem exibir código técnico para usuário final).
• inclusão de nova linha (papel + recurso + ação + nível) usando catálogo retornado pelo backend.
• prevenção de duplicidade de chave (roleId, resourceId, actionId) ao incluir linha.
• remoção de linha da matriz antes do salvar.

Seed inicial obrigatório (cargos EBD)

O bootstrap da matriz deve criar entradas faltantes para todos os papéis EBD_* ativos no catálogo do ministério, sem sobrescrever entradas já existentes:

• ATTENDANCE/REGISTER
• LESSON/LIST
• LESSON/CLASSES_REPORT
• EBD/FILL_REPORT
• EBD/SESSIONS_REPORT

Critério:

• idempotente (não duplica);
• não altera customização existente;
• níveis iniciais por faixa hierárquica (ex.: professor e acima para relatórios/preenchimento; aluno com leitura básica e/ou NONE explícito onde aplicável).

Nota de domínio — Relatório EBD

A matriz controla elegibilidade de funcionalidade, porém não substitui regras de negócio do relatório:

• assistente/professor operam somente em classes onde possuem vínculo;
• superintendente opera no escopo da igreja sob responsabilidade;
• secretaria geral/coordenação podem devolver/aprovar;
• relatório enviado não é editável por papéis operacionais.

Referências

• docs/architecture/adrs/adr-0026-gestao-central-de-acesso-por-perfil-no-ministerio.md
• docs/architecture/tdd/api/tdd-gestao-acesso-ministerio.md