📝 docs(test): reestruturar cenarios manuais para fluxos multiassunto

- reorganiza os testes por objetivos de validacao do orquestrador - adiciona roteiros para fila de pedidos, troca de contexto, controle de conversa e conflitos de revisao - amplia cobertura manual para parsing de datas, protocolos e regressao de memoria curta
1 month ago · e21fc69926
parent 57dc824242
commit e21fc69926
1 changed files with 452 additions and 128 deletions
--- a/TEST_CASES.md
+++ b/TEST_CASES.md
@ -1,194 +1,518 @@
 # Test Cases para o Orquestrador
-## Testes Manuais
+Este documento foi reorganizado para validar a etapa atual do projeto: orquestracao conversacional multiassunto, fila de pedidos, troca de contexto, fluxo de revisao e novas tools de controle da conversa.
 ## Como Executar
 ### Setup
 ```bash
-# Terminal 1: Iniciar servidor
+# Terminal 1
-uvicorn app.main:app --reload
+uvicorn app.main:app --reload --log-level debug
 # Terminal 2: Rodar testes
 bash test-local.sh http://localhost:8000
 ```
-Ou com Docker Compose:
+Opcional com Docker:
 ```bash
 docker-compose up
 bash test-local.sh http://localhost:8000
 ```
-## Casos de Teste
+### Endpoint principal
-### 1. Chat Simples (Sem Tool)
+Todos os cenarios abaixo usam:
 ```bash
 curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
-    "message": "Olá, como você funciona?",
+    "message": "SUA_MENSAGEM_AQUI",
-    "user_id": "user-123"
+    "user_id": "qa-user-001"
  }'
 ```
-**Esperado**: Resposta direta do modelo, sem chamada de tool
+Observacoes:
 - Reaproveite o mesmo `user_id` dentro de cada cenario multi-turno.
 - Troque o `user_id` entre cenarios para evitar contaminacao de contexto.
 - Quando precisar inspecionar handlers diretamente, use os endpoints em `/mock/*`.
---
+## Convencoes de Validacao
-### 2. Consultar Estoque
+Em cada cenario, valide:
 - se a resposta faz sentido para o turno atual;
 - se houve continuidade ou limpeza correta do contexto;
 - se o sistema nao pediu dados que ja tinham sido informados;
 - se nao houve erro 500;
 - se o comportamento bate com a fila, memoria e fluxo esperados.
-```bash
+## Grupo 1. Sanidade Basica
 curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quero um carro de até 50000 reais",
    "user_id": "user-123"
  }'
 ```
-**Esperado**: Modelo chama `consultar_estoque` com `preco_max=50000`
+### 1.1. Conversa geral sem tool
---
+Passos:
 1. Envie: `Ola, como voce funciona?`
-### 2.1. Consultar Carro Mais Barato
+Esperado:
 - resposta textual simples;
 - sem comportamento operacional;
 - sem pedir dados de revisao ou pedido.
-```bash
+### 1.2. Consulta operacional simples de estoque
 curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual e o carro mais barato que voces tem?",
    "user_id": "user-123"
  }'
 ```
-**Esperado**: Modelo chama `consultar_estoque` com `ordenar_preco=asc` e `limite=1`
+Passos:
 1. Envie: `Quero ver carros ate 50000 reais`
---
+Esperado:
 - consulta de estoque;
 - resposta coerente com lista ou resumo de veiculos;
 - sem abrir fluxo incremental desnecessario.
-### 2.2. Consultar Carro Mais Caro
+### 1.3. Criacao simples de pedido
-```bash
+Passos:
-curl -X POST http://localhost:8000/chat \
+1. Envie: `Quero comprar um carro de 45000 reais, meu CPF e 12345678900`
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual e o carro mais caro que voces tem?",
    "user_id": "user-123"
  }'
 ```
-**Esperado**: Modelo chama `consultar_estoque` com `ordenar_preco=desc` e `limite=1`
+Esperado:
 - validacao do cliente;
 - criacao de pedido quando aprovado;
 - retorno com numero do pedido ou mensagem objetiva de restricao.
