Pular para o conteúdo principal

Agente Query (EAQ)

Introdução​

A API Agente Query é responsável por consultar e consolidar informações relacionadas aos agentes do sistema, como papéis, cargos, locais e outras atribuições. Seu principal objetivo é centralizar e disponibilizar, de forma padronizada, os dados de permissões e vínculos de cada usuário para os demais componentes do E-Docs.

Advogados​

Regras de Negócio

  • Busca advogados cadastrados no patriarca OAB a partir do termo de busca. Retorna uma lista de papeis de advogado (AgenteDto). Limitado a 50 resultados.
  • Filtro de OAB: apenas papéis ligados à OAB são consultados, garantindo que os resultados sejam advogados;
  • Lista vazia em casos inválidos: tanto a ausência de termo de busca quanto a ausência de papéis válidos resultam em lista vazia, evitando exceções e chamadas desnecessárias;

Agentes​

Agente Builder​

Função

Construir objetos AgenteDto a partir de diferentes tipos de entidades ou identificadores, encapsulando toda a lógica necessária para montar corretamente as informações do agente no E-Docs.

Regras de Negócio

  • Não é permitido construir um agente sem ID válido.
  • Um papel só é considerado válido se houver uma lotação associada.
  • Antes de devolver dados de unidade/órgão, é verificado se o Patriarca está habilitado ou pertence à OAB; caso contrário, não expõe esse agente.
  • Unidades e organizações inativas não devem aparecer como agentes.
  • (Unidade -> Organização -> Grupo -> Cidadão -> Papel -> Sistema) É a ordem de prioridade definida pelo domínio para identificar agentes a partir de um GUID.
  • Ao obter um agente ativo por tipo, caso cache retorne valor inválido de tipo, o fluxo segue normalmente.

Agente Helper​

Função

Padronizar como os agentes são identificados e exibidos no sistema.

Regras de Negócio

  • Para cada tipo de agente (Cidadão, Papel, Grupo, Unidade, Organizacão, Sistema), há um formato específico de string a ser usada em logs. Essa regra padroniza como os agentes aparecem nos registros do sistema, garantindo que cada tipo traga as informações relevantes (nome do cidadão, IDs, siglas de unidade/órgão, Patriarca etc.).
  • AgenteIdByTipo define como recuperar o Guid de um agente inativo conforme seu tipo. Por exemplo: se for um Cidadão, usa IdAgente; se for Unidade, usa IdUnidade; se for Organizacão, usa IdOrganizacao; se for Grupo, usa IdGrupo; se for Papel, usa IdPapel. Caso não haja tipo ou ID, retorna Guid.Empty. Dessa forma cada tipo de agente tem um campo de ID próprio.
  • O método MapToAgenteDto mapeia uma entidade de carga (AgenteCarga) para um AgenteDto, copiando todos os campos que o sistema considera relevantes. A regra aqui é: "os DTOs expostos para outras camadas devem refletir fielmente os dados de Unidade, Órgão, Patriarca, Sistema, Papel, Grupo e Cidadão presentes na carga". Se agenteCarga for nulo, devolve null – não tenta construir um DTO vazio.
  • Sempre que um AgenteDto precisa ser complementado com informações de localização (Unidade, Órgão e Patriarca), o método LoadUnidadeAndOrgaoAndPatriarcaFromLocalizacao preenche essas propriedades a partir de uma AgenteCarga. A regra é: "não se constrói um agente sem atualizar também seus dados de Unidade/Órgão/Patriarca". Se a localizacaoCarga for nula, retorna null.

Agente Inativado​

Função

Listar GUIDs de agentes inativados recentemente pelo Acesso Cidadão.

Regras de Negócio

  • Verifica grupos, órgãos, unidades e papeis inativados. Adicionando o valor do retorno de cada consulta à lista de agentesInativos e depois retornando seus GUIDs.

Agente Query​

Função

Contultar estado dos agentes, ativos ou inativos.

