Manual de desenvolvimento

ClinicForge
IA — MVP

Guia completo de 5 dias para construção do MVP com Claude Code. Dê baixa em cada item conforme avança — o progresso fica salvo no navegador.

Duração
5 dias
Blocos
38
Stack
Next.js · Supabase · N8N · Z-API
Antes
do código
Pré-desenvolvimento
Contas, chaves e ambiente. Sem isso, o Claude Code não avança no Dia 1.
📄
Supabase
~15 min
Crie o projeto. Anote a URL do projeto, a anon key e a service_role key.
supabase.com →
▲
Vercel + GitHub
~15 min
Crie o repositório no GitHub e conecte na Vercel. Deploy automático a cada push.
vercel.com →
🤖
Chave de IA
~10 min
Claude (Anthropic) — recomendado para português. A chave é cadastrada pela própria clínica (BYOK).
console.anthropic.com →
⚡
N8N
~30 min
VPS barata (Hostinger, Contabo ~R$30/mês) com Docker, ou N8N Cloud ($20/mês). Deixe rodando já.
n8n.io →
💬
Z-API (WhatsApp)
~20 min
Crie a conta e conecte um chip de teste via QR. Anote o instance_id, instance_token e client_token.
z-api.io →
💻
Claude Code
~10 min
Instale o Claude Code no terminal ou no VS Code. Crie a pasta do projeto com o CLAUDE.md na raiz.
docs.claude.com →
⚠️
N8N e Z-API primeiro. São os que demoram mais para configurar. Deixe o N8N rodando antes do Dia 1.
VS
Code
Extensões do VS Code
Instale antes de começar o Dia 1. Algumas são obrigatórias para o Claude Code funcionar bem.
Como instalar:Ctrl+Shift+X → buscar o nome ou colar o ID
Obrigatórias — sem essas o workflow trava
🤖
Claude Code
anthropics.claude-code
O agente de IA que vai construir o projeto. Lê o CLAUDE.md e executa os blocos dos prompts diários.
Obrig.
🔍
ESLint
dbaeumer.vscode-eslint
Mostra erros de linting em tempo real. Essencial para o TypeScript estrito que o CLAUDE.md exige.
Obrig.
✨
Prettier
esbenp.prettier-vscode
Formatação automática ao salvar. Mantém o código gerado pelo Claude Code consistente.
Obrig.
🌊
Tailwind CSS IntelliSense
bradlc.vscode-tailwindcss
Autocomplete e preview de cores para classes Tailwind. Indispensável com Shadcn/ui.
Obrig.
📄
GitLens
eamodio.gitlens
Visualiza histórico e diffs. Essencial para acompanhar os commits do Claude Code.
Obrig.
Recomendadas
📄
DotENV
mikestead.dotenv
Syntax highlighting no .env.local. Facilita configurar as variáveis de ambiente.
Recom.
🚨
Error Lens
usernamehw.errorlens
Mostra erros diretamente na linha do código, sem precisar passar o mouse.
Recom.
⚡
Thunder Client
rangav.vscode-thunder-client
Cliente REST dentro do VS Code para testar os endpoints da API ClinicForge.
Recom.
💡
Configuração rápida do settings.json: adicione "editor.formatOnSave": true e "editor.defaultFormatter": "esbenp.prettier-vscode". O código do Claude Code vai se formatar automaticamente a cada Save.
Dia
01
Fundação + Central do Agente + Voz
Setup técnico, auth, perfis, permissões, layout responsivo, onboarding, FAQ, central do agente e assistente por voz.
Bloco 1
Setup do projeto e dependências
Fundação▾
  • Next.js 14 com App Router e TypeScript estrito
  • Tailwind CSS + Shadcn/ui inicializado
  • Zustand, React Hook Form, Zod instalados
  • Cliente Supabase configurado (lib/supabase) para Server e Client Components
  • Estrutura de pastas conforme seção 16 do CLAUDE.md. Projeto sobe sem erros.
Bloco 2
Schema do banco e RLS multi-tenant
Crítico▾
  • Schema completo da seção 15 implementado como migrations do Supabase
  • RLS ativo em TODAS as tabelas, filtrando por tenant_id
  • Teste de isolamento multi-tenant passa (usuário do tenant A não lê dados do B)
🔒
Não avance sem o teste de isolamento passando. Um bug de multi-tenant com dados de saúde é catastrofico legalmente.
Bloco 3
Autenticação e 5 perfis de usuário
Fundação▾
  • Login, logout, recuperação de senha, sessão persistente via Supabase Auth
  • 5 perfis: Master, Admin, Administrativo, Profissional, Recepção
  • Middleware protegendo rotas por perfil. Páginas /login e /recuperar-senha responsivas.
