Panorama do App — Clínica Maximiano
Documento técnico descritivo · 24/10/2026
Clínica Maximiano
Sistema de Automação de Atendimento · Panorama Técnico Completo
Este documento descreve a arquitetura, funcionalidades, integrações, automações e o estado atual do aplicativo da Clínica Maximiano, construído na plataforma Base44. O sistema é uma solução SaaS multi-tenant para gestão de clínicas de testes respiratórios, com foco em automação de comunicação via WhatsApp.
1. Visão Geral
A Clínica Maximiano é um sistema SaaS multi-tenant de automação de atendimento para clínicas de testes respiratórios (SIBO, IMO, ISO, intolerâncias). O app centraliza gestão de pacientes, agendamento de exames, comunicação via WhatsApp e automação de lembretes.
Objetivo principal: reduzir faltas (no-shows) e automatizar o fluxo de comunicação com o paciente — desde o pedido médico até a confirmação de presença — usando templates aprovados na WhatsApp Business Cloud API.
2. Modelo de Dados (Entidades)
O app possui 11 entidades de domínio (além da entidade User nativa):
| Entidade | Função | Campos-chave |
|---|---|---|
| Patient | Pacientes cadastrados | full_name, phone, external_id, clinical_evaluation, risk_classification, conversation_archived, blocked, etapa_atual, fluxo_em_execucao |
| Exam | Pedidos e agendamentos de exames | patient_id, exam_type, status (14 valores), scheduled_date, approval_flow, controle_disparo, paid, uploaded_files, exam_result |
| MessageLog | Histórico de mensagens WhatsApp | patient_id, direction (sent/received), message_type, content, status, whatsapp_message_id, deleted, edited |
| MessageTemplate | Templates de mensagem | name, type (10 valores), content, active |
| Automation | Automações do canvas visual | name, canvas_nodes, canvas_edges, steps, stats |
| AutomationQueue | Fila de mensagens agendadas | patient_id, automation_id, step, scheduled_at, status |
| Notification | Notificações in-app | title, message, type, read, exam_id |
| Tenant | Dados da clínica (multi-tenant) | name, cnpj, whatsapp_number, whatsapp_devices, plan, active |
| ReminderConfig | Configuração de lembretes | reminder_type, days_before, hours_before, active, auto_reinforce |
| SystemUpdate | Changelog de atualizações | title, description, category, area, status |
| SupportLog | Logs do agente de suporte IA | user_email, problem_reported, diagnosis, result |
3. Páginas e Funcionalidades
O app tem 15 páginas acessíveis via sidebar (com RBAC) mais páginas públicas:
| Página | Acesso | O que faz |
|---|---|---|
| Home | Público | Landing page institucional com planos (Consultório, Clínica, Rede) |
| Dashboard | Todos | KPIs: total de exames, confirmados, pendentes; gráficos de status e lembretes; uso de mensagens |
| Chat | Todos | Central de atendimento WhatsApp em tempo real: lista de conversas, janela de 24h, envio de templates, respostas rápidas, anexos |
| Pacientes | Todos | CRUD de pacientes, busca, filtros, avaliação clínica, classificação de risco |
| Exames | Todos | CRUD de exames, 14 status, fluxo de aprovação médica + recepção, upload de pedido médico, agendamento |
| Agenda | Todos | Visão calendário dos exames agendados |
| Fila de Aprovação | Admin | Aprovação médica e de recepção de exames (workflow de 2 etapas) |
| Automações | Admin | Editor visual de automações (canvas com nós e conexões), fila de execução |
| Templates | Admin | Gestão de templates de mensagem (10 tipos: validação, preparo, lembretes, confirmação) |
| Importar CSV | Admin | Importação em massa de pacientes/exames via CSV/Excel |
| Relatório Financeiro | Admin | Relatório de receita por exame, formas de pagamento, status de pagamento |
| Usuários | Admin | Convite e gestão de usuários da clínica (roles: admin/user) |
| Configurações | Todos | Dados da clínica, lembretes, planos/assinatura, exportação de dados |
| Administradores | Super Admin | Gestão de admins multi-tenant |
| Super Admin | Super Admin | Painel master: visão geral de todos os tenants, métricas globais |
4. Funções Backend
10 funções backend (Deno Edge Functions) em base44/functions/:
| Função | Tipo | Responsabilidade |
|---|---|---|
| sendWhatsapp | HTTP | Envia mensagem WhatsApp via ChakraHQ (modo texto ou template). Cria MessageLog, chama API Meta, atualiza status. |
| metaWebhook | Webhook | Recebe mensagens recebidas e status de entrega da Meta Cloud API. Verificação GET + processamento POST. |
| examReminders | Scheduled | Lê exames agendados e envia lembretes por janela de tempo (7d, 48h, 24h, 13h, 2h) + preparo inicial. Anti-duplicação via dispatch_id. |
| processAutomationQueue | Scheduled | Processa fila AutomationQueue: mensagens agendadas das automações do canvas. Rate-limit e anti-duplicação. |
| notifyExamEvent | Entity (Exam) | Cria Notification in-app + envia email a admins quando exame é criado/confirmado/cancelado. |
| checkWhatsappStatus | HTTP | Verifica conectividade com a API ChakraHQ/WhatsApp e retorna status do número. |
| getFinancialData | HTTP | Agrega dados financeiros para o relatório (receita, pagamentos, status). |
| inviteUser | HTTP | Convida usuários para a clínica com role definida. |
| mergePatientDuplicates | HTTP | Funde registros de pacientes duplicados por telefone. |
| fixDuplicateFlags | HTTP | Corrige flags de controle_disparo inconsistentes em exames. |
5. Integrações
Integrações externas configuradas:
| Integração | Provedor | Uso |
|---|---|---|
| WhatsApp Business Cloud API | ChakraHQ (pass-through Meta) | Envio e recebimento de mensagens. Modos: texto (janela 24h) e template (fora da janela). Secrets: CHAKRAHQ_API_KEY, CHAKRAHQ_PLUGIN_ID, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_API_VERSION. |
| MercadoPago | MercadoPago | Pagamentos de assinatura/planos. Secrets: MERCADOPAGO_PUBLIC_KEY, MERCADOPAGO_ACCESS_TOKEN. |
| Core / InvokeLLM | Base44 | Geração de respostas com LLM (usado no agente de suporte IA). |
| Core / SendEmail | Base44 | Envio de emails (notificações a admins, convites). |
| Core / UploadFile | Base44 | Upload de arquivos (pedidos médicos, resultados, anexos de chat). |
| Core / GenerateImage | Base44 | Geração de imagens por IA (disponível, uso pontual). |
6. Automações
3 automações registradas (via list_automations):
| Nome | Tipo | Status | Descrição |
|---|---|---|---|
| Lembretes Automáticos de Exame | Scheduled (5 min) | ⚠️ PAUSADA | Envia lembretes por janela de tempo antes do exame. Função: examReminders. |
| Processar Fila de Automações | Scheduled (5 min) | ⚠️ PAUSADA | Processa mensagens agendadas do canvas de automações. Função: processAutomationQueue. |
| Notificar Exame Criado/Atualizado | Entity (Exam) | ✅ ATIVA | Cria notificação + email a admins em mudanças de status. Função: notifyExamEvent. |
Observação: as duas automações scheduled estão pausadas desde julho/2026 para evitar disparos indevidos antes de validação dos templates na Meta.
7. Segurança e Controle de Acesso
O app implementa isolamento multi-tenant e RBAC:
- ▸Multi-tenant manual: todas as queries de Exams, Patients, MessageLog filtram por tenant_id (do usuário logado).
- ▸RBAC no Layout: admins veem todas as páginas; usuários comuns veem apenas Dashboard, Chat, Pacientes, Exames e Agenda.
- ▸Super Admin: usuário sem tenant_id vê painel master com acesso a Administradores e Super Admin.
- ▸Autenticação nativa Base44 (tokens, sessões, verificação de email) — sem lógica customizada de auth.
- ▸Isolamento de dados por tenant em todas as operações de leitura/escrita.
8. Status Atual e Pontos de Atenção
Estado do sistema em 24/08/2026:
| Área | Status | Observação |
|---|---|---|
| Chat WhatsApp (envio manual) | ✅ Funcionando | Integração ChakraHQ ativa, credenciais configuradas. |
| Recebimento de mensagens (webhook) | ✅ Funcionando | metaWebhook processa mensagens recebidas e status de entrega. |
| Lembretes automáticos | ⚠️ Pausado | examReminders inativa desde jul/2026. Últimos logs (mai/2026) com status failed. |
| Fila de automações | ⚠️ Pausado | processAutomationQueue inativa. |
| Notificação de eventos de exame | ✅ Funcionando | notifyExamEvent ativa — cria notificação + email a admins. |
| Confirmação de exame via chat → template | ❌ Não implementado | Não há gatilho que dispare template ao paciente quando exame é confirmado. |
| Toasts (notificações UI) | ✅ Corrigido | Auto-dismiss e fechamento por clique implementados. |
| Status dinâmico do WhatsApp | ✅ Funcionando | Badge de conexão via checkWhatsappStatus. |
| Envio de templates fora da janela 24h | ✅ Funcionando | TemplateSender integrado ao ChatWindow. |
Principais lacunas: (1) fluxo de confirmação de agendamento não dispara template automático; (2) lembretes automáticos pausados; (3) sem fila de retry para falhas de envio; (4) sem validação automática de templates aprovados na Meta.
Documento gerado automaticamente · Clínica Maximiano · 24/10/2026