Regras de Negócio

  • Sempre que um GUID é Empty, a operação não deve prosseguir. Retorna erro e loga um aviso.
  • A busca de agentes ativos ou inativos primeiro tenta buscar o agente ativo usando _agenteBuilder. Se não encontrar, tenta buscar o agente inativo no Elastic. Se ainda assim não achar, retorna null (não gera erro).
  • A busca de agentes ativos usa somente _agenteBuilder (constrói agente ativo) e não cai para busca de inativos.
  • A busca de agentes inativos busca diretamente no Elastic (_elasticQueryApiClient.ObterAgenteInativo) e transforma o resultado bruto em um AgenteDto com Ativo=false e todos os campos mapeados.
  • Na busca por termo:
    • O IdPatriarca é obrigatório (não pode ser Guid.Empty).
    • O termo de busca não pode ser vazio.
    • Se todos os filtros SearchServidor, SearchAdvogado, SearchGrupo, SearchOrgao, SearchUnidade forem false, a busca passa a considerar todos os tipos (boolGeralNOR).
    • Para Servidor: busca papéis do Patriarca no Acesso Cidadão.
    • Para Advogado: busca papéis no Acesso Cidadão usando Constantes.OAB.
    • Para Órgão/Unidade: busca guids de agentes ativos no Elastic, depois converte para AgenteDto via repositório.
    • Todos os resultados são ordenados (CidadaoNome > PapelNome > UnidadeNome > OrgaoNome).
  • Na busca por CPF:
    • IdPatriarca obrigatório;
    • CPF não pode ser vazio, inválido ou malformatado (usa método IsCpfValido).
    • Remove caracteres não numéricos do CPF antes da consulta.
    • Consulta o Cidadão no Acesso Cidadão pelo CPF.
    • Se for pesquisa de Cidadão: converte o Cidadão retornado em AgenteDto via BuildCidadao.
    • Se for pesquisa de Servidor: busca papéis do cidadão no Acesso Cidadão, filtra apenas aqueles cujo PatriarcaId é igual ao IdPatriarca informado.
    • Resultados ordenados por PapelNome.
  • Na conversão de inativos para DTO são obtidos os campos "brutos" do agente inativo (IDs, nomes, siglas) e preenchido um AgenteDto com Ativo=false.
  • Na validação do CPF é implementado a regra oficial do CPF brasileiro:
    • Deve ter 11 dígitos.
    • Não pode ser todos iguais.
    • Calcula corretamente os dois dígitos verificadores.

Local Query​

Função

Obter papéis ou membros através de consultas usando órgãos/unidade ou grupos.

Regras de Négocio

  • Sempre que um GUID é vazio ou o retorno de uma api houver falha, a operação não deve prosseguir. Retorna erro e loga um aviso.
  • No método ObterPapelGestorEmConjunto:
    • É feita uma busca no acesso cidadão para papel de gestor através do idOrgaoOuUnidade.
    • Caso o retorno da api seja válido mas nulo, retorna sucesso com AgenteDto nulo (não gera erro).
    • Se houver gestor, usa agenteBuilder para construir e retornar o Dto.
  • Em ObterGupoMembros:
    • É feita uma busca por termo no acesso cidadão para papéis do grupo através do idGrupo, passando como termo string vazia.
    • Caso o retorno da api seja válido mas vazio, retorna sucesso com lista de membros vazia (não gera erro).
    • Se houver papéis, percorre a lista:
      • Para cada papel, ignorar se não houver AgentePublicoSub.
      • Se houver, usar agenteBuilder para construir uma AgenteDto.
      • Caso a construção falhe, não adiciona o item a lista, mas continua processando os demais.

Organizações​

Organizações Helper​

Função

Mapear, manipular e filtrar dados dos grupos.

Regras de Negócio

  • No método MapToAgenteDto:
    • Mesmo que grupoModelDto venha nulo ou com Guid vazio, não é gerado erro; O método retorna null e não mapeia nada.
    • Caso o grupo possua ConjuntoPai é feita uma busca no repositório de organização da unidade ou órgão ativo referente ao pai; Se não, busca a organização ativa usando GuidOrgao.
    • Se conseguir um conjunto pai válido, constrói um novo AgenteDto com dados do grupo + dados herdados do conjuntoPai; Caso não consiga, retorna null.
  • Em RemoverGruposNaoUtilizados:
    • É passado uma lista de grupos e o método remove qualquer grupo que não tenha TipoId igual a 4, 5 ou 6.
    • Caso a lista venha vazia ele retorna null.

Organizações Query​

Função

Fornecer dados estruturados de um determinado órgão, aplicando os filtros e formatações adequadas antes de devolver para aplicação.

