Fluxos de Integração ADMS × Atendimento

Projeto: DSB26201 · Assessment de Arquitetura de Integrações · Energisa Fontes: Wiki técnica da Energisa — "ADMS - Overview" (Canais Convencionais, 7 páginas, atualizado 17/06/2026 por Victor Teixeira Pinheiro) e "Abertura de Ocorrência Técnica pelo ADMS - Overview" (Canais Digitais, 3 páginas, atualizado 03/02/2026 por Lucas de Almeida Teixeira); transcrição consolidada de 3 sessões (15/07, 16/07 e 24/07/2026, pasta Reuniao-Atendimento); Ata 09 do Assessment Consolidado v1.12 Status: Rascunho para consolidação — substitui as referências indicativas do template do Capítulo 2 por dados de protocolo confirmados, e traz um addendum à Ata 09 (sessão de 24/07, ainda não incorporada)

Atualização (08/08/2026): os 6 diagramas de sequência que faltavam (Diagramas 4–9) e a seção "Achado novo — caminho duplo ADMS/RabbitMQ" foram incorporados a partir de dois documentos fornecidos diretamente pelo cliente — export em Mermaid da wiki técnica "ADMS - Overview" (8 fluxos completos) e da página "Abertura de Ocorrência Técnica pelo ADMS - Overview" (prosa detalhada do fluxo 1) — ambos mais detalhados que a leitura original desta wiki, usados aqui para completar o que antes só existia como linha de tabela. Elaborado por: Syntropy Labs

Por que este artefato existe

O template do Capítulo 2 do Assessment tinha, para protocolos e contratos de interface, principalmente campos "[a confirmar]". A wiki técnica interna da Energisa (devops.energisa.com.br) resolve isso: traz diagramas de sequência com nome exato de tópico Kafka, tabela, banco e microserviço para 8 fluxos de integração entre o ADMS/DMS e o ecossistema de atendimento. Este artefato consolida essa wiki, cruza com a Ata 09 já existente (sessões de 15 e 16/07) e fecha a lacuna da sessão de 24/07, que ainda não está em nenhuma ata.

Os 8 fluxos documentados na wiki

#	Fluxo	Serviços envolvidos	Acionamento
1	Abertura de Ocorrência Técnica	WSROT, MsAttOcorrenciaTecnica, MsCrmMiddleware	Síncrono (canal) + assíncrono (Kafka)
2	Encerramento de Comunicação	WSROT, MsAttOcorrenciaTecnica, MsCrmMiddleware	Síncrono + assíncrono
3	Geração de Comunicação	MsAttFiltroIncidentes, MsAttComunicacao	Contínuo (consumer Kafka)
4	Atualização de Clientes	MsAttMonitoraInstalacao, MsAttCliente, MsAttClienteCsv, MsAtualizaPotenciaCliente	CronJob 5min + diário 02h00
5	Desligamento Emergencial	MsAttFiltroIncidentes, MsAttDesligamentoEmergencial	Contínuo (consumer Kafka)
6	Desligamento Programado	MsAttDesligamentoProgramado	CronJob 2min
7	Flexible Load	MsAttClienteCsv	CronJob 5min
8	Load Profile (Curva de Carga)	MsAttClienteCsv	CronJob 5min

Diagrama 1 — Mapa estático de microsserviços

Ajuste (14/08/2026): o banco único "ATD / GIS / GRA (Oracle) + MongoDB" foi separado em dois componentes (oracle e mongo), e as relações de cada microsserviço foram revisadas linha a linha contra os Diagramas 2, 5, 6, 8 e 9 deste mesmo artefato — não apenas divididas mecanicamente. Isso corrigiu três omissões do mapa estático original: MsAttComunicacao não tinha nenhuma relação com banco, apesar de gravar em ATD (ver Diagrama 5); MsAttClienteCsv aparecia só consultando MongoDB, mas os Diagramas 8 e 9 mostram que ele também consulta ATD/GIS (Flexible Load) e ATD/GRA (Load Profile); e MsAtualizaPotenciaCliente aparecia só como consulta a GRA, quando o Diagrama 6 mostra que ele também grava de volta no MongoDB (BulkWrite de P/Q). MsAttCliente passou a mostrar as duas pontas — consulta Oracle, persiste Mongo — em vez de só a segunda.

Diagrama 2 — Sequência: Abertura de Ocorrência Técnica

Diagrama 3 — Sequência: Desligamento Programado (fechado em 24/07)

Diagrama 4 — Sequência: Encerramento de Comunicação (Ocorrência Técnica)

