docs: registra incidentes de producao Z-PRO (endpoint MCP, horario passado, investigacao midia)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/n8n-agendamento-runbook.md

@@ -18,7 +18,12 @@
 > cobre os workflows de exemplo de AI Agent para **agendamento** desses
 > mesmos três providers (fechando a lacuna que só a confirmação tinha
 > preenchido) — ver o inventário geral de todos os workflows de exemplo
-> (agendamento + confirmação, nos 4 providers) no final da seção 22.
+> (agendamento + confirmação, nos 4 providers) no final da seção 22. A
+> seção 23 registra três bugs reais encontrados em produção no Z-PRO
+> depois que o gestor da clínica editou o AI Agent pela UI (endpoint MCP
+> revertido pro servidor errado, agendamento em horário já passado) e o
+> estado da investigação sobre suporte a imagem/áudio (ainda sem
+> solução — depende do painel admin do Z-PRO).
 
 ## 1. Node MCP: qual usar e como instalar
 
@@ -1005,3 +1010,104 @@ apontando pro respectivo MCP Server nativo já construído. Nenhum foi
 ativado nem testado com chamada HTTP real — cada um fica pronto pra
 duplicar assim que a clínica real correspondente e o banco Postgres do
 cliente existirem.
+
+## 23. Incidentes reais em produção (Z-PRO, 17/08/2026) — edição manual pela UI
+
+Depois que o gestor da clínica exemplo editou o node `AI Agent` e o
+`OpenAI Chat Model` diretamente pela UI do n8n (troca de modelo), o
+agendamento em produção (`Agendamento - GChat - Z-PRO (clínica
+exemplo)`, `yG2mi6ECBpPv4Hmn`) parou de funcionar. Três problemas reais
+foram encontrados e corrigidos, nesta ordem:
+
+### 23.1. `endpointUrl` do MCP Client Tool revertido pro servidor errado
+
+**Sintoma**: toda mensagem caía no branch de erro padrão ("Desculpe,
+tive um problema técnico..."). Execução mostrava
+`"error": "Error in sub-node MCP - ZPRO (nativo n8n)"` /
+`"Could not connect to your MCP server"`.
+
+**Causa raiz**: o node `MCP - ZPRO (nativo n8n)` (o único `MCP Client
+Tool` conectado ao AI Agent deste workflow) apontava pro endpoint de
+**teste** do MCP de Mensageria
+(`https://devn8n.gtigrupo.com.br/mcp-test/mcp-server-mensageria-zpro`)
+em vez do MCP de **agendamento** de produção
+(`https://devn8n.gtigrupo.com.br/mcp/mcp-server-zpro-clinica-exemplo`,
+servidor `MCP Server - ZPRO` / `qjSaKllvneBIZ7mC`, tools `agendar` +
+`consultar_horarios`). Confirmado via execução `248` (12/08, um dia
+antes) que o agendamento real só funciona com esse endpoint correto —
+o node havia sido apontado pro MCP errado (mensageria, não
+agendamento) durante uma edição manual, e a correção foi **revertida
+duas vezes** só de reabrir/salvar o node do modelo pela UI (o editor
+recarrega o valor antigo em cache do campo `endpointUrl` e resalva o
+workflow inteiro).
+
+**Fix**: `endpointUrl` corrigido pra
+`https://devn8n.gtigrupo.com.br/mcp/mcp-server-zpro-clinica-exemplo`.
+**Risco de recorrência real** — documentado como aviso pro
+gestor: qualquer edição futura do `AI Agent`/`OpenAI Chat Model` pela
+UI deve conferir esse campo antes de salvar.
+
+### 23.2. Modelo trocado para `gpt-5.6-luna`
+
+O gestor trocou o modelo do `OpenAI Chat Model` de `gpt-4.1-mini` para
+`gpt-5.6-luna` (veio do dropdown de modelos da credencial "GPT",
+`cachedResultName` igual ao `value` — não foi digitado à mão). Mantido
+a pedido do usuário; não identificado como causa de nenhum dos bugs
+desta seção (o erro de conexão MCP acontece antes de qualquer chamada
+ao modelo).
+
+### 23.3. Agendamento aceito em horário já passado
+
+**Sintoma**: paciente pediu "17/08 as 8:30" às 11:48 (mesmo dia) e o
+agente agendou sem objeção, mesmo com o horário já tendo passado.
+
+**Causa raiz**: nem o `systemMessage` do `AI Agent` nem o doc de
+prompt da clínica (Google Docs) tinham qualquer regra comparando o
+horário pedido com o horário atual — só validavam dia da semana e
+horário comercial (seção 3 do doc). O `systemMessage` calculava
+`$now` só com **data**, sem hora, então o modelo não tinha como
+comparar.
+
+**Fix**: `systemMessage` do `AI Agent` alterado para incluir data
+**e hora** atuais (`yyyy-MM-dd (cccc) HH:mm`) e nova regra 8: nunca
+agendar num horário já passado — comparar com o horário atual antes de
+confirmar/agendar, e pedir outro horário se o pedido já passou.
+Também revisado o doc de prompt da clínica (`docId`
+`1NmYRIoF7yD_B6N160_6Bpfv4NyJiryTTO2LFr9xNlYY`, Google Docs) pra
+remover a exigência de "consultar disponibilidade antes de agendar"
+(o Z-PRO não oferece essa consulta — nunca ofereceu, mesmo nos
+agendamentos que funcionaram — então a regra original só confundia o
+modelo sem nunca ter sido cumprível).
+
+### 23.4. Investigação em aberto — suporte a imagem/áudio (sem solução ainda)
+
+Pedido do usuário: fazer o AI Agent entender imagens e áudios enviados
+pelo paciente no WhatsApp. Testado enviando uma imagem e um áudio reais
+pro número de produção:
+
+- **Confirmado por teste direto**: o webhook `Webhook Z-PRO` recebe
+  ambos exatamente como uma mensagem de texto vazia —
+  `{"step":"process","entrada":"","number":...,"contactName":...,"protocol":...}`
+  — sem nenhum campo de mídia, URL, base64 ou tipo de mensagem.
+- **Descartado como evidência**: uma mensagem encontrada num ticket
+  antigo ("No momento, consigo processar apenas mensagens em texto...")
+  **não é** um aviso de sistema do Z-PRO — vem do chatFlow nativo
+  `id 78`, nomeado **"GUSTAVO"**, criado em 14/07/2026 dentro do próprio
+  painel de chatbot do Z-PRO. É texto escrito manualmente por alguém da
+  equipe num flow separado, não evidência da API.
+- A collection pública do Postman do Z-PRO
+  (`postman.com/comunidade-zdg/z-pro/collection/ksvu6vu`) documenta só
+  a API de saída (enviar mensagem, criar ticket, `appointment/*`,
+  etc.) — não tem nenhum endpoint de webhook de entrada nem de busca
+  de mídia recebida.
+- Pista não seguida: o objeto de ticket retornado por
+  `showticketchatbot` tem campos `n8nStatus`/`n8nUrl` (hoje `false`/
+  `null` no ticket testado), sugerindo que o Z-PRO tem alguma
+  configuração de integração com n8n por ticket/canal cujas opções não
+  foram investigadas.
+
+**Pendência real**: confirmar no painel administrativo do Z-PRO (quem
+tem acesso) se a configuração do webhook usado por este workflow
+(`agendamento-zpro-clinica-exemplo`) tem alguma opção pra incluir mídia
+no payload. Sem isso, a feature de entender imagem/áudio não é
+implementável só editando o workflow do n8n.