---
+## Grupo 2. Slot Filling de Pedido
-### 3. Validar Cliente Venda
+### 2.1. Pedido com dados faltantes
-```bash
+Passos:
-curl -X POST http://localhost:8000/chat \
+1. Envie: `Quero fazer um pedido`
-  -H "Content-Type: application/json" \
+2. Responda com um CPF invalido, por exemplo: `123`
-  -d '{
+3. Responda com CPF valido: `12345678900`
-    "message": "Meu CPF é 12345678900. Posso financiar um carro de 45000 reais?",
+4. Responda com valor: `45000`
    "user_id": "user-123"
  }'
 ```
-**Esperado**: Modelo chama `validar_cliente_venda`
+Esperado:
 - o sistema pede apenas os campos faltantes;
 - CPF invalido gera orientacao objetiva;
 - depois de receber os dados corretos, conclui o pedido;
 - nao reinicia o fluxo do zero a cada turno.
---
+### 2.2. Cancelamento de pedido com dados faltantes
-### 4. Avaliar Veículo para Troca
+Passos:
 1. Envie: `Quero cancelar um pedido`
 2. Responda com apenas o numero: `PED-202600001`
 3. Responda com o motivo: `desisti da compra`
-```bash
+Esperado:
-curl -X POST http://localhost:8000/chat \
+- o sistema pede numero e motivo de forma incremental;
-  -H "Content-Type: application/json" \
+- ao informar so um deles, pede apenas o outro;
-  -d '{
+- conclui o cancelamento ao final.
    "message": "Tenho um Toyota Corolla 2015 com 120000 km para dar de entrada. Quanto vale?",
    "user_id": "user-123"
  }'
 ```
-**Esperado**: Modelo chama `avaliar_veiculo_troca`
+## Grupo 3. Fluxo de Revisao
---
+### 3.1. Agendamento completo em uma mensagem
-### 5. Agendar Revisão
+Passos:
 1. Envie: `Quero agendar revisao para o carro ABC1234 em 10/03/2026 as 09:00, modelo Corolla, ano 2020, 30000 km, ja fiz revisao na concessionaria`
-```bash
+Esperado:
-curl -X POST http://localhost:8000/chat \
+- revisao agendada;
-  -H "Content-Type: application/json" \
+- retorno com protocolo, data/hora e valor da revisao;
-  -d '{
+- sem pedir dados adicionais.
    "message": "Quero agendar uma revisão para meu carro com placa ABC1234 no dia 25 de fevereiro às 10 da manhã",
    "user_id": "user-123"
  }'
 ```
-**Esperado**: Modelo chama `agendar_revisao`
+### 3.2. Agendamento incremental
---
+Passos:
 1. Envie: `Quero agendar uma revisao`
 2. Responda: `placa ABC1234`
 3. Responda: `Corolla 2020`
 4. Responda: `30000 km`
 5. Responda: `sim, ja fiz revisao na concessionaria`
 6. Responda: `10/03/2026 as 09:00`
-### 6. Cancelar Pedido
+Esperado:
 - o sistema coleta os dados em varias mensagens;
 - pede apenas os campos faltantes;
 - ao final, agenda sem perder o contexto acumulado.
-```bash
+### 3.3. Listagem de revisoes
 curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Gostaria de cancelar meu pedido número 12345 porque mudei de ideia",
    "user_id": "user-123"
  }'
 ```
-**Esperado**: Modelo chama `cancelar_pedido`
+Passos:
 1. Depois de existir ao menos um agendamento para o mesmo `user_id`, envie: `Liste minhas revisoes`
---
+Esperado:
 - resposta com os agendamentos do usuario;
 - sem pedir dados desnecessarios.
-## Swagger UI
+### 3.4. Cancelamento de revisao com protocolo explicito
-Acesse: http://localhost:8000/docs
+Passos:
 1. Use um protocolo existente, por exemplo `REV-20260310-ABCD1234`
 2. Envie: `Cancelar a revisao do protocolo REV-20260310-ABCD1234 porque nao vou poder ir`
-Todos os endpoints estão documentados lá para testar interativamente.
+Esperado:
 - cancelamento executado;
 - resposta com protocolo e status cancelado;
 - motivo aproveitado corretamente.