Serviços envolvidos: WSROT · MsAttOcorrenciaTecnica · MsCrmMiddleware Descrição: Espelha o fluxo de abertura (Diagrama 2), mas para o encerramento. O SIATT envia a requisição de encerramento ao WSROT, que publica em um tópico diferente (crm_callback_ocorrencia_tecnica, não crm_chamada_ocorrencia_tecnica) — o MsAttOcorrenciaTecnica atualiza a comunicação já existente no ATD e aciona o MsCrmMiddleware para encerrar o Trouble Ticket no ADMS. Diferença notável em relação à abertura: não há retorno síncrono nem tópico de retorno — o fluxo termina no envio ao ADMS.

Hipótese de correção de nome (02/09/2026, não confirmada explicitamente como o mesmo tópico): crm_callback_ocorrencia_tecnica (nome de origem na wiki técnica) não aparece no inventário real de produção — ver nota na tabela de referência abaixo. A equipe do CRM (Lucas) confirmou que crm_encerramento_ocorrencia_tecnica (nome real do inventário de produção) "é preenchido pelo WSROT [via] uma API chamada pelos canais (tanto os digitais quanto o SIATT) quando o cliente avisa que a energia retornou" — produtor (WSROT), consumidor real por consumer group (m-s-att-ocorrencia-tecnica = MsAttOcorrenciaTecnica, ver Proposta 2) e gatilho funcional batem exatamente com este diagrama. Leitura mais provável: é o mesmo tópico, só com nome diferente do que a wiki registrava — mas ninguém confirmou literalmente que os dois nomes são o mesmo tópico, então tratar como hipótese forte, não como fato fechado. Achado adicional: Lucas descreve o acionamento como vindo de "canais, tanto os digitais quanto o SIATT" — mais amplo do que o diagrama abaixo, que mostra só SIATT como ator (herdado da wiki original); não corrigido no diagrama até confirmar se o canal digital realmente aciona este fluxo pelo mesmo caminho.

Diagrama 5 — Sequência: Geração de Comunicação

Serviços envolvidos: MsAttFiltroIncidentes · MsAttComunicacao Descrição: O MsAttFiltroIncidentes consome os 7 tópicos wfm_ordem_servico_* do WFM/SIGOD. Dois caminhos distintos: os 5 tópicos de evento de OS (criado, despachado, encerrado, cancelado, arquivado) disparam consulta ao MongoDB para achar chamadas e UCs associadas antes de publicar; os 2 tópicos de chamada/UC direta (chamada, cliente_afetado) publicam sem consulta adicional. O MsAttComunicacao consome crm_comunicacao e decide, por um alt, entre gerar uma comunicação nova (6 inserções no ATD, incluindo consulta ao Trouble Ticket no ADMS) ou atualizar uma existente (3 operações).

Diagrama 6 — Sequência: Atualização de Clientes

Serviços envolvidos: MsAttMonitoraInstalacao · MsAttCliente · MsAttClienteCsv · MsAtualizaPotenciaCliente Descrição: O SEOPE processa OS comerciais e atualiza INSTALACAO no ATD. O MsAttMonitoraInstalacao (CronJob 5min) detecta instalações pendentes e publica no Kafka. O MsAttCliente consome, agrega dados de três bancos Oracle (ATD, GIS, GRA) e persiste em MongoDB (cliente_adms). O MsAttClienteCsv lê o Mongo e grava CSV no SFTP para o ADMS. Em paralelo, o MsAtualizaPotenciaCliente (CronJob diário às 02h00) recalcula os campos P e Q de todos os clientes, em lotes de 1000 registros por classificação de tensão (AT/BT/MT), a partir dos dados de consumo do mês anterior no banco GRA (InGrid).

Diagrama 7 — Sequência: Desligamento Emergencial

Serviços envolvidos: MsAttFiltroIncidentes · MsAttDesligamentoEmergencial Descrição: O MsAttFiltroIncidentes publica no tópico crm_clientes_afetados_desligamento_emergencial (ver Diagrama 5). O MsAttDesligamentoEmergencial consome e mantém a tabela DESLIGAMENTO_EMGCL_OCORC_TECNC no ATD: remove o registro quando o incidente é encerrado ou o atendimento está cancelado/encerrado, ou faz upsert com a situação quando o incidente está ativo.

Diagrama 8 — Sequência: Flexible Load

Serviços envolvidos: MsAttClienteCsv Descrição: O MsAttClienteCsv (CronJob 5min) gera diariamente o arquivo de cargas flexíveis (microgeração). Consulta UcGeradora no ATD e EoEnergySource no GIS, mescla os dados priorizando GIS, e grava o CSV no SFTP. Idempotente: ignora se o arquivo do dia já existir.

