Spec: confirmação de agenda via WhatsApp (SysLife)
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
e791474d15
commit
f3e513a73a
Binary file not shown.
@@ -0,0 +1,175 @@
|
||||
# Design — Confirmação de Agenda via WhatsApp (SysLife)
|
||||
|
||||
**Data:** 2026-08-11
|
||||
**Status:** Aprovado pelo usuário, aguardando plano de implementação.
|
||||
|
||||
## Objetivo
|
||||
|
||||
Mesmo padrão já implementado para Klingo e ClinicAll
|
||||
(`docs/superpowers/specs/2026-08-11-confirmacao-agenda-klingo-design.md`,
|
||||
`docs/superpowers/specs/2026-08-11-confirmacao-agenda-clinicall-design.md`),
|
||||
agora para o **SysLife**: permitir que o paciente confirme presença numa
|
||||
consulta agendada via WhatsApp. Os endpoints usados fazem parte do mesmo
|
||||
WebService já usado no MVP de agendamento (`Manual WS SysLife V3.4.pdf`,
|
||||
salvo em `docs/Manual WS SysLife V3.4 (1).pdf`, relido nesta sessão),
|
||||
recurso `AgendaWSApp` — explicitamente descrito no manual como "retorna
|
||||
os registros da agenda **para uso do WhatsApp**".
|
||||
|
||||
## 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 e do ClinicAll.
|
||||
- É um MCP **novo e separado** do MCP de agendamento do SysLife
|
||||
(seção 14.2 do runbook) — endpoints diferentes (`AgendaWSApp` de
|
||||
confirmação vs. `Agenda`/`Horario`/etc. de criação), mesmo espírito
|
||||
de separação já usado nos outros dois providers.
|
||||
- **Reaproveita a credencial Basic Auth já criada** no MVP de
|
||||
agendamento do SysLife (`SysLife Basic Auth - clínica pendente`,
|
||||
`u8XXJ6wyrKuGJp4Y`) — usuário/senha fixos do WebService
|
||||
(`WebSysLife`/`$Sys10Life`), documentados literalmente no manual, não
|
||||
variam por clínica nem por endpoint. Diferente do Klingo (token por
|
||||
clínica) e do ClinicAll (sem auth documentada), aqui a credencial já
|
||||
existe e pode ser usada de verdade.
|
||||
|
||||
## Escopo: 3 tools do MCP Server "SysLife - Confirmação de Agenda"
|
||||
|
||||
O recurso `AgendaWSApp` do manual é mais rico que o equivalente dos
|
||||
outros dois providers: um único `GET` já serve três propósitos
|
||||
diferentes, alternados por qual dos três parâmetros é enviado (o manual
|
||||
é explícito: **"Deverá ser usado somente um dos 3 parâmetros"**):
|
||||
|
||||
| Tool | Endpoint | Parâmetro usado | Uso |
|
||||
| --- | --- | --- | --- |
|
||||
| `listar_agendamentos_do_dia` | `GET /AgendaWSApp` | `QuantidadeDias` (`1` = amanhã, `2` = depois de amanhã, etc.) | Base do lembrete proativo |
|
||||
| `buscar_agendamento_por_telefone` | `GET /AgendaWSApp` | `NumeroCelular` (DDD + número, sem separador) | O agente usa pra achar a consulta pendente do paciente pelo telefone |
|
||||
| `confirmar_presenca` | `POST /AgendaWSApp` | `CodigoAgenda` + `Resposta` (`"1"` = SIM, `"2"` = NÃO) | Ação central — o mais simples dos três providers, só dois valores possíveis |
|
||||
|
||||
Duas tools de leitura (`listar_agendamentos_do_dia`,
|
||||
`buscar_agendamento_por_telefone`) apontam pro **mesmo endpoint**, cada
|
||||
uma com um sub-workflow próprio que monta o parâmetro certo — mesma
|
||||
separação de responsabilidade já usada nos outros MCP Servers deste
|
||||
projeto (uma tool, um propósito claro), mesmo reaproveitando a chamada
|
||||
HTTP de baixo nível.
|
||||
|
||||
**Fora de escopo, mesmo raciocínio do `/entrada` do Klingo e do
|
||||
`AgendaCentral`/relatórios do ClinicAll**: `AgendaCentral` (central
|
||||
telefônica, não WhatsApp), `AgendaRetorno` (consultas de retorno, não
|
||||
confirmação), `AgendaStatus` (base para NPS, sem endpoint de submissão
|
||||
documentado no manual) e `AgendaConfirmado` (só consulta informativa de
|
||||
quem já confirmou, sem ação — não essencial ao fluxo).
|
||||
|
||||
## Arquitetura
|
||||
|
||||
```
|
||||
1) MCP Server "SysLife - Confirmação de Agenda" (servidor + 3 sub-workflows)
|
||||
[MCP Server Trigger] ──Tools──┬── listar_agendamentos_do_dia ──▶ GET /AgendaWSApp (QuantidadeDias)
|
||||
├── buscar_agendamento_por_telefone ──▶ GET /AgendaWSApp (NumeroCelular)
|
||||
└── confirmar_presenca ──▶ POST /AgendaWSApp (CodigoAgenda, Resposta)
|
||||
|
||||
2) Workflow proativo "Lembrete de Confirmação - SysLife (exemplo)"
|
||||
[Cron 8h diário] → [SysLife: listar_agendamentos_do_dia (QuantidadeDias=1)]
|
||||
→ [Loop por agendamento] → [Mensageria ZPRO: enviar_texto]
|
||||
|
||||
3) Workflow de exemplo "Confirmação de Agenda - GChat - SysLife+Z-PRO (exemplo)"
|
||||
[Webhook Z-PRO/GChat] → [AI Agent] → resposta ao paciente
|
||||
tools: MCP SysLife - Confirmação de Agenda (buscar_agendamento_por_telefone, confirmar_presenca)
|
||||
memória: Postgres Chat Memory (mesmo padrão dos outros exemplos)
|
||||
```
|
||||
|
||||
Sem clínica SysLife real disponível: mesma disciplina dos outros dois
|
||||
providers — estrutura completa, validada (`n8n_validate_workflow`, 0
|
||||
erros esperados), sem teste de ponta a ponta.
|
||||
|
||||
## Componentes
|
||||
|
||||
### MCP Server "SysLife - Confirmação de Agenda"
|
||||
|
||||
Mesmo esqueleto de sub-workflow do MVP de agendamento do SysLife:
|
||||
`Execute Workflow Trigger` → `Config SysLife` (`Set` com `baseUrl`
|
||||
placeholder) → `Montar corpo` (monta o JSON do body — mesmo em GET,
|
||||
conforme documentado: `Seção Body, Type raw, JSON`) → `HTTP Request`
|
||||
(Basic Auth via credencial reaproveitada, `neverError: true` +
|
||||
`fullResponse: true`) → `Classificar resultado` (mesma taxonomia
|
||||
genérica dos outros providers: `AUTHENTICATION_ERROR` 401/403,
|
||||
`NOT_FOUND` 404, `VALIDATION_ERROR` 400/422, `SYSLIFE_API_ERROR`
|
||||
demais — o manual não documenta código de erro específico).
|
||||
|
||||
- **`listar_agendamentos_do_dia`**: parâmetro `quantidadeDias`
|
||||
(obrigatório — `1` para amanhã, conforme o exemplo do manual "1 = Dia
|
||||
atual + 1"). Body: `{ "QuantidadeDias": <int> }`.
|
||||
- **`buscar_agendamento_por_telefone`**: parâmetro `numeroCelular`
|
||||
(obrigatório, string — DDD + número, ex.: `"71999999999"`, conforme
|
||||
documentado "Código DDD + Número do Celular"). Body:
|
||||
`{ "NumeroCelular": "<string>" }`.
|
||||
- **`confirmar_presenca`**: parâmetros `codigoAgenda` (obrigatório) e
|
||||
`resposta` (obrigatório, string `"1"` ou `"2"` — documentado na
|
||||
`description` da tool como `"1" = paciente confirmou`, `"2"` =
|
||||
paciente não confirmou/recusou, sem terceiro estado como no Klingo).
|
||||
Body: `{ "CodigoAgenda": <int>, "Resposta": "<string>" }`.
|
||||
|
||||
Resposta de `AgendaWSApp` GET é um array rico (campos `coAgenda`,
|
||||
`dtAtendimento`, `hrAtendimentoAlterado`, `nmPaciente`, `coMedico`,
|
||||
`nmMedico`, `nmEspecialidade`, `nmOrigemDestino`, `coProcedimento`,
|
||||
`nmProcedimento`, `nuTelefone`, `nuTelefoneDdd`, `nuCelular`,
|
||||
`nuCelularDdd`, `txObservacao`, `txWhatsappProcedimento`,
|
||||
`txWhatsappHorario`, `txWhatsappMedico`, `txEndereco`, `txBairro`,
|
||||
`txComplemento`, `txCidade`, `txEstado`, `nmMsgSms`, `nmMsgSmsExtra`) —
|
||||
já vem pronto com textos formatados pro WhatsApp
|
||||
(`txWhatsappProcedimento`/`txWhatsappHorario`/`txWhatsappMedico`), útil
|
||||
pra montar a mensagem do lembrete sem concatenar campos manualmente.
|
||||
|
||||
### Workflow proativo "Lembrete de Confirmação - SysLife (exemplo)"
|
||||
|
||||
```
|
||||
[Cron Trigger, 8h diário] → [SysLife: listar_agendamentos_do_dia]
|
||||
(quantidadeDias = 1, ou seja, amanhã)
|
||||
→ [Loop] → [Mensageria ZPRO: enviar_texto]
|
||||
(number = nuCelularDdd + nuCelular do item, body = mensagem usando
|
||||
txWhatsappProcedimento/txWhatsappHorario/txWhatsappMedico quando
|
||||
presentes, senão monta com nmProcedimento/dtAtendimento/nmMedico)
|
||||
```
|
||||
|
||||
Diferente do ClinicAll, o telefone aqui é campo direto do item
|
||||
(`nuCelular`/`nuCelularDdd`), sem objeto `Paciente` aninhado — mais
|
||||
parecido com o Klingo nesse aspecto. Fica **inativo** de propósito.
|
||||
|
||||
### Workflow de exemplo "Confirmação de Agenda - GChat - SysLife+Z-PRO (exemplo)"
|
||||
|
||||
Réplica estrutural do padrão já usado no Klingo e no ClinicAll (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 é confirmação/recusa; se for, pedir o telefone do paciente
|
||||
(ou usar o `telefone` já vindo do próprio contato do WhatsApp, quando
|
||||
disponível) e usar `buscar_agendamento_por_telefone` para achar o
|
||||
`coAgenda` pendente; chamar `confirmar_presenca` com
|
||||
`resposta: "1"` (confirmou) ou `"2"` (recusou); responder confirmando
|
||||
o registro. Mais simples que o ClinicAll — não precisa de tool de
|
||||
tabela de domínio, os dois valores já são documentados diretamente.
|
||||
- **Tools**: MCP SysLife - Confirmação de Agenda —
|
||||
`buscar_agendamento_por_telefone` e `confirmar_presenca` conectadas
|
||||
(`listar_agendamentos_do_dia` só serve ao workflow proativo).
|
||||
- **Memória**: `Postgres Chat Memory`, mesmo padrão da seção 16/18/19
|
||||
do runbook, credencial placeholder.
|
||||
|
||||
Fica **inativo** de propósito.
|
||||
|
||||
## Fora de escopo (adiado)
|
||||
|
||||
- `AgendaCentral`, `AgendaRetorno`, `AgendaStatus`, `AgendaConfirmado`
|
||||
— ver seção "Escopo" acima.
|
||||
- Configuração via Google Docs no workflow de exemplo — sem gestor
|
||||
real associado.
|
||||
- Teste de ponta a ponta contra a API real do SysLife — sem clínica
|
||||
real disponível (mesma pendência do MVP de agendamento).
|
||||
|
||||
## Testes
|
||||
|
||||
Sem clínica SysLife 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 SysLife real — a credencial Basic Auth já existe (reaproveitada
|
||||
do MVP de agendamento), então só falta o `baseUrl` real da clínica.
|
||||
Reference in New Issue
Block a user