224 lines
14 KiB
Markdown
224 lines
14 KiB
Markdown
# Matriz de Migração — Contas -> agent_framework_oci
|
||
|
||
| Capacidade | Destino novo | Reuso framework | Código de domínio novo | Dependência anterior |
|
||
|---|---|---:|---:|---:|
|
||
| LangGraph | `app/workflows/agent_graph.py` | Sim | composição mínima | Não |
|
||
| Router | EnterpriseRouter | Sim | routing.yaml | Não |
|
||
| Stickiness | framework | Sim | configuração | Não |
|
||
| Supervisor | framework | Sim | configuração | Não |
|
||
| Confirmação | AgentRuntimeMixin | Sim | tool policy | Não |
|
||
| Clarificação | AgentRuntimeMixin/MCP mapping | Sim | schemas/mapping | Não |
|
||
| Sessions | framework repository | Sim | Não | Não |
|
||
| Message memory | framework | Sim | Não | Não |
|
||
| Summary memory | framework | Sim | Não | Não |
|
||
| LTM | framework | Sim | Não | Não |
|
||
| Checkpoint | framework | Sim | Não | Não |
|
||
| RAG | RagService | Sim | conteúdo/config | Não |
|
||
| Guardrails | GuardrailPipeline | Sim | config | Não |
|
||
| Output Supervisor | framework | Sim | Não | Não |
|
||
| Judges | JudgePipeline | Sim | config | Não |
|
||
| MCP router | framework | Sim | tool catalog | Não |
|
||
| Faturas | MCP/domain | Não aplicável | Sim | Não |
|
||
| Billing Analysis | MCP/domain | Não aplicável | Sim | Não |
|
||
| Consulta/Histórico VAS | MCP/domain | Não aplicável | Sim | Não |
|
||
| Bloqueio/Cancelamento VAS | MCP/domain | confirmação no framework | Sim | Não |
|
||
| Contestação | MCP/domain | confirmação/estado no framework | Sim | Não |
|
||
| Protocol/Status/Tracking | MCP/domain | contexto no framework | Sim | Não |
|
||
| SMS | MCP/domain | contexto no framework | Sim | Não |
|
||
| Secure PDF | MCP/domain | contexto no framework | Sim | Não |
|
||
| Langfuse | framework | Sim | Não | Não |
|
||
| Pub/Sub/sequence | framework | Sim | configuração | Não |
|
||
| OCI Streaming | framework | Sim | configuração | Não |
|
||
| OTEL | framework | Sim | configuração | Não |
|
||
|
||
## Regra
|
||
|
||
O pacote anterior não é uma biblioteca do novo projeto. Se uma regra específica for necessária, ela deve ser portada e testada dentro de `app/domain/contas`; infraestrutura genérica deve ser eliminada em favor do framework.
|
||
|
||
|
||
## Contratos TIM validados por regressão
|
||
|
||
| Integração | Paridade coberta | Estado |
|
||
|---|---|---|
|
||
| CompleteInvoices | método/payload/header `ClientID` | ✅ |
|
||
| Query VAS | URL por MSISDN, `clientId=AIAAGENTCR`, auth | ✅ |
|
||
| VAS History | query `msisdn`, `clientId`, `messageId`, auth | ✅ |
|
||
| Block VAS | payload PMid + fallbacks e headers | ✅ |
|
||
| Cancel VAS | DELETE, channel, protocol, headers, messageId | ✅ |
|
||
| Contract Information | GET por MSISDN, `clientId`, auth | ✅ |
|
||
| Profile/Line Info | GET e header `ClientID` | ✅ |
|
||
| Billing Analysis | GET por MSISDN + channel | ✅ |
|
||
| Bill PDF | POST detalhado + criptografia | ✅ |
|
||
| Secure PDF | GET com parâmetros criptografados | ✅ |
|
||
| Customer Contestation | payload/headers principais | ✅ |
|
||
| Service Request Status | envelope `serviceRequest` | ✅ |
|
||
| Tracking Activities | customer/invoice/activity/user | ✅ |
|
||
| Protocol V2 | envelope Siebel + headers corporativos | ✅ |
|
||
| SMS Barcode | payload completo + retry/RCT | ✅ |
|
||
|
||
## Jornadas compostas e comportamento conversacional
|
||
|
||
| Capacidade original | Implementação migrada | Reuso do framework | Regressão |
|
||
|---|---|---:|---:|
|
||
| Cancelamento VAS -> contestação | dois workflows encadeados no MCP | `WorkflowRuntime` | ✅ |
|
||
| Composição final cancelamento | `app/domain/contas/vas_cancellation_message.py` | domínio determinístico | ✅ 19 casos originais |
|
||
| Fallback VAS History | `ContasDomainService.cancelar_vas_avulso` | transporte via adapter | ✅ |
|
||
| Cancelamento parcial em lote | action expõe cancelados/falhas/candidatos | WorkflowRuntime + IdempotencyStore | ✅ |
|
||
| Idempotência transacional | `create_idempotency_store()` | framework | ✅ |
|
||
| Replay pós-finalização | Channel short-circuit | framework | ✅ |
|
||
| Idle nudge replay | Channel short-circuit | framework | ✅ |
|
||
| Processing interruption | replay + classificador LLM fail-safe | `LLMProvider` framework | ✅ |
|
||
| Correção Fim/Mim -> Sim | channel transcription | framework | ✅ |
|
||
| Finalização status/summary | regra pura de domínio | workflow framework | ✅ |
|
||
| Protocolo informacional final | action + ProtocolV2 | WorkflowRuntime | ✅ |
|
||
|
||
### Bootstrap MCP
|
||
|
||
`WorkflowRuntime`, checkpointer e `IdempotencyStore` são inicializados de forma lazy. Isto evita dependência de Oracle/Redis para endpoints de diagnóstico e garante que o backend durável só seja aberto quando um workflow realmente precisar ser executado.
|
||
|
||
## Incrementos de paridade - baseline 420
|
||
|
||
| Capacidade original | Implementação migrada | Responsabilidade | Estado |
|
||
|---|---|---|---:|
|
||
| InvoiceContextProvider / prefetch | `InvoiceContextService` + `agent_framework.cache.Cache` | domínio escolhe evidências; framework fornece cache | ✅ |
|
||
| Isolamento de invoice context por sessão | chave `session_id:msisdn:invoice_id` | framework cache | ✅ |
|
||
| Plano família titular/dependente | normalização antes do workflow + contestação única no titular | domínio + WorkflowRuntime | ✅ |
|
||
| Correção de linha por invoice detail | normalização determinística | domínio | ✅ |
|
||
| CVAL fail-stop | edge `success=false -> END` | WorkflowRuntime | ✅ |
|
||
| Snapshot parcial em falha | `WorkflowRuntime` recupera último state do LangGraph | framework | ✅ |
|
||
| Retry Billing Analysis / RCT 079-084 | metadata `_transport` + `RCTPolicy` | domínio define códigos; observer publica | ✅ |
|
||
| Finalização invoice explanation | protocolo informacional somente após workflow executado | domínio + WorkflowRuntime | ✅ |
|
||
| VEB fechado / force RT15 | reuso ou novo protocolo conforme flags | domínio | ✅ |
|
||
| Inicialização AgentWorkflow | router/agentes/grafo dentro de `__init__` | aplicação/framework | ✅ |
|
||
|
||
### Incrementos de paridade — baseline 435
|
||
|
||
| Capacidade original | Implementação migrada | Responsabilidade | Status |
|
||
|---|---|---|---|
|
||
| Invoice prefetch single-flight | `InvoiceContextService` + `agent_framework.cache.Cache` | domínio escolhe evidências; framework fornece cache | ✅ |
|
||
| CVN de prefetch sem duplicação | `business_events` + cache markers | domínio define código; observer framework publica | ✅ |
|
||
| Latch invoice/workflow já executado | `AgentRuntimeMixin.business_workflows_executed` | framework | ✅ |
|
||
| Batch cancellation max 5 | action async + semaphore | domínio action sobre WorkflowRuntime | ✅ |
|
||
| Protocolo por linha antes de cancelar | action `cancelamento_vas_avulso_batch` | domínio + adapter TIM | ✅ |
|
||
| Erro estruturado de workflow | `WorkflowRunResult.error_details` | framework | ✅ |
|
||
| Provider error de contestação | MCP mapping sobre `error_details` | domínio/MCP fino | ✅ |
|
||
|
||
|
||
## Baseline 440 testes - continuação
|
||
|
||
- 440 testes de migração passando; 2 skipped por dependências indisponíveis neste runtime (`langgraph`/`jellyfish`).
|
||
- Cancelamento VAS: falha de bloqueio/cancelamento pode permanecer candidata à contestação sem mascarar sucesso.
|
||
- Resposta composta preserva protocolos de cancelamento por linha + protocolo de contestação e sinaliza finalização sugerida.
|
||
- Plano família: protocolo de cancelamento em dependente resolve `socialSecNo` via LineInfo da própria linha.
|
||
- Registro de protocolo aceita aliases de resposta `interactionProtocol`, `protocolNumber`, `protocol` e `protocolo`.
|
||
- Finalização informacional recalcula Bundle/Estratégico/Avulso pela evidência de `invoice_detail`/Billing Analysis quando disponível.
|
||
|
||
## Finalização - paridade adicional (baseline 533)
|
||
|
||
| Capability original | Implementação migrada | Framework reutilizado | Evidência |
|
||
|---|---|---|---|
|
||
| CVN aceite/recusa no encerramento | `finalizar_atendimento_action` | `business_events` + `AgentObserver` | testes de finalização estendida |
|
||
| Protocolo RT-15 informacional | action de domínio + TIM client | WorkflowRuntime/observer/idempotência | RCT.085/086 + CVN.010/011 |
|
||
| Nota de invoice explanation | valor canônico `Explicação dos valores da fatura` | workflow latch do framework | regressão |
|
||
| Handoff/retention suppression | flags no state/domain action | estado persistido do framework | regressão |
|
||
| SAD decision tree | `SAD.001/002/003/004/005/006/007` como business events | AgentObserver | regressão |
|
||
| Classificação VAS sem invoice detail | aliases determinísticos de domínio | nenhuma engine paralela | regressão |
|
||
| Regressão offline de workflow | `WorkflowRuntime(... allow_deterministic_fallback=True)` somente em teste | DSL/actions do framework | 18 casos históricos executados |
|
||
|
||
## Atualização de paridade - baseline 550
|
||
|
||
| Capability | Original | Migrado | Evidência |
|
||
|---|---|---|---|
|
||
| Finalização com prefetch de fatura | CVN lookup + RT-15 quando aplicável | Implementado | regressão de finalização |
|
||
| Supressão após transição para negócio | não reemite CVN/MPI | Implementado | regressão dedicada |
|
||
| VEB terminal | não duplica RT-15/CVN | Implementado | regressão dedicada |
|
||
| Precedência de tipo pela fatura | total/parcial/sem match | Implementado | regressão dedicada |
|
||
| Protocolo já existente | não duplica RT-15 | Implementado | regressão dedicada |
|
||
| Matcher fonético/transcrição | catálogo real | Implementado sem xfails | suíte de transcrição |
|
||
|
||
## VAA — rastreabilidade de cancelamento/contestação
|
||
|
||
| Capability histórica | Implementação migrada | Framework reutilizado | Estado |
|
||
|---|---|---|---|
|
||
| VAA.001–004 cancelamento | `cancelamento_vas_avulso_batch` retorna `business_events` | AgentObserver / analytics | OK |
|
||
| VAA.005–009 contestação/boleto | `abrir_contestacao_cliente` retorna `business_events` | AgentObserver / analytics | OK |
|
||
| VAA.012–015 SMS | `enviar_sms` retorna `business_events` e mantém fluxo em erro | AgentObserver / analytics | OK |
|
||
| VAA.016–017 status SR | `atualizar_status_sr` retorna `business_events` | AgentObserver / analytics | OK |
|
||
|
||
|
||
## Baseline 560 testes - metadata corporativa TIM
|
||
|
||
- 560 testes de migração passando, sem skips/xfails.
|
||
- Business events preservam contexto corporativo: `agentProtocolId`, `adjustedProtocol`, `billingId`, `uraCallId`, `channelId`, `sessionId`, `messageId` e `agentSpecificData`.
|
||
- Contestação VAA.005-009 preserva itens/valores ajustados e protocolo.
|
||
- Finalização CVN.010/011 preserva protocolo TIM/URA e billing context.
|
||
- RCTs derivados de retry HTTP carregam `apiUrl`, `apiStatusCode`, `apiResponsePayload` e `latencyMs`.
|
||
- SMS e Service Request Status carregam metadata de transporte e contexto de protocolo.
|
||
- `tim_payload_mapper` aceita o formato histórico `agentSpecificData` JSON-string e o converte para o objeto canônico TIM no payload final.
|
||
|
||
### Paridade de eventos conversacionais — baseline 565
|
||
|
||
| Família | Paridade adicionada |
|
||
|---|---|
|
||
| VEB | ordem dos branches de VAS estratégico e metadata do turno/URA |
|
||
| MPI | contexto de invoice explanation, pró-rata e cancelamento |
|
||
| CVN | contexto conversacional/protocolo no encerramento |
|
||
| SAD | `llmResponse`, `messageId`, sessão/canal e `sessionEndAt` normalizado |
|
||
|
||
## Incremento de paridade — baseline 570
|
||
|
||
| Funcionalidade original | Implementação migrada | Responsabilidade |
|
||
|---|---|---|
|
||
| Cancelamento solicitado para item estratégico/bundle | `InvoiceResolver` redireciona para workflow `vas_estrategico` | Domínio + WorkflowRuntime |
|
||
| Invoice explanation SIM | recomenda `resolvido` pelo último node do workflow | MCP adapter fino sobre WorkflowRuntime |
|
||
| Invoice explanation NÃO sem VAS variado | recomenda `nao_resolvido` | MCP adapter fino sobre WorkflowRuntime |
|
||
| Pró-rata aceito / sem Plano Controle | recomenda `resolvido` | MCP adapter fino sobre WorkflowRuntime |
|
||
| Orientação de cancelamento de VAS estratégico por parceiro | action declara `requires_rag/rag_queries`; `AgentRuntimeMixin` chama `RagService` | Framework |
|
||
| Gate padrão de regressão | `pytest -q` -> `tests/` | Projeto migrado |
|
||
|
||
## Baseline 578 - wrapper cancelamento + LLM composition
|
||
|
||
- 593 testes passando; zero skipped/xfail.
|
||
- Cancelamento preserva `auto_finalize_on_failure` em falha técnica de contestação.
|
||
- Item já contestado não mascara cancelamento concluído como falha sistêmica.
|
||
- `cancelamento_vas_protocol` e todos os protocolos de resposta são preservados.
|
||
- Plano família contesta titular + dependentes em uma única `contestacao_tool`.
|
||
- Lote com muitos no-match continua contestando exatamente os candidatos elegíveis.
|
||
- Pró-rata usa `requires_llm_composition` do framework em vez de gateway LLM de domínio.
|
||
|
||
|
||
### Paridade de wrappers históricos — baseline 593
|
||
|
||
| Comportamento original | Implementação migrada | Estado |
|
||
|---|---|---|
|
||
| `tipo_atendimento=contestacao` | `_workflow_payload(contestacao_tool)` | ✅ |
|
||
| Contexto do turno no workflow | payload MCP preserva IDs/canal/mensagem | ✅ |
|
||
| CPF como alias de socialSecNo | normalização no wrapper composto | ✅ |
|
||
| `cancelados` sem `results.success` | fallback agregado do wrapper | ✅ |
|
||
| `itens_para_contestacao` | alias de `contestation_candidates` | ✅ |
|
||
| falha block/cancel ainda elegível a RT-02 | composição de dois WorkflowRuntime | ✅ |
|
||
| SMS falha sem derrubar jornada | `sms_not_send_error` | ✅ |
|
||
| Bundle + Estratégico + NÃO | protocolo deferido + RAG obrigatório | ✅ |
|
||
|
||
## Complemento de paridade — baseline 599
|
||
|
||
| Comportamento histórico | Implementação migrada | Prova |
|
||
|---|---|---|
|
||
| Itens já contestados | normalização em `abrir_contestacao_cliente` + compositor determinístico | teste de wrapper 1:1 |
|
||
| Itens contestados/não contestados | classificação na action de domínio | regressão de contestação |
|
||
| Total contestado somente dos itens aceitos | cálculo determinístico no domínio | regressão de contestação |
|
||
| Contestação retorna valor zero | fallback para total efetivamente cancelado | teste de wrapper 1:1 |
|
||
| Valor na fala em pt-BR | normalização na borda MCP | teste `R$ 14,99` |
|
||
| `next_subject` | ignorado pelo compositor determinístico | teste de wrapper 1:1 |
|
||
| Billing Analysis indisponível | fraseologia canônica e `auto_finalize_on_failure=false` | regressão invoice explanation |
|
||
|
||
### Cobertura 1:1 de wrappers — baseline 615
|
||
|
||
Além dos testes de domínio/actions/workflows, a suíte passa a reproduzir diretamente
|
||
outcomes históricos dos wrappers `cancelar_vas_single` e `finalize_support`, cobrindo
|
||
no-match, candidatos explícitos, falhas parciais RT-01→RT-02, SMS, protocolos,
|
||
`protocol_closed`, plano família/titular-dependente e protocolo informacional deferido.
|
||
|
||
Esses testes são classificados como **paridade explícita de contrato externo**, e não
|
||
apenas cobertura indireta por actions internas.
|