Regras de Negócio

  • No método privado ConstruirArvore:
    • A árvore é montada com base na hierarquia de unidades. Cada nó representa uma UnidadeArvoreDto com um AgenteDto dentro.
    • Somente unidades com agente correspondente são incluídas. Se não existe AgenteDto para uma unidade filha, ela é ignorada (não entra na árvore).
    • Filhos são construidos recursivamente. A estrutura é percorrida até o nível mais profundo de hierarquia.
    • Cada nó sempre tem uma lista Filhos inicializada. Garante que é possível adicionar subnós sem null.
    • A Árvore se baseia no Guid do pai. GuidUnidadePai indica quem é o pai na hierarquia; GuidUnidade indica a unidade filha.
  • Em ValidarOrgaoEPatriarcaAsync:
    • Este método privado faz 3 validações principais:
      • Primeiro verifica se o GuidOrgao esta vazio
      • Depois se o AgenteCarga desse órgão é nulo, vazio ou com valor diferente de ativo.
      • Por último verifica se o patriarca é habilitado.
    • Se alguma dessas validações falhar, é gerado erro.
    • Caso contrário é retornado o orgaoAgenteCarga.
  • O método ObterUnidadesByOrgao retorna uma nova lista de AgenteDto, para isso:
    • Valida o órgão e o patriarca através do método apresentado acima (ValidarOrgaoEPatriarcaAsync).
    • Com o método ObterUnidadesAtivasEmOrdemSiglaPorOrgao, são ordenadas apenas unidades ativas.
    • Caso não exista nenhuma unidade ativa para o órgão, retorna sucesso com a lista vazia (não gera erro).
  • ObterUnidadesEmArvoreByOrgao segue a mesma validação do método anterior:
    • GuidOrgao não pode ser vazio.
    • Órgão precisa existir, estar ativo e com patriarca habilitado.
    • Só considera unidades ativas no órgão.
    • Além disso, a estrutura retornada segue a hierarquia pai-filho definida no banco.
    • Unidades com GuidUnidadePai igual a null são tratadas como "raiz" da árvore.
    • Caso não exista nenhuma unidade ativa para o órgão, retorna sucesso com a lista vazia (não gera erro).
  • ObterGruposComissoesByOrgao:
    • GuidOrgao não pode ser vazio.
    • Órgão precisa existir, estar ativo e com patriarca habilitado.
    • Se searchGrupo e searchComissoes são ambos true OU ambos false,busca grupos e comissões.
    • Se apenas searchGrupo = true, busca só grupos.
    • Caso só searchComissoes = true, busca apenas comissões.
    • Grupos não utilizados são removidos antes do retorno.
    • Cada grupo ou comissão é mapeado e convertido para AgenteDto com dados pertinentes ao órgão.
    • Lista final é ordenada por GrupoNome.

Patriarcas​

Patriarca Helper​

Função

Aplicar verificações e regras específicas em Guids de Patriarcas.

Regras de Negócio

  • IsPatriarcaHabilitado:
    • Se o GuidPatriarca for null ou Guid.Empty, considera não habilitado e retorna false.
    • Para guids válidos, chama o método IsPatriarcaHabilitados (que trata listas) para verificar o status.
    • Se estiver habilitado no sistema retorna true.
    • Se não estiver habilitado ou houver qualquer problema na verificação retorna false.
  • IsPatriarcasHabilitados:
    • Se a lista for null ou vazia, retorna uma lista vazia.
    • Busca patriarcas habilitados no repositório.
    • Caso a busca falhe ou retorne null, considera que TODOS os guids recebidos não estão habilitados.
    • Validação individual para cada guid recebido:
      • Se o for Guid.Empty, marca como não habilitado.
      • Se estiver presente na lista de habilitados, marca como IsHabilitado = true.
      • Caso não esteja presente, marca IsHabilitado = false.
    • Retorna uma lista de tuplas com status para cada patriarca.
  • IsPatriarcaOAB:
    • Se o GuidPatriarca for null ou Guid.Empty, retorna false.
    • Caso o guid informado for igual ao Constates.OAB, retorna true (assumindo ser um patriarca OAB).
    • Para qualquer outro guid, retorna false.

Patriarca Query​

Função

Buscar informações de patriarcas ou organizações relacionadas a patriarcas, garantindo que apenas patriarcas habilitados ou especiais sejam retornados.

Regras de Negócio

  • ObterPatriarcasHabilitados:
    • Busca a lista de patriarcas habilitados no repositório.
    • Se a busca falhar retorna erro.
    • Se não houver patriarcas habilitados ou lista de guids vazia, retorna sucesso com lista vazia.
    • Para os guids obtidos, busca dados completos no repositório. Converte cada patriarca para AgenteDto com AgenteHelper.MapToAgenteDto.
  • ObterOrganizacaoFilhasByPatriarca:
    • Se o guid for Guid.Empty, retorna falha.
    • Usa PatriarcaHelper.IsPatriarcaHabilitado para garantir que o patriarca está habilitado.
    • Caso não esteja habilitado, retorna falha.
    • Consulta o repositório para obter órgãos ativos do patriarca.
    • Converte cada patriarca para AgenteDto com AgenteHelper.MapToAgenteDto.
  • ObterPatriarcasEspeciais:
    • Lê a seção "PatriarcasGuidsEspeciais" para obter guids dos patriarcas especiais.
    • Consulta repositório para obter dados completos dos patriarcas especiais.
    • Caso a consulta falhe, retorna erro.
    • Converte cada patriarca para AgenteDto com AgenteHelper.MapToAgenteDto.

