Runbook de homologação¶
Homologar é executar um roteiro controlado em um ambiente conhecido e comparar a evidência com o contrato esperado. Esta página é um procedimento a executar pelo responsável; não registra aprovação de ambiente real e não implica execução de mensagens, escrita em providers ou deploy nesta tarefa.
Preparação do registro¶
Registre ambiente, conta/região, stack, commit implantado, configuração relevante sem secrets, janela do teste, responsáveis e critério de encerramento. Use identificadores fictícios para a conversa e destinatários de teste autorizados; teste@example.invalid e <CPF_FICTICIO> são placeholders documentais e não devem ser enviados a validadores como se fossem cadastro válido.
Combine previamente os números controlados, o cadastro de teste aceito pelo eGestor e os objetos [TESTE] no CRM. Planeje como localizar e limpar cada objeto. O smoke eGestor possui dados fixos no código e a CLI não aceita trocar seu documento.
Roteiro e critérios¶
| Etapa | Execução | Evidência de aprovação |
|---|---|---|
| 1. Ambiente | Conferir identidade AWS, Environment, região, stack e outputs |
Destino corresponde ao registro; nenhuma URL/configuração de outro ambiente |
| 2. Parâmetros | Revisar flags, modelos, URL CRM, pipeline, cinco stages, SSM e whitelist | Configuração efetiva coerente; etapas terminais distintas das ativas |
| 3. Preflight | Health HTTP e smokes sem efeitos com permissões explicitamente falsas | Health 200; cada check classificado; skipped registrado como não executado |
| 4. WhatsApp | Verificação GET, envio inbound do número controlado e resposta | Assinatura aceita, receipt, SQS e outbound correlacionados; duplicata não reenviada |
| 5. Agentes | Serviço no catálogo, coleta, confirmação, pedido de humano e saída de portfólio | Estado/action/dados coerentes e resposta apropriada; sem inventar serviço/preço |
| 6. CRM | Primeiro resultado confirmado, enriquecimento e encerramento | Projeção converge ao stage esperado, IDs vinculados e sem negócio duplicado |
| 7. eGestor | Smoke autorizado ou confirmação com cadastro de teste conhecido | Busca valida identidade e upsert retorna ID correto; não modifica outro cliente |
| 8. Handoff | Pedir humano com operador disponível e sem operador disponível | Notificação ou fila, motivo e resumo preservados |
| 9. Painel | entrar, login, assumir, colaboração, enviar e finalizar |
Cookie/CSRF, histórico, silêncio do bot em HUMAN, fila e CLOSED coerentes |
| 10. Logs | Conferir erros, filas, métricas CRM e avisos | Sem falhas ocultas; nenhum dado sensível anexado ao relatório |
| 11. Rollback/cleanup | Reconciliar efeitos e objetos criados | IDs tratados pelo responsável, sessão encerrada e pendências conhecidas |
Comandos para preparar e observar¶
Antes dos testes reais, validar regressões locais:
python -m pytest tests/unit tests/integration/test_fixture_replay.py -q
sam validate --lint --region sa-east-1
Consulta operacional sem alteração de dados:
aws cloudformation describe-stacks --region sa-east-1 --stack-name gogenetic-agent-staging --query 'Stacks[0].{Status:StackStatus,Outputs:Outputs}'
aws logs tail /aws/lambda/gogenetic-agent-orchestrator-staging --region sa-east-1 --since 30m
python scripts/diagnose_crm_sync.py --table gogenetic-agent-staging --region sa-east-1
Esses comandos de observação acessam a conta real selecionada. O último não consulta o CRM remoto por conta própria; veja observabilidade para comparação com snapshot.
Casos que precisam de atenção específica¶
Mensagens rápidas: envie duas mensagens de teste em sequência durante uma chamada do agente. A resposta superada deve ser descartada pelo mecanismo vigente; não conclua que a primeira entrada foi perdida apenas porque ela não gerou outbound isolado. Investigue receipts, IDs do provider e SQS.
Handoff sem operador: marque indisponibilidade e solicite humano pelo cliente controlado. A sessão deve continuar HANDOFF_PENDING; handoff_queued é uma condição operacional válida. Depois envie entrar: o operador recebe um link e o total da fila, sem um disparo extra por cada cliente já aguardando.
Colaboração: entre com dois operadores autorizados. O primeiro fica em assigned_to; o segundo continua autorizado a ajudar. Dois envios simultâneos devem respeitar o lock e uma finalização durante envio deve ser bloqueada.
CRM após finalizar: a conversa sai da lista antes da confirmação remota. Verifique /atendimento/crm até a convergência ou classificação explícita do erro. UNCERTAIN não autoriza novo POST de negócio.
Janela de atendimento: mensagem de texto humano requer inbound com menos de 24 horas. Um teste de janela fechada deve verificar bloqueio local sem tentar contornar com template pago; o SAM fixa WhatsAppFreeOnly=true.
Limpeza e reversão¶
Finalize as conversas de teste pelo painel. CRM/eGestor exigem tratamento específico dos IDs retornados; o runner não fornece cleanup automático. Confirme que o registro é exclusivamente do teste antes de remover ou atualizar qualquer objeto externo.
scripts/reset_sessions.ps1 faz dry-run por padrão e lista todas as sessões nos estados selecionados, com telefones em claro:
.\scripts\reset_sessions.ps1 -Environment staging -Region sa-east-1
O default seleciona HANDOFF_PENDING e HUMAN; -Execute fecha em massa e -AllNonTerminal amplia a seleção. Não use esse mecanismo para limpar apenas uma conversa numa tabela compartilhada. Ele escreve diretamente no DynamoDB, não percorre o serviço humano nem reconcilia automaticamente a projeção CRM; um reset não equivale a sincronização de encerramento. Para rollback de código/infra, siga deploy.
Resultado final da rodada¶
Para cada cenário, registre passou, falhou, bloqueado ou não executado, com motivo, estado observado e referências técnicas sanitizadas. Separe “testes locais passaram”, “preflight respondeu”, “envio entregue” e “dados confirmados no provider”. Aprovação comercial, operacional e jurídica deve ser dada pelos respectivos responsáveis; não pode ser deduzida de um exit code 0 de smoke.