diff --git a/docs/superpowers/specs/2026-08-11-confirmacao-agenda-klingo-design.md b/docs/superpowers/specs/2026-08-11-confirmacao-agenda-klingo-design.md new file mode 100644 index 0000000..80d4ac2 --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-confirmacao-agenda-klingo-design.md @@ -0,0 +1,176 @@ +# Design — Confirmação de Agenda via WhatsApp (Klingo Telefonia) + +**Data:** 2026-08-11 +**Status:** Aprovado pelo usuário, aguardando plano de implementação. + +## Objetivo + +Permitir que o paciente confirme presença numa consulta agendada via +WhatsApp, usando a **Klingo Telefonia API** +(`https://api-externa.klingo.app/api/telefonia`, auth `X-APP-TOKEN`) — +uma API separada da API de agendamento do Klingo já integrada +anteriormente. Dois fluxos compõem a feature: um **lembrete proativo** +(cron diário avisando o paciente da consulta do dia seguinte) e uma +**confirmação reativa** (o paciente responde "sim"/"não" no WhatsApp, e +o sistema registra isso no Klingo). + +## Relação com o trabalho anterior + +- Reaproveita o **MCP Server standalone de Mensageria (Z-PRO)** + (`docs/n8n-agendamento-runbook.md`, seção 17) para o disparo do + lembrete — este design não cria nenhuma lógica nova de envio de + mensagem, só consome a tool `enviar_texto` já validada. +- É um MCP **novo e separado** do MCP de agendamento do Klingo + (`docs/n8n-agendamento-runbook.md`, seção 14.1) — API diferente + (Telefonia vs. Agendamento), auth diferente (`X-APP-TOKEN` vs. o que + for usado no de agendamento), propósito diferente. Mesma disciplina + de não misturar integrações já estabelecida no projeto. +- Escopo excludente confirmado pelo usuário: o endpoint `POST /entrada` + da API de Telefonia (registro de chamada telefônica) fica **fora** + desta feature — "não envolve telefonia, apenas a confirmação no + nosso sistema de WhatsApp". + +## Escopo: 6 tools do MCP Server "Klingo Telefonia" + +| Tool | Endpoint | Uso | +| --- | --- | --- | +| `listar_agendamentos_do_dia` | `GET /lista/{data}` | Base do lembrete proativo — todas as consultas de uma data | +| `consultar_agendamento_por_id` | `GET /{id}` | Detalhe de uma consulta específica | +| `buscar_agendamento_pendente_por_cpf` | `GET /lista_ultimo_por_cpf` | O agente usa isso pra achar qual consulta o paciente está confirmando, a partir do CPF/telefone dele | +| `confirmar_presenca` | `POST /confirmar` | Ação central — registra a confirmação/recusa de presença no Klingo | +| `registrar_nps` | `POST /nps` | Pesquisa de satisfação pós-consulta — fora do fluxo de confirmação em si, mas dentro do escopo "tudo" aprovado pelo usuário | +| `consultar_bloqueios` | `GET /bloqueios` | Consulta de bloqueios de agenda — informativo | + +`POST /entrada` excluído (ver seção anterior). + +## Arquitetura + +Três peças distintas, cada uma um conjunto de workflows n8n: + +``` +1) MCP Server "Klingo Telefonia" (servidor + 6 sub-workflows) + [MCP Server Trigger] ──Tools──┬── listar_agendamentos_do_dia ──▶ GET /lista/{data} + ├── consultar_agendamento_por_id ──▶ GET /{id} + ├── buscar_agendamento_pendente_por_cpf ──▶ GET /lista_ultimo_por_cpf + ├── confirmar_presenca ──▶ POST /confirmar + ├── registrar_nps ──▶ POST /nps + └── consultar_bloqueios ──▶ GET /bloqueios + +2) Workflow proativo "Lembrete de Confirmação — Klingo (exemplo)" + [Cron 8h diário] → [Klingo Telefonia: listar_agendamentos_do_dia (amanhã)] + → [Loop por agendamento] → [Mensageria ZPRO: enviar_texto] + +3) Workflow de exemplo "Confirmação de Agenda — GChat - Klingo+Z-PRO (exemplo)" + [Webhook Z-PRO/GChat] → [AI Agent] → resposta ao paciente + tools: MCP Klingo Telefonia (buscar_agendamento_pendente_por_cpf, confirmar_presenca) + memória: Postgres Chat Memory (mesmo padrão da clínica exemplo) +``` + +Nenhuma das três peças depende de cliente real Klingo em produção para +existir estruturalmente — mesma disciplina já usada pra Klingo/SysLife/ +ClinicAll no agendamento: construir e validar a estrutura +(`n8n_validate_workflow`, 0 erros), sem teste de ponta a ponta contra a +API real (sem credencial de teste disponível no momento). + +## Componentes + +### MCP Server "Klingo Telefonia" + +Mesmo esqueleto de sub-workflow usado em todos os outros MCP Servers +deste projeto: `Execute Workflow Trigger` → `Config Klingo Telefonia` +(`Set` com `baseUrl` e placeholder de auth) → montagem de +query/params/body → `HTTP Request` (header `X-APP-TOKEN`, +`neverError: true` + `fullResponse: true`) → classificação de resultado +(taxonomia genérica já usada nos outros providers: +`AUTHENTICATION_ERROR` 401/403, `NOT_FOUND` 404, `VALIDATION_ERROR` +400/422, `KLINGO_TELEFONIA_API_ERROR` demais). + +- **`listar_agendamentos_do_dia`**: parâmetro `data` (formato a + confirmar contra a spec do SwaggerHub — assumido `YYYY-MM-DD` até + verificação). Devolve lista de agendamentos do dia. +- **`consultar_agendamento_por_id`**: parâmetro `id`. +- **`buscar_agendamento_pendente_por_cpf`**: parâmetro `cpf`. +- **`confirmar_presenca`**: parâmetros `id` (ou `idAgenda`, a confirmar + contra a spec) e `resposta`/`confirmado` (a confirmar o formato exato + esperado pela API — booleano vs. enum — contra o SwaggerHub na hora + da implementação). +- **`registrar_nps`**: parâmetros `id` e nota/comentário (formato a + confirmar contra a spec). +- **`consultar_bloqueios`**: sem parâmetros obrigatórios óbvios — a + confirmar contra a spec (pode aceitar filtro de data/profissional). + +**Pendência explícita**: os nomes exatos de campo de cada endpoint +(além do que já foi inspecionado) serão confirmados durante a +implementação, consultando o spec OpenAPI do SwaggerHub +(`api.swaggerhub.com/apis/agsx30/klingo-api-telefonia/1.0.0` — técnica +de acesso direto ao spec raw já validada nesta sessão). Nenhum campo +será inventado; se o spec não documentar algo necessário, fica +registrado como pendência, não como suposição. + +**Autenticação**: assim como o MCP de Mensageria, nenhuma credencial é +inventada — a criação da credencial `httpHeaderAuth` com o +`X-APP-TOKEN` real fica pré-requisito manual do usuário, feito quando +houver uma clínica Klingo real pra testar. + +### Workflow proativo "Lembrete de Confirmação — Klingo (exemplo)" + +``` +[Cron Trigger, 8h diário] → [Klingo Telefonia: listar_agendamentos_do_dia] + (data = amanhã, calculada via expressão) + → [Split in Batches / loop] → [Mensageria ZPRO: enviar_texto] + (number = telefone do paciente, body = mensagem de lembrete com + nome do paciente + data/hora da consulta) +``` + +Chama diretamente as tools dos dois MCP Servers via `Execute Workflow` +(não via AI Agent — fluxo determinístico, sem necessidade de +interpretação de linguagem natural). Sem lógica de "já lembrado +antes" nesta rodada — se rodar mais de uma vez no mesmo dia por engano, +manda lembrete duplicado; ajuste futuro se isso for um problema real. +Texto do lembrete fixo nesta rodada (sem config via Google Docs — é +workflow de exemplo, sem cliente/gestor real associado ainda). + +### Workflow de exemplo "Confirmação de Agenda — GChat - Klingo+Z-PRO (exemplo)" + +Réplica estrutural do padrão já usado na clínica exemplo (webhook → +AI Agent → memória Postgres), mas **sem cliente real associado** — +workflow de referência/esqueleto, mesmo espírito dos MCP Servers de +agendamento Klingo/SysLife/ClinicAll já construídos sem clínica real. + +- **Webhook**: mesmo contrato do Z-PRO/GChat já documentado (seção 6 + do runbook). +- **AI Agent**: `systemMessage` fixo (sem Google Docs nesta rodada) + instruindo o agente a: entender se a mensagem do paciente é uma + resposta de confirmação/recusa de presença; se for, usar + `buscar_agendamento_pendente_por_cpf` pra achar a consulta pendente + (a partir do telefone/CPF do contato do webhook) e então chamar + `confirmar_presenca`; responder ao paciente confirmando o registro. +- **Tools**: MCP Klingo Telefonia — só `buscar_agendamento_pendente_por_cpf` + e `confirmar_presenca` conectados nesta rodada (as outras 4 tools do + MCP existem mas não são atribuídas a este agente específico — podem + ser usadas por outros workflows futuros). +- **Memória**: `Postgres Chat Memory`, mesmo padrão da seção 16 do + runbook — credencial própria a ser criada quando houver cliente real. + +## Fora de escopo (adiado) + +- `POST /entrada` (telefonia em si) — explicitamente fora, por + instrução do usuário. +- Lógica de "não lembrar de novo se já confirmado" no workflow + proativo — YAGNI até aparecer o caso real. +- Configuração via Google Docs no workflow de exemplo — sem gestor/ + cliente real associado ainda; replicar quando houver. +- Teste de ponta a ponta contra a API real do Klingo Telefonia — sem + credencial de teste disponível. +- Qualquer UI/relatório de acompanhamento de confirmações — não + solicitado. + +## Testes + +Sem cliente/credencial real Klingo Telefonia disponível: validação +estrutural apenas (`n8n_validate_workflow`, 0 erros esperados em todos +os workflows) — mesma disciplina já usada para Klingo/SysLife/ClinicAll +no agendamento. Teste real de ponta a ponta (lembrete disparando, +paciente respondendo, `/confirmar` sendo chamado corretamente) fica +pendente para quando houver uma clínica Klingo real em produção, com +credencial de teste da API de Telefonia.