-## Checklist de Testes
+### 3.5. Remarcacao de revisao com dados faltantes
- [ ] Chat simples sem tool funciona
+Passos:
- [ ] Consultar estoque retorna veículos
+1. Envie: `Quero remarcar minha revisao`
- [ ] Validar cliente retorna aprovação/rejeição
+2. Responda com protocolo: `REV-20260310-ABCD1234`
- [ ] Avaliar veículo retorna valor estimado
+3. Responda com nova data: `11/03/2026 as 14:30`
 - [ ] Agendar revisão retorna agendamento
 - [ ] Cancelar pedido retorna cancelamento
 - [ ] Modelo é assertivo (chama tools quando apropriado)
 - [ ] Modelo não chama tools desnecessariamente
 - [ ] Respostas são formatadas corretamente
 - [ ] Sem erros 500 na API
-## Debugging
+Esperado:
 - o sistema pede protocolo e nova data se faltarem;
 - aceita o protocolo em formato completo;
 - conclui a remarcacao quando ambos forem informados.
-### Ver logs detalhados
+## Grupo 4. Conflito de Agenda em Revisao
-```bash
+### 4.1. Agendamento em horario ocupado com sugestao
 # Terminal com logs
 uvicorn app.main:app --reload --log-level debug
 ```
-### Testar Mockaroo direto
+Pre-condicao:
 - deve existir um agendamento ativo no horario escolhido.
-```bash
+Passos:
-curl -X POST http://localhost:8000/mock/consultar-estoque \
+1. Com um `user_id` qualquer, agende uma revisao em `10/03/2026 as 09:00`
-  -H "Content-Type: application/json" \
+2. Com outro `user_id`, envie uma nova solicitacao para o mesmo horario
  -d '{"preco_max": 50000}'
 ```
-```bash
+Esperado:
-curl -X POST http://localhost:8000/mock/consultar-estoque \
+- o sistema informa que o horario esta ocupado;
-  -H "Content-Type: application/json" \
+- oferece um proximo horario sugerido;
-  -d '{"ordenar_preco": "asc", "limite": 1}'
+- a mensagem e objetiva e reaproveitavel pelo fluxo.
 ```
