diff --git a/docs/Manual WS SysLife V3.4 (1).pdf b/docs/Manual WS SysLife V3.4 (1).pdf new file mode 100644 index 0000000..66834a4 Binary files /dev/null and b/docs/Manual WS SysLife V3.4 (1).pdf differ diff --git a/docs/superpowers/specs/2026-08-11-confirmacao-agenda-syslife-design.md b/docs/superpowers/specs/2026-08-11-confirmacao-agenda-syslife-design.md new file mode 100644 index 0000000..3ef0b63 --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-confirmacao-agenda-syslife-design.md @@ -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": }`. +- **`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": "" }`. +- **`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": , "Resposta": "" }`. + +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.