bugfix: search engine
This commit is contained in:
T3782834
104
docs/LEGACY_INTEGRATION_PARITY_20260822.md
Normal file
104
docs/LEGACY_INTEGRATION_PARITY_20260822.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user