Diagrama 9 — Sequência: Load Profile (Curva de Carga)

Serviços envolvidos: MsAttClienteCsv Descrição: O MsAttClienteCsv (CronJob 5min) gera diariamente o arquivo de curvas de carga. Verifica o parâmetro de habilitação no ATD (CdParametrosGlobais), consulta LoadProfile no GRA (48 períodos de potência ativa e reativa), grava o CSV no SFTP e atualiza o parâmetro indicando a execução. Idempotente: ignora se o arquivo do dia já existir.

Addendum à Ata 09 — sessão de 24/07/2026 (13min, não incorporada)

A Ata 09 registra as sessões de 15 e 16/07 e fecha com uma pendência explícita: "o fluxo de desligamento programado não foi detalhado (...) as duas áreas acordaram apresentá-lo em conjunto em sessão posterior". A sessão de 24/07 é exatamente essa continuação, e ainda não está em nenhuma ata. Dois pontos saem dela:

Fechamento do fluxo de Desligamento Programado. Izabooh (atendimento convencional) confirmou o fluxo completo — ADMS deposita CSV no SFTP, o microserviço processa em CronJob de 2 minutos, persiste no Oracle e publica no Kafka — e que o único consumidor do tópico é o SAC Proativo, que fica inteiramente do lado de canais digitais (equipe do Lucas). Do lado do atendimento convencional, nada consome esse tópico.

Correção (02/09/2026, equipe do CRM/Lucas): "SAC Proativo" não é o consumidor técnico do tópico — é um conjunto de sistemas do time de canais digitais, não um serviço único. Quem de fato consome crm_clientes_afetados_desligamento_programado é o MSCCA, que lê esse e mais dois tópicos (crm_comunicacao, crm_clientes_afetados_desligamento_emergencial) e preenche uma collection própria no MongoDB do time para cada um — resolve a identificação de m-s-c-c-a, o consumidor recorrente não identificado nos três tópicos, já registrado em propostas-atendimento/proposta-2-outbox-oracle-aq.md. Achado adicional, não fechado: os avisos de desligamento programado que o SAC Proativo efetivamente envia ao cliente são gerados por outro serviço que nem usa Kafka — ou seja, o MSCCA alimenta o MongoDB do time, mas não é (ao menos não sozinho) quem dispara a notificação ao cliente. Esse outro serviço não foi nomeado nem investigado nesta troca.

Recomendação arquitetural nova, ainda não registrada em nenhuma ata. Castellani propôs uma regra prática para triagem de eventos: quando um evento é ponto-a-ponto entre dois componentes do mesmo domínio (um produtor, um consumidor, sem necessidade de múltiplos assinantes), ele não precisa estar no Kafka corporativo — pode usar um message broker mais barato e mais simples, como Oracle AQ ou TxEventQ (a interface Kafka-compatível do Oracle mais recente). Reservar o Kafka/Confluent para eventos que são, de fato, fatos de domínio com múltiplos consumidores entre domínios diferentes. Norberto confirmou que já vinha pensando na mesma direção. A conversa também tocou a discussão, já registrada na Ata 09 (item 1.10.5.6), sobre se a resposta para o crescimento do ambiente é adicionar Apache Flink ou primeiro racionalizar o que está desnecessariamente no Kafka — a sessão de 24/07 reforça a segunda leitura.

Achado de nomenclatura: "Sigode" vs. MsAttFiltroIncidentes

A Ata 09 atribui ao Sigode o papel de consolidar o estado da ocorrência e republicar em 7 tópicos por estado ("o Sigode mantém um tópico mais amplo de ordem de serviço... a partir dele, o próprio Sigode agrega e republica o conteúdo em tópicos específicos"). A wiki técnica, porém, atribui esse papel a um microserviço específico, o MsAttFiltroIncidentes, que consome os 7 tópicos wfm_ordem_servico_* — esses sim produzidos pelo WFM (produto SIGOD, domínio 4 do framework corporativo) — e republica para crm_comunicacao e crm_clientes_afetados_desligamento_emergencial.

A lista de 7 tópicos bate exatamente entre as duas fontes (criado, despachado, encerrado, cancelado, arquivado, chamada, afetado), então o conteúdo técnico está correto nas duas — a diferença é de atribuição: a ata trata "Sigode" como o agente que filtra e republica, quando pela wiki esse papel é do MsAttFiltroIncidentes, e Sigode/SIGOD é só o sistema de origem (WFM) dos 7 tópicos brutos. Pode ser apenas o jeito como as áreas se referem a isso informalmente em reunião — vale confirmar com Izabooh ou Lucas antes de corrigir a Ata 09.