-```bash
+### 4.2. Confirmacao da sugestao
-curl -X POST http://localhost:8000/mock/consultar-estoque \
+
-  -H "Content-Type: application/json" \
+Pre-condicao:
-  -d '{"ordenar_preco": "desc", "limite": 1}'
+- executar o cenario 4.1 imediatamente antes.
 Passos:
 1. Depois da mensagem de conflito com sugestao, envie: `pode ser`
 Esperado:
 - o sistema usa o horario sugerido sem pedir todos os dados novamente;
 - a revisao e criada com sucesso;
 - o contexto de confirmacao pendente e limpo depois.
 ## Grupo 5. Parsing de Datas e Protocolo
 ### 5.1. Datas absolutas aceitas
 Teste separadamente estas mensagens:
 - `Quero agendar revisao em 10/03/2026 as 09:00`
 - `Quero agendar revisao em 10/03/2026 09:00`
 - `Quero agendar revisao em 2026-03-10 09:00`
 - `Quero agendar revisao em 2026-03-10T09:00:00-03:00`
 Esperado:
 - os formatos sao reconhecidos;
 - o sistema nao reclama de `data_hora invalida` por causa do formato.
 ### 5.2. Datas relativas com horario
 Passos:
 1. Envie: `Quero agendar revisao amanha as 09:00 para a placa ABC1234, Corolla 2020, 30000 km, sim`
 Esperado:
 - o sistema converte a data relativa para uma data absoluta;
 - segue o fluxo normalmente.
 ### 5.3. Protocolo com pontuacao ao redor
 Passos:
 1. Envie algo como: `Pode cancelar o protocolo (REV-20260310-ABCD1234), por favor`
 Esperado:
 - o protocolo e extraido mesmo com parenteses ou pontuacao;
 - nao pede protocolo novamente se ele ja estiver claro.
 ### 5.4. Protocolo invalido
 Passos:
 1. Envie: `Cancelar revisao do protocolo REV-XYZ`
 Esperado:
 - o sistema nao aceita um protocolo malformado como valido;
 - pede a informacao correta ou informa que faltou protocolo valido.
 ## Grupo 6. Multiassunto e Fila de Pedidos
 ### 6.1. Duas intencoes operacionais na mesma mensagem
 Passos:
 1. Envie: `Quero agendar revisao para o ABC1234 amanha as 09:00 e tambem comprar um carro de 45000, meu CPF e 12345678900`
 Esperado:
 - o sistema identifica duas acoes;
 - responde pedindo para escolher qual iniciar primeiro;
 - nao executa as duas de uma vez.
 ### 6.2. Escolha explicita da primeira opcao
 Pre-condicao:
 - executar o cenario 6.1 imediatamente antes.
 Passos:
 1. Envie: `1`
 Esperado:
 - o sistema inicia a primeira opcao;
 - a segunda fica pendente em fila;
 - ao terminar o fluxo atual, avisa que existe proximo pedido na fila.
 ### 6.3. Escolha explicita da segunda opcao
 Pre-condicao:
 - repetir o cenario 6.1 com novo `user_id`.
 Passos:
 1. Envie: `2`
 Esperado:
 - o sistema inicia a segunda opcao;
 - a primeira fica na fila para depois.
 ### 6.4. Escolha por indiferenca
 Pre-condicao:
 - repetir o cenario 6.1 com novo `user_id`.
 Passos:
 1. Envie: `tanto faz`
 Esperado:
 - o sistema escolhe uma das opcoes;
 - deixa claro qual foi escolhida;
 - a outra permanece enfileirada.
 ### 6.5. Continuar proximo pedido
 Pre-condicao:
 - existir pelo menos um pedido pendente em fila.
 Passos:
 1. Envie: `continuar`
 Esperado:
 - o sistema abre o proximo pedido da fila;
 - faz a transicao de contexto corretamente;
 - usa a nova tool de orquestracao para isso, quando aplicavel.
 ### 6.6. Continuar sem fila
 Passos:
 1. Com um `user_id` limpo, envie: `continuar`
 Esperado:
 - resposta informando que nao ha pedidos pendentes;
 - sem erro.
 ## Grupo 7. Controle de Contexto
 ### 7.1. Cancelar apenas o fluxo atual
 Pre-condicao:
 - iniciar um fluxo incompleto de revisao ou pedido.
 Passos:
 1. Envie: `cancelar esse fluxo`
 Esperado:
 - o fluxo atual e encerrado;
 - a conversa nao e zerada por completo;
 - se houver fila pendente, ela nao deve ser apagada indevidamente.
 ### 7.2. Descartar apenas fila pendente
 Pre-condicao:
 - existir pedido em fila.
 Passos:
 1. Envie: `pode descartar os pedidos pendentes`
 Esperado:
 - a fila e limpa;
 - o contexto atual nao e resetado integralmente;
 - a resposta informa quantos pedidos foram descartados.
 ### 7.3. Limpar contexto completo
 Pre-condicao:
 - existir contexto ativo, fila ou rascunhos.
 Passos:
 1. Envie: `esquece tudo, vamos comecar de novo`
 Esperado:
 - contexto da conversa limpo;
 - fila removida;
 - fluxos pendentes removidos;
 - proxima mensagem deve ser tratada como novo atendimento.
 ### 7.4. Reset durante escolha entre duas acoes
 Pre-condicao:
 - executar o cenario 6.1 e parar na pergunta de escolha.
 Passos:
 1. Envie: `esquece tudo agora`
 Esperado:
 - o `pending_order_selection` e limpo;
 - o contexto ativo e limpo;
 - o sistema pede um novo assunto ou recomeça sem residuos.
 ### 7.5. Novo pedido operacional enquanto ha escolha pendente
 Pre-condicao:
 - executar o cenario 6.1 e parar na pergunta de escolha.
 Passos:
 1. Envie uma nova demanda operacional completa, por exemplo: `Na verdade quero apenas cancelar meu pedido PED-202600001 porque desisti`
 Esperado:
 - o sistema nao fica preso na escolha anterior;
 - a nova solicitacao pode assumir prioridade;
 - o comportamento deve ser coerente e sem mistura de contextos.
 ## Grupo 8. Troca de Dominio
 ### 8.1. Troca de revisao para vendas com fluxo em aberto
 Passos:
 1. Inicie um agendamento de revisao sem concluir
 2. Antes de terminar, envie: `Agora quero comprar um carro`
 Esperado:
 - o sistema detecta mudanca de dominio;
 - deve haver comportamento claro de confirmacao, troca ou preservacao do fluxo atual;
 - nao mistura campos de revisao com pedido.
 ### 8.2. Troca de vendas para revisao com fila
 Passos:
 1. Inicie um pedido de compra
 2. Durante a conversa, envie tambem uma solicitacao de revisao
 Esperado:
 - um fluxo segue ativo;
 - o outro pode ir para fila;
 - a resposta deixa claro o que ficou para depois.
 ## Grupo 9. Reuso de Pacote de Revisao
 ### 9.1. Reagendamento novo com reuso de dados anteriores
 Pre-condicao:
 - concluir um agendamento de revisao com sucesso no mesmo `user_id`.
 Passos:
 1. Envie: `Quero marcar outra revisao parecida`
 2. Se o sistema perguntar se pode reaproveitar os dados anteriores, responda: `sim`
 3. Informe apenas nova data/hora
 Esperado:
 - o sistema reaproveita placa, modelo, ano, km e historico quando apropriado;
 - pede apenas a nova data/hora;
 - cria novo agendamento corretamente.
 ### 9.2. Rejeitar reuso de pacote
 Pre-condicao:
 - executar o inicio do cenario 9.1.
 Passos:
 1. Quando o sistema oferecer reaproveitamento, responda: `nao`
 Esperado:
 - o pacote anterior nao e reutilizado;
 - o sistema volta a coletar os dados normalmente.
 ## Grupo 10. Casos Negativos e Regressao
 ### 10.1. Nao chamar tool desnecessariamente
 Passos:
 1. Envie: `Obrigado`
 2. Envie: `Pode me explicar melhor como voces funcionam?`
 Esperado:
 - respostas gerais;
 - sem entrar em fluxo operacional.
 ### 10.2. Nao perder dados ja coletados
 Passos:
 1. Inicie revisao com alguns dados
 2. Responda a um campo faltante
 3. Verifique se o sistema nao pede novamente os campos anteriores
 Esperado:
 - continuidade real do rascunho;
 - sem regressao de memoria curta.
 ### 10.3. Sem erro 500 em fluxos interrompidos
 Passos:
 1. Inicie qualquer fluxo
 2. Cancele o fluxo atual
 3. Limpe contexto
 4. Peça para continuar
 Esperado:
 - respostas coerentes em todas as etapas;
 - sem excecao interna exposta ao usuario.
 ## Checklist Resumido
 - [ ] Conversa geral sem tool
 - [ ] Consulta simples de estoque
 - [ ] Pedido com slot filling
 - [ ] Cancelamento de pedido com slot filling
 - [ ] Agendamento completo de revisao
 - [ ] Agendamento incremental de revisao
 - [ ] Listagem de revisoes
 - [ ] Cancelamento de revisao
 - [ ] Remarcacao de revisao
 - [ ] Conflito de agenda com sugestao
 - [ ] Confirmacao de sugestao de horario
 - [ ] Parsing de multiplos formatos de data
 - [ ] Extracao de protocolo com pontuacao
 - [ ] Deteccao de protocolo invalido
 - [ ] Escolha entre duas acoes na mesma mensagem
 - [ ] Continuar proximo pedido da fila
 - [ ] Continuar sem fila
 - [ ] Cancelar apenas fluxo atual
 - [ ] Descartar apenas fila pendente
 - [ ] Limpar contexto completo
 - [ ] Reset durante escolha pendente
 - [ ] Troca de dominio sem contaminacao
 - [ ] Reuso de pacote de revisao
 - [ ] Sem erro 500 nos fluxos interrompidos
 ## Apoio de Debug
 ### Swagger UI
 Acesse:
 ```text
 http://localhost:8000/docs
 ```
-### Ver resposta do Vertex AI
+### Endpoints mock uteis
 - `POST /mock/agendar-revisao`
 - `POST /mock/listar-agendamentos-revisao`
 - `POST /mock/cancelar-agendamento-revisao`
 - `POST /mock/editar-data-revisao`
 - `POST /mock/realizar-pedido`
 - `POST /mock/cancelar-pedido`
 ### O que observar nos logs
-Adicione console.log nos handlers para ver o que o Vertex retorna.
+Com `--log-level debug`, acompanhe:
 - extracao estruturada do LLM;
 - roteamento de pedidos;
 - troca de dominio;
 - criacao e consumo da fila;
 - conflitos de revisao e sugestao de horario;
 - limpeza de contexto e expiracao de estados pendentes.