Skip to content
EBDbe

adr-0019-catalogo-de-papeis-em-memoria-no-cliente

Decisão

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.