Spec: confirmação de agenda via WhatsApp (ClinicAll)
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Gustavo
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
49e9cb9bca
commit
01ca9d5e34
@@ -0,0 +1,200 @@
|
|||||||
|
# Design — Confirmação de Agenda via WhatsApp (ClinicAll)
|
||||||
|
|
||||||
|
**Data:** 2026-08-11
|
||||||
|
**Status:** Aprovado pelo usuário, aguardando plano de implementação.
|
||||||
|
|
||||||
|
## Objetivo
|
||||||
|
|
||||||
|
Mesmo padrão já implementado para o Klingo
|
||||||
|
(`docs/superpowers/specs/2026-08-11-confirmacao-agenda-klingo-design.md`),
|
||||||
|
agora para o **ClinicAll**: permitir que o paciente confirme presença
|
||||||
|
numa consulta agendada via WhatsApp. Diferente do Klingo, o ClinicAll
|
||||||
|
não tem uma API de "Telefonia" separada — os endpoints de confirmação
|
||||||
|
fazem parte da mesma `TCalendarController` já usada no MVP de
|
||||||
|
agendamento (`docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-clinicall-design.md`),
|
||||||
|
verificados diretamente no manual oficial (`docs/API Clinicall.pdf`,
|
||||||
|
versão 1.1.16).
|
||||||
|
|
||||||
|
## 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 — mesma decisão do Klingo, assumindo que o cliente ClinicAll
|
||||||
|
de exemplo também usaria Z-PRO/GChat como canal de WhatsApp.
|
||||||
|
- É um MCP **novo e separado** do MCP de agendamento do ClinicAll
|
||||||
|
(seção 14.3 do runbook) — mesmo `TCalendarController`/`TDomainController`,
|
||||||
|
mas endpoints diferentes (confirmação de presença, não criação de
|
||||||
|
agendamento), mesmo espírito de separação de responsabilidades já
|
||||||
|
usado no Klingo (MCP de Telefonia separado do MCP de Agendamento).
|
||||||
|
- Mesma pendência de autenticação já documentada no MVP de agendamento
|
||||||
|
do ClinicAll: o manual não documenta nenhum header de autenticação
|
||||||
|
por requisição para `TCalendarController`/`TDomainController`.
|
||||||
|
**Decisão idêntica à já tomada**: `authentication: none` em todos os
|
||||||
|
nodes HTTP, nada inventado.
|
||||||
|
|
||||||
|
## Escopo: 5 tools do MCP Server "ClinicAll - Confirmação de Agenda"
|
||||||
|
|
||||||
|
| Tool | Endpoint | Uso |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `listar_agendamentos_do_dia` | `GET /TCalendarController/agendamento` (param: `data`) | Base do lembrete proativo — todas as marcações de uma data (livres e agendadas) |
|
||||||
|
| `buscar_agendamento_por_cpf` | `GET/POST /TCalendarController/agendamentoSemPaciente` (params: `cpf`, `dataNascimento`) | O agente usa isso pra achar a consulta pendente do paciente — **precisa de CPF e data de nascimento**, diferente do Klingo (que só pedia CPF) |
|
||||||
|
| `confirmar_presenca` | `POST /TCalendarController/AgendamentoFlags` | Ação central — atualiza `estadoAgenda`/`situacaoAgenda` da marcação |
|
||||||
|
| `consultar_estados_agenda` | `GET /TDomainController/estadoAgenda` | Tabela de domínio — valores exatos aceitos em `estadoAgenda` (ex.: `"CONFIRMADO PELA TELEFONISTA"`, `"NAO CONFIRMADO"`, `"FALTOU"`) |
|
||||||
|
| `consultar_situacoes_agenda` | `GET /TDomainController/situacaoAgenda` | Tabela de domínio — valores exatos aceitos em `situacaoAgenda` (ex.: `"Agendado"`, `"Presente"`, `"Atrasado"`) |
|
||||||
|
|
||||||
|
**Diferença estrutural real em relação ao Klingo**: o Klingo aceita um
|
||||||
|
código curto de 1 letra (`C`/`S`/`N`) pra confirmar. O ClinicAll exige
|
||||||
|
uma **string exata e longa** em dois campos separados
|
||||||
|
(`estadoAgenda`/`situacaoAgenda`), cujos valores válidos só existem
|
||||||
|
documentados nas tabelas de domínio — por isso `consultar_estados_agenda`
|
||||||
|
e `consultar_situacoes_agenda` entram como tools de apoio (não
|
||||||
|
opcionais): sem elas, o agente teria que adivinhar a string exata, o
|
||||||
|
que violaria a disciplina de não inventar valores. Não há tool
|
||||||
|
equivalente a NPS ou consulta de bloqueios — o manual do ClinicAll não
|
||||||
|
documenta nada parecido para este módulo; ficam fora, sem inventar.
|
||||||
|
|
||||||
|
## Arquitetura
|
||||||
|
|
||||||
|
Três peças, mesmo padrão do Klingo:
|
||||||
|
|
||||||
|
```
|
||||||
|
1) MCP Server "ClinicAll - Confirmação de Agenda" (servidor + 5 sub-workflows)
|
||||||
|
[MCP Server Trigger] ──Tools──┬── listar_agendamentos_do_dia ──▶ GET /TCalendarController/agendamento
|
||||||
|
├── buscar_agendamento_por_cpf ──▶ GET/POST /TCalendarController/agendamentoSemPaciente
|
||||||
|
├── confirmar_presenca ──▶ POST /TCalendarController/AgendamentoFlags
|
||||||
|
├── consultar_estados_agenda ──▶ GET /TDomainController/estadoAgenda
|
||||||
|
└── consultar_situacoes_agenda ──▶ GET /TDomainController/situacaoAgenda
|
||||||
|
|
||||||
|
2) Workflow proativo "Lembrete de Confirmação - ClinicAll (exemplo)"
|
||||||
|
[Cron 8h diário] → [ClinicAll: listar_agendamentos_do_dia (amanhã)]
|
||||||
|
→ [Loop por agendamento] → [Mensageria ZPRO: enviar_texto]
|
||||||
|
|
||||||
|
3) Workflow de exemplo "Confirmação de Agenda - GChat - ClinicAll+Z-PRO (exemplo)"
|
||||||
|
[Webhook Z-PRO/GChat] → [AI Agent] → resposta ao paciente
|
||||||
|
tools: MCP ClinicAll - Confirmação de Agenda (buscar_agendamento_por_cpf, confirmar_presenca,
|
||||||
|
consultar_estados_agenda, consultar_situacoes_agenda)
|
||||||
|
memória: Postgres Chat Memory (mesmo padrão dos outros exemplos)
|
||||||
|
```
|
||||||
|
|
||||||
|
Sem cliente ClinicAll real disponível: mesma disciplina do Klingo —
|
||||||
|
estrutura completa, validada (`n8n_validate_workflow`, 0 erros
|
||||||
|
esperados), sem teste de ponta a ponta.
|
||||||
|
|
||||||
|
## Componentes
|
||||||
|
|
||||||
|
### MCP Server "ClinicAll - Confirmação de Agenda"
|
||||||
|
|
||||||
|
Mesmo esqueleto de sub-workflow dos outros MCP Servers deste projeto:
|
||||||
|
`Execute Workflow Trigger` → `Config ClinicAll` (`Set` com `baseUrl`
|
||||||
|
placeholder) → montagem de query/body → `HTTP Request`
|
||||||
|
(`authentication: none`, `neverError: true` + `fullResponse: true`) →
|
||||||
|
classificação de resultado (mesma taxonomia genérica dos outros
|
||||||
|
providers: `AUTHENTICATION_ERROR` 401/403, `NOT_FOUND` 404,
|
||||||
|
`VALIDATION_ERROR` 400/422, `CLINICALL_API_ERROR` demais — o manual não
|
||||||
|
documenta código de erro específico pra estes endpoints).
|
||||||
|
|
||||||
|
- **`listar_agendamentos_do_dia`**: parâmetro `data` (obrigatório,
|
||||||
|
conforme documentado — "Mandatório data da agenda"). URL:
|
||||||
|
`{{baseUrl}}/datasnap/rest/TCalendarController/agendamento/<data>`
|
||||||
|
(mesmo endpoint base já usado no MVP de agendamento com `PUT` para
|
||||||
|
conciliar; aqui usado com `GET` para listar).
|
||||||
|
- **`buscar_agendamento_por_cpf`**: parâmetros `cpf` e `dataNascimento`
|
||||||
|
(ambos obrigatórios, conforme documentado). Endpoint:
|
||||||
|
`{{baseUrl}}/datasnap/rest/TCalendarController/agendamentoSemPaciente`.
|
||||||
|
**Ambiguidade real do manual**: o endpoint documenta métodos `GET,
|
||||||
|
POST` sem esclarecer se os parâmetros vão como query string (GET) ou
|
||||||
|
corpo (POST) — o exemplo do manual não mostra a requisição, só a
|
||||||
|
resposta. Decisão desta etapa: implementar como `GET` com os dois
|
||||||
|
parâmetros como query string (`?cpf=...&dataNascimento=...`), por
|
||||||
|
ser o padrão mais comum nos demais endpoints GET documentados deste
|
||||||
|
mesmo manual (todos os outros GETs do ClinicAll usam query string,
|
||||||
|
nunca body) — mas isso é uma suposição não verificada contra a API
|
||||||
|
real, registrada explicitamente como tal.
|
||||||
|
- **`confirmar_presenca`**: parâmetros `idAgenda` (obrigatório),
|
||||||
|
`situacaoAgenda` (obrigatório, string exata — ex.: `"Agendado"`),
|
||||||
|
`estadoAgenda` (obrigatório, string exata — ex.: `"CONFIRMADO PELA
|
||||||
|
TELEFONISTA"`), `confirmadoPor` (opcional — nome de quem confirmou,
|
||||||
|
útil quando não é o próprio paciente respondendo), `usuarioConfirmou`,
|
||||||
|
`dataConfirmacao`, `horarioFlag`, `usuarioFlag` (estes quatro
|
||||||
|
opcionais, preenchidos com dados fixos identificando a automação —
|
||||||
|
ex.: `usuarioConfirmou: "bot-whatsapp"` — já que não há usuário
|
||||||
|
humano operando). Endpoint:
|
||||||
|
`{{baseUrl}}/datasnap/rest/TCalendarController/AgendamentoFlags`.
|
||||||
|
- **`consultar_estados_agenda`**: sem parâmetro obrigatório (aceita
|
||||||
|
`nome` opcional de busca, conforme documentado). Endpoint:
|
||||||
|
`{{baseUrl}}/datasnap/rest/TDomainController/estadoAgenda`.
|
||||||
|
- **`consultar_situacoes_agenda`**: mesmo padrão, endpoint
|
||||||
|
`{{baseUrl}}/datasnap/rest/TDomainController/situacaoAgenda`.
|
||||||
|
|
||||||
|
### Workflow proativo "Lembrete de Confirmação - ClinicAll (exemplo)"
|
||||||
|
|
||||||
|
```
|
||||||
|
[Cron Trigger, 8h diário] → [ClinicAll: listar_agendamentos_do_dia]
|
||||||
|
(data = amanhã, calculada via expressão)
|
||||||
|
→ [Loop] → [Mensageria ZPRO: enviar_texto]
|
||||||
|
(number = telefoneCelular do paciente dentro do objeto Paciente
|
||||||
|
aninhado, body = mensagem com nomePaciente + dataAgenda/horaAgenda)
|
||||||
|
```
|
||||||
|
|
||||||
|
Mesmo padrão do Klingo: chamada direta via `Execute Workflow` (sem IA,
|
||||||
|
fluxo determinístico). Nota: no ClinicAll, o telefone do paciente vem
|
||||||
|
aninhado dentro do objeto `Paciente` de cada item da lista
|
||||||
|
(`item.Paciente.telefoneCelular`), diferente do Klingo onde `celular`
|
||||||
|
era um campo direto do item — refletir isso na extração de dados.
|
||||||
|
Itens com `situacaoAgenda: "Livre"` (sem paciente vinculado) devem ser
|
||||||
|
filtrados antes do envio — só mandar lembrete pra marcações com
|
||||||
|
`idPaciente` preenchido. Texto fixo nesta rodada (sem Google Docs — é
|
||||||
|
exemplo/esqueleto, sem gestor real). Fica **inativo** de propósito —
|
||||||
|
sem clínica real, ativar geraria só chamadas com erro.
|
||||||
|
|
||||||
|
### Workflow de exemplo "Confirmação de Agenda - GChat - ClinicAll+Z-PRO (exemplo)"
|
||||||
|
|
||||||
|
Réplica estrutural do padrão já usado no Klingo e no Z-PRO (webhook →
|
||||||
|
AI Agent → memória Postgres), sem cliente real associado.
|
||||||
|
|
||||||
|
- **Webhook**: mesmo contrato Z-PRO/GChat já documentado (seção 6 do
|
||||||
|
runbook).
|
||||||
|
- **AI Agent**: `systemMessage` fixo instruindo o agente a: entender se
|
||||||
|
a mensagem é uma resposta de confirmação/recusa; se for, pedir **CPF
|
||||||
|
e data de nascimento** do paciente (diferente do Klingo, que só
|
||||||
|
precisava do CPF) e usar `buscar_agendamento_por_cpf` para achar a
|
||||||
|
marcação pendente; consultar `consultar_estados_agenda` e
|
||||||
|
`consultar_situacoes_agenda` para obter as strings exatas válidas
|
||||||
|
antes de decidir o que enviar (nunca inventar um valor de estado);
|
||||||
|
chamar `confirmar_presenca` com `estadoAgenda: "CONFIRMADO PELA
|
||||||
|
TELEFONISTA"` (paciente confirmou) ou `estadoAgenda: "NAO
|
||||||
|
CONFIRMADO"`/`"FALTOU"` conforme o caso, mantendo `situacaoAgenda:
|
||||||
|
"Agendado"` (a marcação continua agendada, só o estado de confirmação
|
||||||
|
muda); responder confirmando o registro ao paciente.
|
||||||
|
- **Tools**: MCP ClinicAll - Confirmação de Agenda — `buscar_agendamento_por_cpf`,
|
||||||
|
`confirmar_presenca`, `consultar_estados_agenda`,
|
||||||
|
`consultar_situacoes_agenda` conectadas (todas as 4 exceto
|
||||||
|
`listar_agendamentos_do_dia`, que só serve ao workflow proativo).
|
||||||
|
- **Memória**: `Postgres Chat Memory`, mesmo padrão da seção 16/18 do
|
||||||
|
runbook, credencial placeholder (sem cliente real).
|
||||||
|
|
||||||
|
Fica **inativo** de propósito, mesma razão do workflow proativo.
|
||||||
|
|
||||||
|
## Fora de escopo (adiado)
|
||||||
|
|
||||||
|
- NPS / avaliação pós-consulta — não documentado no manual do
|
||||||
|
ClinicAll para este módulo.
|
||||||
|
- Consulta de bloqueios de agenda — não documentado no manual do
|
||||||
|
ClinicAll para este módulo (existe `flagEstadoAgenda: "B" —
|
||||||
|
BLOQUEADO` como estado de uma marcação individual, mas não um
|
||||||
|
endpoint de consulta de bloqueios como no Klingo).
|
||||||
|
- Resolver a ambiguidade de GET vs. body em `agendamentoSemPaciente`
|
||||||
|
contra a API real — fica pendente até haver clínica real pra testar.
|
||||||
|
- Configuração via Google Docs no workflow de exemplo — sem gestor
|
||||||
|
real associado.
|
||||||
|
- Teste de ponta a ponta contra a API real do ClinicAll — sem clínica
|
||||||
|
real disponível, mesma limitação já registrada no MVP de agendamento.
|
||||||
|
|
||||||
|
## Testes
|
||||||
|
|
||||||
|
Sem clínica ClinicAll real disponível: validação estrutural apenas
|
||||||
|
(`n8n_validate_workflow`, 0 erros esperados em todos os workflows).
|
||||||
|
Teste real de ponta a ponta fica pendente para quando houver uma
|
||||||
|
clínica ClinicAll real — nesse momento, resolver primeiro a
|
||||||
|
autenticação (mesma pendência do MVP de agendamento) e a ambiguidade
|
||||||
|
de `agendamentoSemPaciente` antes de qualquer teste de confirmação.
|
||||||
Reference in New Issue
Block a user