agent_contas/docs/LEGACY_INTEGRATION_PARITY_20260822.md

Paridade de Integração Contas — Mock x Sistemas Reais

Data: 2026-08-22

Objetivo

Validar o agente Contas migrado contra o código original, usando o legado como fonte de verdade para contratos HTTP, autenticação, headers, payloads, URLs, timeouts e comportamento de integração. O objetivo é manter o funcionamento com mocks locais sem impedir a execução contra sistemas reais quando TIM_GATEWAY_MODE/TIM_USE_MOCK_GATEWAY forem configurados para modo real.

Correção crítica — identidade do item transacional

Foi corrigido o caso em que um pedido explícito para TIM CTRL Redes Sociais 8.0 podia ser reinterpretado pelo matcher fuzzy como TIM Fashion Mensal.

Causa

O InvoiceResolver eliminava seções não transacionáveis (por exemplo, planos) antes da resolução de identidade e, em seguida, aplicava similaridade somente sobre VAS. Como TIM Fashion Mensal ultrapassava o threshold do matcher, o subject era substituído antes da execução.

Correção

• A resolução exata de identidade agora acontece antes de qualquer fuzzy matching.
• A busca exata considera também itens fora do escopo transacional, como planos.
• Um plano encontrado exatamente é classificado como out_of_scope para a operação VAS.
• O fuzzy matching continua restrito aos candidatos realmente tratáveis.
• resolve_items() preserva o comportamento anterior onde necessário para compatibilidade; o fluxo operacional usa a proteção de identidade.

Resultado esperado para o caso:

TIM CTRL Redes Sociais 8.0 -> exact match -> plano -> out_of_scope -> não substituir por outro VAS -> não executar cancelamento.

Comparação com o código original

Foram comparados os comandos do projeto original (agente_contas_tim/commands), factory.py, config.py e o gateway HTTP com o adaptador atual app/domain/contas/client.py.

Serviço/Integração	Contrato encontrado no original	Situação no migrado após revisão
Consulta VAS	GET, URL com {msisdn} ou append /msisdn, normalização para prefixo 55, clientId	Corrigido: aliases originais, timeout, append e prefixo 55
Histórico VAS	GET com ?msisdn=, clientId/messageId/auth	Corrigido default clientId=AIAGENTCR
Bloqueio VAS	POST, contratos de payload pmid/input/vasBlock, headers extras	Corrigidos aliases de URL/auth/timeout/clientId/operation/payload/encoding
Cancelamento VAS	DELETE, body com channel/msisdn/appId/cspId/interactionProtocol, OAM/CN/type opcionais	Corrigidos aliases TIM_CANCELLATION_* e TIM_CANCELAMENTO_*
Divergência / explicação de fatura	GET <base>/<msisdn>?channel=AIAGENTCR, Basic opcional user/password, clientID	Corrigidos aliases, Basic auth e timeout
CompleteInvoices	POST {"msisdn": ...}, ClientID=AIAGENTCR	Compatível; timeout respeitado
Profile bill	Factory original usa configuração de CompleteInvoices	Corrigido para priorizar contrato/config de CompleteInvoices
Profile full	GET com placeholder ou append /msisdn, ClientID=AIAGENTCR	Corrigido append e timeout
Line info	Mesmo padrão de URL do profile full	Corrigido append e timeout
Contrato	GET <base>/<msisdn>, clientId do legado	Corrigido default AIAGENTCR
Protocolo V2	POST serviceRequest/interaction, headers opcionais OAM/CN/type	Mantido no adaptador atual
Contestação do cliente	POST, clientId/messageId/X-Agent-Id, user configurável	Corrigido default via TIM_CUSTOMER_CONTESTATION_USER_ID
Atualização de Service Request	POST, channel/serviceRequest, headers de integração	Mantido
Tracking Activities	POST com customer/protocol/invoice/activity/user	Mantido
SMS	POST com msisdn/sender/message/URL e receipt opcional	Mantido
Bill PDF detalhada	POST com invoiceId/customerId e invoiceType DETALHADA, retorno PDF	Aliases ampliados
Secure PDF / invoice recover	GET com invoiceId/msisdn/customerId	Aliases/header ajustados

Configurações presentes no legado sem uso operacional comprovado

• status_customer: configuração encontrada, mas sem comando/runtime consumidor localizado na revisão.
• configuração OAuth específica de SMS: declarada no config original, mas sem consumidor runtime localizado.

Esses itens não foram tratados como requisito ativo sem evidência de uso no código original.

Mock x modo real

O mock continua suportado. Em mock, o cliente retorna fixtures locais para as operações previstas. Em modo real, o mesmo adaptador segue os contratos HTTP reconstruídos a partir do código original.

A principal diferença de risco é que um mock tende a responder 200/OK para cenários preparados. Por isso, a validação de identidade deve ocorrer antes do gateway — como agora ocorre — para impedir que um erro de resolução de entidade seja mascarado pelo mock e, principalmente, que chegue a um backend real.

Testes executados

Regressão + contratos existentes

• 101 testes passaram no conjunto de contratos, paridade, idempotência e resolução.

Novos testes de compatibilidade legado/real

• 7 testes passaram cobrindo:
  • prefixo 55 e composição da URL de consulta VAS;
  • aliases originais e timeout;
  • aliases de cancelamento;
  • append de MSISDN em profile full;
  • Basic auth de divergência via usuário/senha;
  • client IDs de histórico VAS e contrato;
  • uso de CompleteInvoices no profile bill.

Suite tests/migration

Resultado observado após as mudanças:

• 660 passed
• 4 failed

As quatro falhas remanescentes são de configuração/contexto de guardrails (conversation_history e FRASEOLOGIA) e não estão relacionadas ao InvoiceResolver nem aos contratos de integração revisados.

Limite desta validação

A revisão comprova paridade de contrato em nível de código-fonte e testes locais. Ela não é uma certificação de conectividade real porque não foram usados endpoints, credenciais ou rede dos sistemas legados neste ambiente.

Para homologação real, recomenda-se executar testes de contrato contra um ambiente não produtivo dos serviços TIM, verificando status HTTP, schemas reais, autenticação, timeouts, headers obrigatórios e respostas de erro.

Gaps de endurecimento recomendados

1. Adicionar validação de readiness no startup quando mock=false, falhando cedo se endpoint/auth obrigatórios estiverem ausentes.
2. Criar testes de contrato contra ambiente de homologação para cada integração ativa.
3. Comparar periodicamente fixtures mock com schemas/respostas reais para evitar drift.
4. Manter invariantes transacionais: item solicitado, item resolvido e item executado nunca podem divergir silenciosamente.
5. Evoluir mascaramento/observabilidade do cliente migrado para o mesmo nível do HttpGateway original, sem registrar secrets.