Diagrama 10 — Sequência: bifurcação ADMS/RabbitMQ-MSGOT (achado novo, parâmetro global 70 do SIATT — R43)

A página "Abertura de Ocorrência Técnica pelo ADMS - Overview" (Canais Digitais) revela um mecanismo de transição que não aparece em nenhum outro artefato deste assessment: o roteamento da abertura de ocorrência técnica bifurca por distribuidora, não é um caminho único. Até esta revisão, esse achado só existia em prosa — nenhum artefato tinha o diagrama de sequência correspondente.

O WSROT decide o caminho consultando o parâmetro global 70 do SIATT: se a distribuidora já está usando o ADMS, a requisição segue para o Kafka (crm_chamada_ocorrencia_tecnica) e todo o fluxo descrito nos Diagramas 1 e 2 se aplica. Caso contrário — distribuidora ainda não migrada — o WSROT segue o fluxo antigo, publicando na fila ordemservico.tecnico.create.crm do RabbitMQ, consumida por um sistema chamado MSGOT, que não tem nenhuma menção em nenhum artefato, ata ou diagrama produzido até aqui neste assessment. Confirmado por Castellani em 12/08/2026: o modelo bifurca exatamente assim — distribuidoras migradas seguem por Kafka, as demais por RabbitMQ.

Isso muda a leitura de "o ADMS já processa a abertura de ocorrência técnica" (afirmação implícita nos Diagramas 1 e 2 e na síntese executiva) para "o ADMS processa a abertura de ocorrência técnica para as distribuidoras já migradas; as demais continuam num caminho legado (RabbitMQ/MSGOT) hoje sem visibilidade documental nenhuma no assessment". Dado que o G1 é justamente a onda de migração em curso (go-live 01/09), esse achado tem relação direta com o risco de topologia já registrado em R01 — mas é um risco distinto: não é sobre a WAN entre datacenters, é sobre não haver evidência de processo formal nem inventário de quais distribuidoras ainda dependem do caminho legado, nem de como (ou se) o MSGOT será decomissionado.

Lacuna a detalhar — comportamento interno do MSGOT. O que se sabe hoje se resume a "ele consome a fila ordemservico.tecnico.create.crm". Não há evidência de retry, dead-letter queue, garantia de ordenação, nem tratamento de falha/reprocessamento. Fica como pendência para uma sessão dedicada — sem isso, não dá para avaliar o risco real de perda de mensagem nesse caminho legado, nem propor um plano de decomissionamento com segurança.

Três pontos adicionais que a mesma fonte traz e vale registrar, mesmo sem virarem risco por si só:

• Endpoints deprecados (setembro/2025). Antes do ADMS entrar na EMS, o WSROT expunha 3 endpoints (Post, PostServicosTecnicos, PostServicosTecnicosNivelTensao); com a entrada do ADMS, só Post continua em uso — os outros dois ficaram obsoletos, e o próprio SIATT passou a consumir esse endpoint único.
• Collection MongoDB não documentada em nenhum outro artefato. O MsAttOcorrenciaTecnica atualiza uma collection OcorrenciaTecnica no MongoDB, além das tabelas Oracle já conhecidas — nenhum outro artefato deste assessment menciona essa collection.
• Tabelas Oracle completas. A lista exaustiva de tabelas gravadas pelo MsAttOcorrenciaTecnica é ATT_LIGACOES, ATT_INTERACAO, PROTOCOLO_ATENDIMENTO, ATT_COMENTARIOS, ATT_ATENDIMENTOS, COMUNICACOES — mais FAIXA_HORARIO_ATENDIMENTO e TERMO_ANUENCIA quando a ocorrência é de Nível de Tensão. O Diagrama 2 acima, herdado da wiki original, usava reticências (...) nesse ponto — corrigido aqui para a lista completa.

Ver 080-diagnostico/matriz-riscos-consolidada.md (R43) e 080-diagnostico/matriz-achados-lacunas.md (D3) para o registro formal deste achado.

Tabela de referência — tópicos Kafka principais

Coluna de schema adicionada em 05/08/2026, a partir do inventário real de produção do Confluent (topicos_detalhado_latest.md) — ver evidencias-producao-confluent-kafka.md. "Sem Schema" significa que o tópico não está registrado no Schema Registry no inventário de 09/07/2026.

