TDD — Gestão de acesso no nível de ministério

Status

Implementado (piloto no gateway de usuário)

Objetivo

Definir modelo técnico de autorização central por perfil para funcionalidades de ministério, com níveis FULL, READ, NONE.

Modelo de dados

Níveis de acesso

Código	Nome amigável	Semântica
FULL	Completo	Leitura e escrita
READ	Leitura	Apenas leitura
NONE	Nenhum	Sem acesso

Matriz canônica por ministério

Documento:

{
  "version": 1,
  "levels": [
    { "code": "FULL", "friendlyName": "Completo" },
    { "code": "READ", "friendlyName": "Leitura" },
    { "code": "NONE", "friendlyName": "Nenhum" }
  ],
  "entries": [
    {
      "roleId": "EBD_TEACHER",
      "resourceId": "USER_PROFILE",
      "actionId": "GET",
      "accessLevelCode": "READ",
      "accessLevelName": "Leitura"
    }
  ],
  "updatedAt": "2026-03-11T00:00:00.000Z",
  "updatedBy": "system:migration-access-matrix"
}

Caminho:

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

Catálogo canônico de acesso por ministério

Documento:

{
  "version": 1,
  "resources": [
    {
      "resourceId": "USER_PROFILE",
      "resourceName": "Perfil do usuário",
      "actions": [
        { "actionId": "GET", "actionName": "Consultar", "mode": "READ" },
        { "actionId": "UPDATE", "actionName": "Atualizar", "mode": "WRITE" }
      ]
    }
  ],
  "updatedAt": "2026-03-11T00:00:00.000Z",
  "updatedBy": "system:access-catalog"
}

Caminho:

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

Fallback temporário de transição:

• platform/ministrys/{ministryId}/data/user_roles/catalog

Regras de resolução

Entrada:

• ministryId
• requesterRole
• resourceId
• actionId (opcional)

Processo:

1. Verificar regra explícita para resourceId/actionId no papel atual.
2. Sem regra, verificar regra de resourceId sem ação.
3. Sem regra, herdar da hierarquia inferior (quem pode mais, pode menos).
4. Sem correspondência, retornar NONE.

Regras adicionais para Relatório EBD

Além da matriz de acesso, o backend deve validar:

• vínculo de classe para ações de assistente/professor;
• vínculo de igreja para ações de superintendente;
• escopo de ministério para ações de secretaria geral/coordenação;
• fase do relatório para permitir ou negar transições.

Regra de fase:

• ENVIADO bloqueia edição para papéis operacionais;
• apenas papéis de governança podem DEVOLVER ou APROVAR.

Regra combinada (UX + backend)

Para ações da Home:

• visible = roleEligible(minRole) AND matrix>=READ
• canRead = matrix>=READ
• canWrite = matrix==FULL

Onde:

• roleEligible(minRole) usa hierarquia do catálogo (minRole/minHierarchyLevel);
• matrix é resolvida por resourceId/actionId definidos no access_catalog/current.

Contratos de serviço

Serviço: RoleCatalogService

• resolveAccessLevel(...)
• canRead(...)
• canWrite(...)

Contratos de API (gestão da matriz)

Via userGatewayHttp (v1), ações planejadas:

• USER_ACCESS_MATRIX_GET
• USER_ACCESS_MATRIX_UPDATE
• USER_HOME_ACTIONS_ACCESS_GET (consulta de acesso por lista de ações da Home)

Payload esperado:

• USER_ACCESS_MATRIX_GET: {} (usa ministério do escopo)
• USER_ACCESS_MATRIX_UPDATE: { entries: [...], version, reason? }
• USER_HOME_ACTIONS_ACCESS_GET: { items: [{ actionId, resourceId, readActionId, writeActionId? }] }

Resposta de USER_ACCESS_MATRIX_GET inclui:

• entries com resourceName e actionName (quando disponíveis);
• catalog.roles para combos de papel;
• catalog.resources[].actions[] para combos de recurso/ação;
• levels para combos de nível.

Validação de autorização:

• leitura: resourceId=ACCESS_MATRIX, actionId=GET (mínimo READ)
• escrita: resourceId=ACCESS_MATRIX, actionId=UPDATE (FULL)

Recursos/Ações de referência para relatório EBD

Recursos:

• ATTENDANCE
• LESSON
• EBD
• REPORT_WORKFLOW

Ações mínimas:

• ATTENDANCE/REGISTER
• LESSON/LIST
• LESSON/CLASSES_REPORT
• EBD/FILL_REPORT
• EBD/SESSIONS_REPORT
• EBD/CREATE_SESSION
• LESSON/FILL_CLASS_REPORT
• EBD/SEND_REPORT
• EBD/RETURN_REPORT
• EBD/APPROVE_REPORT
• REPORT_WORKFLOW/GET
• REPORT_WORKFLOW/UPDATE

Observação:

• SEND_REPORT, RETURN_REPORT e APPROVE_REPORT exigem validação de fase e escopo adicional no backend.
• CREATE_SESSION e FILL_CLASS_REPORT devem ser expostos como ações distintas para separar responsabilidade de sessão vs classe.

Integração piloto atual

No ProcessUserActionUseCase, foi aplicada autorização central para ações:

• USER_GET
• USER_MESSAGES_LIST
• USER_ROLES_AVAILABLE_LIST
• USER_PROFILE_UPDATE
• USER_PREFERENCES_UPDATE
• USER_ACTIVE_ROLE_SET
• USER_ROLE_REQUEST
• USER_ROLE_REQUEST_DELETE
• USER_ROLE_REQUEST_APPROVE
• USER_ROLE_REQUEST_REJECT
• USER_ROLE_REQUESTS_PENDING
• USER_MESSAGE_MARK_READ
• USER_CHANGE_STATUS
• USER_SELF_REGISTER

Cobertura atual e gap

• Ações do userGatewayHttp já passam pelo autorizador central (assertMinistryAccess).
• Fluxos com acesso direto do frontend ao Firestore não passam pela matriz no backend.
• Meta de arquitetura: migrar operações críticas para gateway/backend before-write.

Rollout

Se access_matrix/current ainda não existir para o ministério, o backend usa fallback compatível para não interromper ambientes legados. Ao ativar a matriz canônica, a política passa a ser estrita.

Quando access_catalog/current não existir, o backend pode fornecer nomes amigáveis por fallback temporário interno. A política alvo é eliminar fallback hardcoded no frontend.

Seed operacional da matriz (papéis EBD)

Script operacional deve garantir bootstrap das permissões funcionais para todos os papéis ativos EBD_* no ministério:

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

Requisitos:

• idempotente;
• não sobrescrever entradas existentes;
• manter access_catalog/current alinhado com recursos/ações usados no seed.

Testes

Teste de avaliação de acesso via script dedicado:

• npm run test:access-control

Referências

• docs/architecture/adrs/adr-0026-gestao-central-de-acesso-por-perfil-no-ministerio.md
• backend/functions/src/application/services/role-catalog-service.ts
• backend/functions/src/application/use-cases/process-user-action.ts