TDD — Ações da Home (visibilidade e execução)

Status

Planejado

Objetivo

Padronizar como as ações da aba Home/Ações são:

• exibidas na UI;
• autorizadas no backend;
• diferenciadas entre leitura, escrita e sem acesso.

Regra padrão

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

Interpretação dos níveis

Nível	Exibe ação	Permite leitura	Permite escrita
NONE	Não	Não	Não
READ	Sim	Sim	Não
FULL	Sim	Sim	Sim

Fonte dos critérios

• minRole/minHierarchyLevel: catálogo de papéis do ministério;
• catálogo de acesso: platform/ministrys/{ministryId}/data/access_catalog/current (resource/action + nomes amigáveis);
• matrix: platform/ministrys/{ministryId}/data/access_matrix/current (nível por papel).

Registro das ações

As ações da Home não são cadastradas somente na matrix.

Modelo oficial:

1. Catálogo da Home (frontend) define presença/ordem/rota da ação.
2. Catálogo de acesso (BD) define resourceId/actionId e nomes amigáveis.
3. Matrix (BD) define accessLevelCode por papel.

Sem item no catálogo de acesso, a ação não deve ser exibida para usuários finais.

Mapeamento inicial (HomeAction -> Matrix key)

HomeAction ID	resourceId	actionId	Tipo
open_profile	USER_PROFILE	GET	leitura
register_attendance	ATTENDANCE	REGISTER	escrita
my_lessons	LESSON	LIST	leitura
fill_ebd_report	EBD	FILL_REPORT	escrita
ebd_sessions_report	EBD	SESSIONS_REPORT	leitura
classes_report	LESSON	CLASSES_REPORT	leitura
manage_access_matrix	ACCESS_MATRIX	GET/UPDATE	leitura+escrita

Requisitos de implementação

1. Serviço de ações da Home deve combinar minRole com resultado da matriz.
2. Ação com READ e sem FULL pode abrir tela em modo leitura (quando aplicável).
3. Toda escrita deve passar por backend com validação de matriz.
4. Ações ainda em Firestore direto devem migrar para gateway/backend.

Critérios de aceite

• Usuário com NONE não vê ação e backend bloqueia.
• Usuário com READ vê ação e consegue apenas leitura.
• Usuário com FULL vê ação e consegue escrita.
• Logs/auditoria registram bloqueios por FORBIDDEN_ACCESS_LEVEL.
• UI da Home e da Gestão de Permissões exibem somente nomes amigáveis vindos do backend.

Referências

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