Permissões​

Permissão Agente Query​

Regras de Negócio

Antes de retornar as informações, a API realiza etapas de validação, como:

  • Verificação de Feature Flag: garante que determinadas funcionalidades estejam habilitadas ou desabilitadas conforme configurações do sistema.
  • Validação do tipo de agente: caso o agente informado não seja um cidadão, as verificações de permissões são dispensadas.
  • Controle de permissões: se o agente não possuir permissões, é retornada uma lista vazia; caso possua, são obtidos os GUIDs dos papéis autorizados.

Permissão E-Docs​

Função

Consultar e filtrar permissões de papéis, locais e ações do usuário.

Regras de Negócio

  • Validação inicial do usuário e da ação:
    • Todo acesso começa validando o GUID do usuário e o idAção.
    • Se o usuário não tiver nenhuma permissão para a ação solicitada, a API retorna lista vazia imediatamente.
  • Restrições por papel:
    • São obtidos os GUIDs dos papéis com permissão para a ação solicitada.
    • Se não houver papéis válidos, a lista também retorna vazia.
  • Restrições por localização:
    • Dependendo da consulta, além do idAção também é validada a localização (órgão ou unidade) do agente.
    • A validação pode ser feita para uma única localização ou para uma coleção de localizações, repetindo o mesmo padrão (verifica permissões, retorna lista vazia se não houver).
  • Locais de acesso:
    • O sistema busca todos os locais de acesso do agente (órgãos/unidades) presentes em guidsLocalizacoes.
    • Gera uma lista de PatriarcaId vinculados.
    • Verifica quais PatriarcaId estão habilitados (filtrando entidades não habilitadas, como OAB).
    • Retorna somente agentes e papéis que pertençam a PatriarcaId habilitados.
  • Verificação final de papéis:
    • Após passar pelas etapas acima, o sistema ainda valida se o idOrgaoUnidade é válido e se realmente possui papéis com permissões (via PapelRepository.SearchByPerfilAndConjunto).

Unidades​

Unidades Helper​

Função

Converter um objeto papel e um objeto unidade em um único AgenteDto que contém todos os dados necessários para ser usado no sistema.

Regras de Negócio

  • MapToAgenteDto:
    • Primeiramente faz verificação de parâmetros, caso o papelModelDto for nulo ou tiver Guid vazio, retorna null.
    • Na criação do AgenteDto:
      • Define Id e PapelId como o Guid do papel.
      • Define Ativo = true e Tipo = AgenteTipo.Papel.
      • Copia os dados de unidade, órgão e patriarca do AgenteDto da unidade recebida.
      • Define PapelNome como o nome do papel em maiúsculo.
      • Preenche os campos do cidadão com dados do papel.

Unidades Query​

Função

Buscar todas as lotações associadas a uma unidade específica, validar se a unidade existe e se o patriarca dela está habilitado, e devolver uma lista de AgenteDto representando essas lotações.

Regras de Negócio

  • ObterLotacoesByUnidade:
    • Validação inicial: caso guidUnidade estiver vazio, retorna erro.
    • Após isso busca as lotações ligadas à unidade; Caso a chamada falhe, retorna erro.
    • Depois busca a unidade ativa no repositório; Se não existir ou estiver inativa, retorna erro.
    • Usa IsPatriarcaHabilitado para verificar se o patriarca da unidade está habilitado; Caso não esteja, retorna erro.
    • Mapemento das lotações:
      • Para cada lotação retornada, converte para AgenteDto usando MapToAgenteDto de unidades.
      • E adiciona cada AgenteDto à lista de retorno.
    • Ordena a lista resultante por CidadaoNome e depois por PapelNome.
    • Por fim retorna a lista de AgenteDto.

Usuários​

Agente Público​

Função

Descobrir o Guid do usuário a partir do identificador "sub".

Regras de Negócio

  • ObterGuidUsuarioBySub:
    • Se sub for menor ou igual a 0, retorna erro.
    • Busca Agente Público via api do Acesso Cidadão.
    • Verifica resultado:
      • Caso falhe, retorna erro.
      • Se nulo, retorna sucesso com Guid vazio.

Usuário Query​

Função