Correção (29/08/2026): ao validar a Proposta 2 (Oracle AQ) contra os consumer groups reais da extração de 25/08/2026, crm_comunicacao e crm_clientes_afetados_desligamento_emergencial — documentados abaixo como 1:1 (um produtor, um consumidor) — na verdade têm 2 e 3 consumer groups ativos em produção, respectivamente. Este mapeamento reflete o que foi levantado para o fluxo original, não uma consulta a consumer groups — os dois consumidores adicionais (m-s-c-c-a e, no segundo caso, também m-s-c-o-m-f-e-c-l-i) não estavam documentados em nenhum artefato deste assessment. Ver a seção "Validação (29/08/2026)" da Proposta 2 para o detalhamento completo.

Identificação (02/09/2026, equipe do CRM/Lucas): m-s-c-c-a é o MSCCA — serviço do time de canais digitais que consolida os três tópicos (desligamento programado, desligamento emergencial, comunicação) em collections próprias no MongoDB do time; m-s-c-o-m-f-e-c-l-i é o MSCOMFECLI — gera os avisos de desligamento emergencial ao cliente via SAC Proativo. Nenhum dos dois pertence ao domínio de Atendimento (MsAtt*) — são serviços de canais digitais consumindo tópicos publicados por serviços de Atendimento, cruzando fronteira de domínio. Ver correção também na seção "Addendum à Ata 09" acima (Desligamento Programado) e na Proposta 2.

Tópico	Produtor	Consumidor	Schema (inventário real, 09/07)
wfm_ordem_servico_criado/despachado/encerrado/cancelado/arquivado/chamada/cliente_afetado (7 tópicos)	WFM/ADMS (SIGOD)	MsAttFiltroIncidentes	Sem Schema (domínio WFM: 0/40 tópicos com schema no inventário geral)
crm_comunicacao	MsAttFiltroIncidentes	MsAttComunicacao	Sem Schema
crm_clientes_afetados_desligamento_emergencial	MsAttFiltroIncidentes	MsAttDesligamentoEmergencial	Sem Schema
crm_clientes_afetados_desligamento_programado	MsAttDesligamentoProgramado	MSCCA (não "SAC Proativo" — corrigido em 02/09/2026, ver nota acima)	Sem Schema
crm_atualizacao_cliente_adms	MsAttMonitoraInstalacao	MsAttCliente	Sem Schema
crm_chamada_ocorrencia_tecnica	WSROT	MsAttOcorrenciaTecnica	Sem Schema — payload real inspecionado contém CPF e telefone em texto puro (ver R42 proposto em matriz-riscos-consolidada.md)
crm_callback_ocorrencia_tecnica	WSROT	MsAttOcorrenciaTecnica	Não localizado no inventário de 09/07/2026 entre os 14 tópicos do domínio CRM. Hipótese forte, não confirmada (02/09/2026): é o mesmo tópico que crm_encerramento_ocorrencia_tecnica no inventário real de produção — produtor (WSROT) e consumidor (MsAttOcorrenciaTecnica) confirmados pela equipe do CRM batem com este, mas ninguém confirmou literalmente que os dois nomes são o mesmo tópico. Ver nota no Diagrama 4 acima
crm_encerramento_ocorrencia_tecnica	WSROT (confirmado 02/09/2026, equipe do CRM)	MsAttOcorrenciaTecnica (via consumer group real m-s-att-ocorrencia-tecnica, ver Proposta 2)	Sem Schema — nome real do inventário de produção; ver hipótese de correspondência com crm_callback_ocorrencia_tecnica acima
crm_registra_ocorrencia_sistema_tecnico	MsAttOcorrenciaTecnica	MsCrmMiddleware	Sem Schema
crm_retorno_ocorrencia_sistema_tecnico	MsCrmMiddleware	MsAttOcorrenciaTecnica	Sem Schema

Próximo passo

Consolidar este artefato em dois lugares: (1) Ata 09, como um item 1.10.24 (addendum da sessão de 24/07), incluindo a recomendação de racionalização de broker e a ressalva sobre a nomenclatura Sigode/MsAttFiltroIncidentes; (2) Capítulo 2 do Assessment Consolidado, substituindo os campos "[a confirmar]" do template por estes tópicos, tabelas e serviços confirmados. Vale também levar a recomendação de broker por domínio (Oracle AQ/TxEventQ) para o Capítulo 6 (Recomendações e Roadmap), quando esse capítulo for iniciado. Adicionalmente, a coluna de schema agora presente na tabela de tópicos reforça a recomendação de Schema Registry obrigatório (Ata 09) com evidência concreta: nenhum dos 8 tópicos deste fluxo tem schema hoje, e um deles carrega dado pessoal em texto puro.