105 lines
6.7 KiB
Markdown
105 lines
6.7 KiB
Markdown
# 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.
|