From a56bf09c8870d1113ec7d44747792559a531e279 Mon Sep 17 00:00:00 2001 From: Gustavo Date: Tue, 11 Aug 2026 08:59:19 -0300 Subject: [PATCH] docs: atualiza runbook com os 4 providers (Z-PRO, Klingo, SysLife, ClinicAll) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Renomeia o título e a intro para refletir que o runbook agora cobre os 4 providers, não só o Z-PRO. Adiciona seção 14 consolidando Klingo, SysLife e ClinicAll (IDs de workflow, diferenças de autenticação, pendências reais de cada um) e uma subseção de padrão comum aos quatro. Renomeia "Status final" para "Status final - Z-PRO" para deixar claro o escopo. Co-Authored-By: Claude Sonnet 5 --- docs/n8n-agendamento-runbook.md | 73 +++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 8 deletions(-) diff --git a/docs/n8n-agendamento-runbook.md b/docs/n8n-agendamento-runbook.md index bf1bba0..c668027 100644 --- a/docs/n8n-agendamento-runbook.md +++ b/docs/n8n-agendamento-runbook.md @@ -1,11 +1,15 @@ -# Runbook — Workflow de Agendamento no n8n (GChat/Z-PRO + gti-scheduling-mcp) +# Runbook — Workflow de Agendamento no n8n (Z-PRO, Klingo, SysLife, ClinicAll) -> Registra problemas reais encontrados ao montar o workflow -> `Agendamento - GChat - Z-PRO (clínica exemplo)` (id `yG2mi6ECBpPv4Hmn`, servidor -> `srvdevn8ngti` / `devn8n.gtigrupo.com.br`), e como foram resolvidos — para não -> repetir o mesmo processo de descoberta ao duplicar este workflow para uma nova -> clínica. Ver também `docs/superpowers/specs/2026-08-10-n8n-agendamento-workflow-design.md` -> (design) e `docs/superpowers/plans/2026-08-10-n8n-agendamento-workflow.md` (plano). +> Registra problemas reais encontrados ao montar os workflows de +> agendamento no n8n (servidor `srvdevn8ngti` / `devn8n.gtigrupo.com.br`) +> e como foram resolvidos — para não repetir o mesmo processo de +> descoberta ao duplicar para uma nova clínica ou provider. As seções 1-13 +> cobrem o histórico completo do **Z-PRO** (o único provider em produção +> real até agora, incluindo a migração do node comunitário pro MCP Server +> nativo do n8n). A seção 14 cobre os outros três providers — **Klingo**, +> **SysLife** e **ClinicAll** — todos construídos com o mesmo padrão de +> MCP Server nativo, mas ainda sem clínica real pra testar (ver cada +> subseção pras specs/planos completos e pendências específicas). ## 1. Node MCP: qual usar e como instalar @@ -358,7 +362,7 @@ mais a este workflow, mas continuam relevantes se algum dia o padrão nativo não for suficiente e for necessário voltar ao processo externo (`gti-scheduling-mcp`, monorepo TypeScript pausado). -## Status final (11/08/2026) +## Status final — Z-PRO (11/08/2026) Testado de ponta a ponta com sucesso, tanto com a chave real da OpenAI (`gpt-4o-mini`) quanto com o MCP Server nativo do n8n (seção 13): telefone @@ -367,3 +371,56 @@ visualmente no Z-PRO. Workflow **ativo em produção** (`yG2mi6ECBpPv4Hmn`), junto com os 3 workflows do MCP Server nativo (`qjSaKllvneBIZ7mC`, `5ZEOqTOk4Xex6jUQ`, `yfKkhSTDZaIYCPqP`) — todos precisam permanecer `active: true`. + +## 14. Providers adicionais via MCP Server nativo (Klingo, SysLife, ClinicAll) + +Mesmo padrão arquitetural validado no Z-PRO (seção 13) — `MCP Server +Trigger` + `Call n8n Sub-Workflow Tool`, sem processo Node.js externo — +aplicado a mais três providers nesta sessão (11/08/2026). Nenhum dos três +tem clínica real disponível ainda: todos os workflows foram criados e +validados estruturalmente (`n8n_validate_workflow`, 0 erros), mas ficam +**inativos**, sem nenhuma chamada HTTP real feita, e sem workflow de +agente cliente (AI Agent + prompt) — isso fica para quando houver uma +clínica real e um canal de mensagens definido para cada um. + +### 14.1 - Klingo + +- Spec: `docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-klingo-design.md` +- Plano: `docs/superpowers/plans/2026-08-11-mcp-server-nativo-n8n-klingo.md` +- Tools de apoio (spec/plano adicional): `docs/superpowers/specs/2026-08-11-klingo-tools-de-apoio-design.md` / `docs/superpowers/plans/2026-08-11-klingo-tools-de-apoio.md` +- Fonte: `gti-scheduling-mcp/docs/klingo-openapi.json` (Swagger público) — único provider dos 4 com adapter TypeScript prévio testado (`KlingoAdapter`), portado fielmente. +- **7 tools** no servidor `MCP Server - Klingo` (`3eiFEnfOTLnutP78`): `agendar` (`0PXwQZ3EXJUtuRgN`), `consultar_horarios` (`7ikOIk6mdoBwClC3`), `especialidade` (`VhDRpgVxC7Bq9ZMg`), `profissional` (`27HOTfmlTH0r5UiX`), `convenio` (`v8VGt7Du0zfbc2FT`), `unidade` (`Sms5egwOtmZkeIkw`), `preco` (`tSq0p8fRxS39CSWE`). +- **Diferença de autenticação em relação ao Z-PRO**: dois estágios — `X-APP-TOKEN` estático (credencial `Klingo APP Token - clínica pendente`, `lwmRgDYe7W1zrKP5`) para identificar o paciente e consultar catálogo, e um **Bearer de sessão dinâmico** (obtido na resposta de `/paciente/identificar`, nunca armazenado como credential) só para `/agenda/reservar`. +- **Limitação conhecida, sem solução**: não existe endpoint público de listagem de procedimentos no Klingo — `specialtyId`/`procedimento` (exigido por `agendar` e opcionalmente por `preco`) não tem nenhuma tool que resolva. `consultar_horarios` sempre retorna `SLOT_MAPPING_UNAVAILABLE` pelo mesmo motivo já registrado no `KlingoAdapter` original (formato de horário individual não documentado no Swagger público). + +### 14.2 - SysLife + +- Spec: `docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-syslife-design.md` +- Plano: `docs/superpowers/plans/2026-08-11-mcp-server-nativo-n8n-syslife.md` +- Fonte: `Manual WS SysLife V3.4.pdf` (fornecido pelo usuário) — sem adapter TypeScript prévio, único provider cuja fonte de verdade é só o manual. +- **7 tools** no servidor `MCP Server - SysLife` (`TYu78UqIUr2yCBHK`): `especialidade`, `medico`, `convenio`, `paciente`, `procedimento`, `consultar_horarios` (GET `/Horario`), `agendar` (PUT `/Agenda`). +- **Autenticação**: Basic Auth fixo do WebService (usuário/senha documentados literalmente no manual, não por clínica) — credencial `SysLife Basic Auth - clínica pendente` (`u8XXJ6wyrKuGJp4Y`), reaproveitada nas 7 tools. Só o `baseUrl` (IP:porta) muda por clínica. +- **Ponto forte deste provider**: o `Horario` GET retorna `nuConsulta`, que corresponde ao `NumeroConsulta` esperado no `Agenda` PUT — ciclo consultar→agendar fecha de verdade, diferente do Klingo. + +### 14.3 - ClinicAll + +- Spec: `docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-clinicall-design.md` +- Plano: `docs/superpowers/plans/2026-08-11-mcp-server-nativo-n8n-clinicall.md` +- Fonte: `docs/API Clinicall.pdf` ("Documentação da API de Integração com ClinicAll para Módulo de Agendamento", v1.1.16, Focus Tecnologia em Sistemas) — a documentação mais completa e explícita dos 4 providers (campos obrigatórios, exemplos reais de request/response). +- **8 tools** no servidor `MCP Server - ClinicAll` (`igaKjoHcPNYRAxPS`): `unidade`, `especialidade`, `convenio`, `profissional`, `procedimento`, `paciente`, `consultar_horarios` (GET `/disponibilidade/{idUnidade}/{idProfissional}`), `agendar` (PUT `/agendamento`). +- **Duas pendências reais, sem credencial nem verbo assumido por invenção**: + 1. **Autenticação desconhecida** — o manual não documenta nenhum header/token nas chamadas de `TEntityController`/`TPatientController`/`TCalendarController`. Nenhuma credencial foi criada; todos os nodes HTTP usam `authentication: none`. Existe um `TAuthenticateController/login` separado, mas não está claro se é pré-requisito nem que token ele gera. + 2. **Verbo HTTP do agendamento não confirmado** — `/agendamento` aceita GET/POST/PUT/DELETE sem o manual mapear qual verbo concilia um `idAgenda` livre já existente (o fluxo real é atualizar um registro pré-existente, não criar do zero). Assumido `PUT`; se não funcionar contra uma clínica real, tentar `POST` antes de qualquer outra hipótese. +- **Ponto forte deste provider**: `/disponibilidade` retorna `idAgenda` de cada horário livre, e esse mesmo `idAgenda` é usado para "conciliar" o agendamento via `/agendamento` — mesmo padrão de ciclo fechado do SysLife, com a vantagem de já vir com nome do profissional/especialidade/unidade no mesmo payload. + +### 14.4 - Padrão comum aos três (e ao Z-PRO) + +Reforçando o que já vale desde a seção 13, agora confirmado em mais três implementações: + +- Cada provider = 1 workflow servidor (`MCP Server Trigger` + N `Call n8n Sub-Workflow Tool`) + N sub-workflows (1 por tool). +- Sub-workflows chamados via `Call n8n Sub-Workflow Tool` **precisam estar `active: true`** para funcionar no caminho real do AI Agent (gotcha 1 da seção 13) — nenhum dos três providers desta seção foi ativado ainda, então isso só será re-confirmado quando houver teste real. +- HTTP Request nodes sempre com `neverError: true` + `fullResponse: true` — captura manual de status/corpo, nunca deixa o n8n abortar em 4xx/5xx. +- Tools de escrita (`agendar`) sempre com a regra "qualquer HTTP 2xx é sucesso operacional" — proteção contra duplicidade, nunca reportar erro numa operação que a API já aceitou. +- Tools de leitura nunca reformatam o corpo de sucesso — devolvem cru, sem inventar um envelope que não foi confirmado por um exemplo real de resposta. +- Mapeamento de parâmetros `$fromAI(...)` nas tools do servidor é sempre um passo manual na UI (resourceMapper não é confiável via API do n8n) — feito pelo usuário, não pela automação. +- Nenhuma credencial é criada automaticamente pela automação — sempre pré-requisito manual do usuário na UI do n8n, mesmo quando o valor é só um placeholder de rascunho.