Skip to main content

ADR-0019 — Catálogo de papéis em memória no cliente e acesso unificado

Status​

Aprovado

Contexto​

O catálogo de papéis (user_roles/catalog) é consultado pelo frontend para exibir papéis disponíveis (ex.: diálogo de perfil, solicitação de cargo). Sem uma camada central no cliente:

  • Cada tela poderia chamar o backend diretamente, gerando cargas repetidas ao BD.
  • Não haveria cache em memória nem opção de adicionar roles incrementalmente ou recarregar o catálogo completo de forma controlada.

É desejável o mesmo conceito adotado para o perfil do usuário (ADR implícito no UserProfileService): uma classe que centraliza leitura, mantém estado em memória e é o único ponto que persiste alterações quando houver escrita.

Decisão​

O sistema adotará um serviço central de catálogo de papéis no cliente (RoleCatalogService), alinhado ao conceito do serviço de perfil.

1. Acesso unificado​

  • Todas as chamadas ao catálogo de papéis no frontend devem ser feitas por meio do RoleCatalogService.
  • Nenhum módulo de apresentação ou aplicação deve chamar o repositório/backend diretamente para obter a lista de papéis disponíveis.

2. Cache em memória​

  • O serviço mantém em memória os resultados já carregados, indexados por contexto (unitId, requesterRole) ou por catálogo completo (full).
  • Primeira requisição para um dado contexto carrega do backend e armazena no cache.
  • Requisições subsequentes para o mesmo contexto retornam do cache, salvo indicação de refresh.

3. Modos de carregamento​

  • Normal: retorna do cache se existir; caso contrário, carrega do backend e armazena.
  • Catálogo completo (fullCatalog): solicita ao backend o catálogo completo do ministério (sem filtro de igreja/requester); armazena em cache próprio e retorna.
  • Adição (addOnly): carrega do backend e mescla o resultado com o cache existente para aquele contexto (novos roleIds são adicionados, sem substituir o cache).
  • Refresh forçado (forceFullRefresh): ignora cache e recarrega do backend, atualizando o cache.

4. Persistência no BD​

  • Eventuais alterações nos dados do catálogo (ex.: admin atualiza papéis) devem ser persistidas no BD apenas por fluxos que passem por este serviço (ou pelo backend quando for o caso). O cliente não deve gravar no catálogo por vias alternativas.
  • O backend continua sendo a autoridade do catálogo (Firestore/user_roles/catalog); o serviço no cliente apenas centraliza leitura e cache e, no futuro, orquestra escritas se houver fluxos para isso.

5. Limpeza de cache​

  • O cache deve ser limpo ao logout (ou ao trocar de ministério/tenant), para evitar vazamento de contexto entre sessões.

Consequências​

  • Redução de chamadas ao backend/BD para o mesmo contexto de catálogo.
  • Comportamento previsível: um único ponto de acesso e uma única política de cache e persistência.
  • Backend expõe opção de retorno de catálogo completo (payload fullCatalog) para suportar o modo full no cliente.
  • Integração com ADR-0018 (catálogo de roleId) e ADR-0014 (gateway único); a ação USER_ROLES_AVAILABLE_LIST permanece no gateway com suporte a fullCatalog.

Integração com ADRs existentes​

  • ADR-0018: catálogo de roleId compartilhado entre backend e frontend; o serviço no cliente consome esse catálogo via gateway.
  • ADR-0014: ação USER_ROLES_AVAILABLE_LIST no gateway único; payload pode incluir fullCatalog para catálogo completo do ministério.
Last updated on