Essa classe funciona como um serviço de integração com o cadastro do Acesso Cidadão. Ele centraliza métodos para:

  • Consultar papéis do cidadão.
  • Consultar localizações desses papéis.
  • Consultar grupo, comissões e conjuntos do gestor associado ao cidadão.
  • Consultar e-mails do cidadão.
  • Limpar cache do usuário.
  • Validar se a conta do cidadão é verificada.

Regras de Negócio

  • ObterPapeisServidor:
    • Se o idCidadao é vazio, retorna erro.
    • Busca os papéis do cidadão via _obterPapeis.
      • Se não tem papéis, retorna lista vazia.
    • Filtra retirando papéis de advogado.
    • Retorna lista de papéis "servidor".
  • ObterPapeisAdvogado:
    • Segue mesmo padrão de validação e busca do método anterior, porém filtra para listar apenas os papéis de advogado.
  • ObterLocalizacoesPapeisServidor:
    • Se o idCidadao é vazio, retorna erro.
    • Busca os papéis do cidadão via api do Acesso Cidadão.
      • Se não tem papéis, retorna lista vazia.
    • Busca os guids das localizações de todos os papéis (retirando duplicatas).
    • Busca os Locais (Orgaos e Unidades), que não são da OAB e estão presentes em guidsLocalizacao e guarda em retornoCarga.
    • Cria uma lista contendo todos os patriarcaId presentes em retornoCarga.
    • Verifica se os patriarcas contidos na lista são habilitados e salva numa tupla.
    • Extrai os patriarcasIds que estão habilitados.
    • Filtra em retorno para incluir apenas agentes com PatriarcaId habilitado (como OAB não está habilitado, é retirada da lista).
  • ObterGrupos:
    • Se o idCidadao é vazio, retorna erro.
    • Busca grupos via api do Acesso Cidadão.
      • Caso não tenha grupo, retorna lista vazia.
    • Converte cada grupo em AgenteDto, se estiver ok, adiciona à lista.
  • ObterGruposTrabalhoEComissao:
    • Se o idCidadao é vazio, retorna erro.
    • Busca grupos via api do Acesso Cidadão.
      • Caso não tenha grupo, retorna lista vazia.
    • Filtra os grupos por Comissão Siarhes, Grupo Trabalho e Grupo Trabalho Com Lider.
    • Converte cada grupo em AgenteDto, se estiver ok, adiciona à lista.
  • ObterConjuntosGestor:
    • Se o idCidadao é vazio, retorna erro.
    • Busca conjuntos via api do Acesso Cidadão.
      • Caso não tenha grupo, retorna lista vazia.
    • Busca os Locais (Orgaos e Unidades) que estão presentes em guidsLocalizacao e guarda em retornoCarga.
    • Cria uma lista contendo todos os patriarcaId presentes em retornoCarga.
    • Verifica se os patriarcas contidos na lista são habilitados e salva numa tupla.
    • Extrai os patriarcasIds que estão habilitados (como OAB não está habilitado, é retirada da lista).
    • Filtra em retorno para incluir apenas agentes com PatriarcaId habilitado.
  • ObterEmailsCidadao:
    • Valida se a lista de Guids está nula ou vazia, caso esteja, retorna erro.
    • Para cada Guid não vazio:
      • Busca e-mails via api Acesso Cidadão.
      • Monta EmailDto (pessoal + corporativo) e adiciona à lista.
    • Retorna lista de e-mails por cidadão.
  • LimparCachesUsuario:
    • Valida Guid, caso vazio, retorna erro.
    • Chama _cacheHelper.LimparCachesUsuario dentro de try/catch.
  • ObterPapeisServidorEmGrupo:
    • Verifica idCidadao e idGrupo, retorna erro caso algum esteja vazio.
    • Busca papéis do grupo via api do Acesso Cidadão.
      • Caso não tenha grupo, retorna lista vazia.
    • Extrai Guids dos papéis do grupo.
    • Busca papéis do usuário via _obterPapeis.
    • Filtra apenas os papéis de usuários que estão dentro do grupo e que não são advogados.
  • _obterPapeis (privado):
    • Busca papéis do cidadão no Acesso Cidadão, caso não tenha, retorna null.
    • Para cada papel, chama _agenteBuilder e adiciona à lista.
  • VerificacoesValidas (privado):
    • Busca lista de verificações via api Acesso Cidadão.
    • Filtra apenas verificações com Confiabilidade > 0.
    • Retorna lista dessas verificações.
  • IsContaVerificada:
    • Valida Guid.
    • Busca verificações do cidadão via api do Acesso Cidadão.
    • Busca lista de verificações válidas.
    • Percorre lista de ids de verificações do cidadão:
      • Caso algum id coincidir com as verificações válidas recebe verificado = true.
    • Retorna true ou false.