Bloco 4
Permissões data-driven
Crítico▾
  • Permissões vêm da tabela permissions — nunca hardcoded
  • Helper lib/permissions com função can(user, module, action)
  • Exclusão (X) só para Admin e Master. Profissional vê só dados "próprios".
🎉 Fechamento do Dia 1
  • Teste de isolamento multi-tenant confirmado passando
  • Você revisou e aprovou antes de começar o Dia 2
Dia
02
Agenda + Pacientes + Profissionais
As entidades que o agente vai usar para agendar. O helper de slots criado aqui é reutilizado no Dia 4.
Bloco 1
Pacientes — CRUD completo
Dados▾
  • Ficha completa: nome, CPF, telefone, email, nascimento, convênio, endereço, observações
  • Flags: is_first_visit, consentimento LGPD, opt_out, ai_memory_json
  • Busca, filtros, paginação. Profissional vê só os próprios pacientes.
Bloco 2
Profissionais, disponibilidade e helper de slots
Crítico▾
  • split_percent INDIVIDUAL por profissional. CRM/CRO, especialidade, foto, bio.
  • Helper de slots: interseção de horário da clínica + disponibilidade + exceções. Reutilizado pela agenda E pelo agente no Dia 4.
Bloco 3
Agenda visual com lock anti-conflito
Crítico▾
  • Agenda visual (FullCalendar) — visão dia/semana por profissional e sala
  • Lock pessimista (SELECT FOR UPDATE) + constraint única. Teste de double booking passa.
🎉 Fechamento do Dia 2
  • Teste de double booking e isolamento confirmados passando
  • Agenda testada em mobile (375px). Você aprovou.
Dia
03
CRM + Leads + Follow-up + GUT
A timeline é o coração: toda conversa do WhatsApp cairá aqui no Dia 4.
Bloco 1
Pipeline de leads e endpoint de captação
Leads▾
  • Pipeline Kanban: Novo → Qualificado → Agendado → Cliente ativo → Perdido
  • Endpoint POST /api/v1/leads/inbound — recebe leads do site/WordPress
Bloco 2
Timeline + Tarefas + GUT dinâmico
Núcleo▾
  • Timeline unificada (8 tipos): Mensagem · Ligação · Consulta · Orçamento · Nota · Tarefa · Follow-up · Status
  • GUT dinâmico: recalcula com o tempo, lista se reordena automaticamente (1–125)
🎉 Fechamento do Dia 3
  • Timeline sólida (base para o WhatsApp no Dia 4). GUT dinâmico funcionando.
Dia
04
WhatsApp + Agente de IA funcionando
O agente começa a agendar pacientes de verdade. Teste cada conversa como se fosse o paciente.
⚠️ Pré-requisitos: Z-API com número conectado. N8N rodando. Chave de IA ativa.
Bloco 1
Camada de abstração de WhatsApp
Crítico▾
  • lib/whatsapp com interface única. Normaliza webhooks Z-API e Meta Oficial.
  • Toda mensagem salva em conversations e na timeline do CRM
Bloco 2
Agendamento pela IA + emergência
Núcleo▾
  • Consulta o helper de slots. Oferece no máximo 2 horários. Cria agendamento com lock anti-conflito.
  • Emergência médica: detecta sinais → NÃO agenda → orienta SAMU/PS → alerta médico (GUT 125).
  • Pausa da IA: secretária responde → IA pausa naquele chat. Reativa por botão.
🎉 Fechamento do Dia 4
  • Teste ponta a ponta: lead entra → IA qualifica → apresenta médico → agenda → confirma → registra no CRM
  • Emergência médica e pausa da IA testados e passando
Dia
05
API + Webhooks + IA sobre dados + Deploy
Abrir o sistema para integrações e colocar no ar com smoke test em produção.
Bloco 1
API REST + Webhooks + Deploy
Go live▾
  • Endpoints /api/v1: patients, appointments, leads, professionals, available-slots
  • Vercel: CI/CD, variáveis de ambiente de produção. Supabase em produção com RLS.
  • Smoke test em produção: criar lead de teste e rodar a jornada completa
Pós
MVP
Sprints semanais pós-MVP
1 semana por sprint, validando com clientes reais entre cada entrega.
Sprint 1
Pagamento + NFS-e
Controle de pagamento (todas as formas)
Recibo em PDF
NFS-e via hub (Nuvem Fiscal / Focus NFe)
Sprint 2
Voz no WhatsApp + Check-ins
Whisper para transcrição de áudio
Check-ins semanais por médico
Programa de indicação com link rastreado
Sprint 3
Marketing + Financial Intelligence
Gerador de conteúdo com IA
Publicação: Instagram, LinkedIn, WordPress
Dashboard Financial Intelligence
Sprint 4
Agenda avançada + Feegow/MedX
Grade sugerida por parâmetros
Overbooking inteligente
Integração Feegow / MedX