# 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.
