# 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.