📝 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
-uvicorn app.main:app --reload
-
-# Terminal 2: Rodar testes
-bash test-local.sh http://localhost:8000
+# Terminal 1
+uvicorn app.main:app --reload --log-level debug
 ```

-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?",
-    "user_id": "user-123"
+    "message": "SUA_MENSAGEM_AQUI",
+    "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
-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"
-  }'
-```
+## Grupo 1. Sanidade Basica

-**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
-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"
-  }'
-```
+### 1.2. Consulta operacional simples de estoque

-**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
-curl -X POST http://localhost:8000/chat \
-  -H "Content-Type: application/json" \
-  -d '{
-    "message": "Qual e o carro mais caro que voces tem?",
-    "user_id": "user-123"
-  }'
-```
+Passos:
+1. Envie: `Quero comprar um carro de 45000 reais, meu CPF e 12345678900`

-**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
-curl -X POST http://localhost:8000/chat \
-  -H "Content-Type: application/json" \
-  -d '{
-    "message": "Meu CPF é 12345678900. Posso financiar um carro de 45000 reais?",
-    "user_id": "user-123"
-  }'
-```
+Passos:
+1. Envie: `Quero fazer um pedido`
+2. Responda com um CPF invalido, por exemplo: `123`
+3. Responda com CPF valido: `12345678900`
+4. Responda com valor: `45000`

-**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
-curl -X POST http://localhost:8000/chat \
-  -H "Content-Type: application/json" \
-  -d '{
-    "message": "Tenho um Toyota Corolla 2015 com 120000 km para dar de entrada. Quanto vale?",
-    "user_id": "user-123"
-  }'
-```
+Esperado:
+- o sistema pede numero e motivo de forma incremental;
+- ao informar so um deles, pede apenas o outro;
+- conclui o cancelamento ao final.

-**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
-curl -X POST http://localhost:8000/chat \
-  -H "Content-Type: application/json" \
-  -d '{
-    "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:
+- revisao agendada;
+- retorno com protocolo, data/hora e valor da revisao;
+- sem pedir dados adicionais.

-**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
-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"
-  }'
-```
+### 3.3. Listagem de revisoes

-**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
- [ ] Consultar estoque retorna veículos
- [ ] Validar cliente retorna aprovação/rejeição
- [ ] Avaliar veículo retorna valor estimado
- [ ] 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
+Passos:
+1. Envie: `Quero remarcar minha revisao`
+2. Responda com protocolo: `REV-20260310-ABCD1234`
+3. Responda com nova data: `11/03/2026 as 14:30`

-## 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
-# Terminal com logs
-uvicorn app.main:app --reload --log-level debug
-```
+### 4.1. Agendamento em horario ocupado com sugestao

-### Testar Mockaroo direto
+Pre-condicao:
+- deve existir um agendamento ativo no horario escolhido.

-```bash
-curl -X POST http://localhost:8000/mock/consultar-estoque \
-  -H "Content-Type: application/json" \
-  -d '{"preco_max": 50000}'
-```
+Passos:
+1. Com um `user_id` qualquer, agende uma revisao em `10/03/2026 as 09:00`
+2. Com outro `user_id`, envie uma nova solicitacao para o mesmo horario

-```bash
-curl -X POST http://localhost:8000/mock/consultar-estoque \
-  -H "Content-Type: application/json" \
-  -d '{"ordenar_preco": "asc", "limite": 1}'
-```
+Esperado:
+- o sistema informa que o horario esta ocupado;
+- oferece um proximo horario sugerido;
+- a mensagem e objetiva e reaproveitavel pelo fluxo.

-```bash
-curl -X POST http://localhost:8000/mock/consultar-estoque \
-  -H "Content-Type: application/json" \
-  -d '{"ordenar_preco": "desc", "limite": 1}'
+### 4.2. Confirmacao da sugestao
+
+Pre-condicao:
+- 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.