Como Construir um CRM Completo com Claude Code

Guia passo a passo para construir um CRM B2B de vendas usando Claude Code como copiloto de desenvolvimento.

Este guia documenta o processo real usado para construir o KopkAI CRM - um sistema completo de gestão de vendas B2B com pipeline Kanban, automações visuais, integrações com Gmail e WhatsApp, relatórios avancados e muito mais.

Indice

1. Visao Geral do Projeto
2. Stack Tecnologico
3. Setup Inicial do Projeto
4. Base de Dados com Prisma
5. Autenticacao e Controlo de Acessos
6. Estrutura de Paginas e Rotas
7. API REST Completa
8. Pipeline Kanban (Drag & Drop)
9. Gestao de Contactos
10. Tarefas e Calendario
11. Integracao Gmail
12. Integracao WhatsApp
13. Sistema de Automacoes Visuais
14. Relatorios e Business Intelligence
15. Notificacoes em Tempo Real
16. Importacao CSV e Exportacao PDF
17. Calculadora de Orcamentos
18. Tema Dark/Light e UX
19. Deploy com Docker
20. Dicas para Trabalhar com Claude Code

1. Visao Geral do Projeto

O CRM que vamos construir tem estas funcionalidades principais:

• Pipeline de vendas com 12 estagios e board Kanban drag-and-drop
• Gestao de contactos com perfis completos, tags e historico
• Tarefas com tipos (chamada, reuniao, follow-up, email), datas e atribuicao
• Calendario com reunioes ligadas a deals
• Integracao Gmail - ler e enviar emails diretamente no CRM
• Integracao WhatsApp - enviar mensagens via API
• Automacoes visuais - workflow builder com triggers, condicoes e acoes
• Relatorios avancados - 16+ graficos com filtros e exportacao PDF
• Calculadora de orcamentos para projetos
• Sistema de convites com roles (Admin, Manager, Vendedor)
• API REST completa para integracoes externas (n8n, Zapier, etc.)
• Tempo real - presenca de utilizadores, notificacoes, atualizacoes live

2. Stack Tecnologico

Prompt para Claude Code:

Cria um novo projeto Next.js com TypeScript, Tailwind CSS e App Router.
Instala: prisma, @prisma/client, next-auth, sonner, lucide-react,
date-fns, recharts, @dnd-kit/core, @dnd-kit/utilities, cmdk
Configura o Tailwind e cria a estrutura base do projeto.

3. Setup Inicial do Projeto

3.1 Criar o Projeto

npx create-next-app@latest crm --typescript --tailwind --app --src-dir
cd crm

3.2 Instalar Dependencias

# Core
npm install @prisma/client next-auth sonner

# UI
npm install lucide-react class-variance-authority clsx tailwind-merge
npm install @radix-ui/react-dialog @radix-ui/react-select @radix-ui/react-tabs
# (ou usar o CLI do shadcn: npx shadcn@latest init)

# Funcionalidades
npm install recharts @dnd-kit/core @dnd-kit/utilities
npm install date-fns cmdk jspdf html2canvas-pro
npm install @xyflow/react  # para automacoes visuais

# Dev
npm install -D prisma @types/node

3.3 Configurar shadcn/ui

npx shadcn@latest init
npx shadcn@latest add button card input label select tabs dialog badge
npx shadcn@latest add popover command calendar dropdown-menu

Prompt para Claude Code:

Configura o shadcn/ui no projeto. Adiciona os componentes base:
button, card, input, label, select, tabs, dialog, badge, popover,
command, calendar, dropdown-menu, sonner (toaster).

3.4 Estrutura de Pastas

src/
  app/
    (auth)/          # Paginas publicas (login, convite)
    (dashboard)/     # Paginas protegidas
    api/             # Rotas API
    layout.tsx       # Layout raiz
    globals.css
  components/
    ui/              # Componentes shadcn/ui
    ...              # Componentes do CRM
  hooks/             # Custom hooks
  lib/               # Logica de negocio e utilitarios
  types/             # Definicoes TypeScript
prisma/
  schema.prisma      # Schema da base de dados

4. Base de Dados com Prisma

4.1 Inicializar Prisma

npx prisma init --datasource-provider postgresql

4.2 Schema Principal

O schema e o coracao do CRM. Aqui esta a estrutura completa:

Prompt para Claude Code:

Cria o schema Prisma para um CRM de vendas B2B com estes modelos:

1. User - com roles (ADMIN, MANAGER, SELLER), Google OAuth fields,
   Gmail tokens, last seen
2. Contact - nome, email, telefone, empresa, cargo, fonte, tags, notas
3. Deal - titulo, valor, estagio (12 estagios de pipeline), probabilidade,
   contacto associado, responsavel, follow-up, datas de cada estagio,
   nicho, fonte, proposta, motivo de perda
4. Task - titulo, descricao, tipo (CALL/MEETING/FOLLOWUP/EMAIL/OTHER),
   status, data limite, deal e contacto associados
5. Meeting - data, tipo (primeira reuniao/follow-up), link, duracao,
   concluida, deal associado
6. MeetingRecord - link de gravacao, titulo, deal associado
7. Activity - log de alteracoes (tipo, dados antes/depois, user, deal/contacto)
8. Invite - token de convite com role, email opcional, expiracao
9. ApiToken - tokens API com hash, prefixo, expiracao
10. Automation - workflow JSON, status (ACTIVE/INACTIVE/ARCHIVED)
11. AutomationExecution - log de execucoes com resultados por step
12. ScheduledAutomation - agendamento cron para automacoes
13. Budget - historico da calculadora com form data e resultados

Adiciona indices para performance nas queries mais comuns.
Use enums para: Role, DealStage (12 estagios), TaskType, TaskStatus,
MeetingType, AutomationStatus.

4.3 Os 12 Estagios do Pipeline

enum DealStage {
  NOVA_LEAD
  CONTACTADA
  REUNIAO_AGENDADA
  FOLLOW_UP
  NEGOCIACAO
  VA                    // Valor Acrescentado
  CONTRATO_ASSINADO
  CLIENTE_FECHADO
  CLIENTE_PERDIDO
  ADORMECIDO
  NAO_QUALIFICADO
  SEM_INTERESSE
}

4.4 Aplicar o Schema

npx prisma db push    # Desenvolvimento rapido
# ou
npx prisma migrate dev --name init   # Com historico de migracoes

4.5 Singleton do Prisma Client

// src/lib/prisma.ts
import { PrismaClient } from "@prisma/client";

const globalForPrisma = global as unknown as { prisma: PrismaClient };

export const prisma =
  globalForPrisma.prisma ||
  new PrismaClient({ log: ["error"] });

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

5. Autenticacao e Controlo de Acessos

5.1 Configurar NextAuth com Google

Prompt para Claude Code:

Configura NextAuth.js com Google Provider. Os utilizadores so podem
registar-se com um convite valido. Na primeira vez que fazem login
com Google, o sistema verifica se existe um convite valido (por cookie
ou por email) e cria o utilizador com o role do convite.

Inclui no JWT: id, role, name, email, image.
Session maxAge: 24 horas.

Ficheiros necessarios:

• src/lib/auth.ts - configuracao NextAuth
• src/lib/session.ts - helpers de sessao
• src/app/api/auth/[...nextauth]/route.ts - handler
• src/middleware.ts - protecao de rotas
• src/types/next-auth.d.ts - tipos customizados

5.2 Middleware de Protecao

// src/middleware.ts
import { NextRequest, NextResponse } from "next/server";
import { withAuth } from "next-auth/middleware";

const authMiddleware = withAuth({ pages: { signIn: "/login" } });

export default async function middleware(req: NextRequest) {
  // Permitir API tokens
  const authHeader = req.headers.get("authorization");
  if (authHeader?.startsWith("Bearer ")) {
    return NextResponse.next();
  }
  return authMiddleware(req, null as never);
}

export const config = {
  matcher: [
    "/((?!login|convite|api/auth|_next/static|_next/image|favicon.ico).*)",
  ],
};

5.3 Sistema de Convites

O fluxo de onboarding:

1. Admin cria convite com role e email opcional
2. Sistema gera link unico (/convite?token=...)
3. Novo utilizador abre o link, aceita o convite
4. Token e guardado em cookie
5. Utilizador faz login com Google
6. NextAuth verifica o cookie, cria o user com o role do convite

Prompt para Claude Code:

Cria o sistema de convites:
- API POST /api/admin/invites - criar convite (admin only)
- API GET /api/admin/invites - listar convites
- API DELETE /api/admin/invites/[id] - revogar
- API POST /api/admin/invites/validate - validar token
- API POST /api/admin/invites/set-cookie - guardar token em cookie
- Pagina /convite - aceitar convite e redirecionar para login
- No NextAuth signIn callback, verificar cookie e criar user

5.4 Controlo de Acessos por Role

// Padrao usado em todas as API routes
export async function GET(req: NextRequest) {
  const user = await getAuthContext(req); // verifica sessao ou API token
  if (!user) return NextResponse.json({ error: "Nao autorizado" }, { status: 401 });

  const isSeller = user.role === "SELLER";
  const userFilter = isSeller ? { assignedToId: user.id } : {};

  // Sellers so veem os seus deals; Admins/Managers veem tudo
  const deals = await prisma.deal.findMany({ where: userFilter });
  return NextResponse.json(deals);
}

6. Estrutura de Paginas e Rotas

6.1 Layout Base

Prompt para Claude Code:

Cria o layout do dashboard com:
- Sidebar esquerda fixa com navegacao (Pipeline, Contactos, Tarefas,
  Calendario, Equipa, Relatorios, Calculadora, Configuracoes)
- Header com barra de pesquisa, notificacoes, e perfil do utilizador
- Area de conteudo principal com scroll
- Suporte mobile com sidebar colapsavel
- Indicadores de utilizadores online

6.2 Paginas do CRM

7. API REST Completa

7.1 Padrao CRUD para Entidades

Prompt para Claude Code:

Para cada entidade (deals, contatos, tarefas), cria API routes com:
- GET /api/[entidade] - listar com paginacao, filtros, ordenacao
- POST /api/[entidade] - criar
- GET /api/[entidade]/[id] - detalhe
- PUT /api/[entidade]/[id] - atualizar
- DELETE /api/[entidade]/[id] - eliminar

Cada rota deve:
1. Verificar autenticacao (sessao ou API token)
2. Aplicar filtros de role (seller so ve os seus)
3. Validar inputs
4. Registar atividade no log (Activity model)
5. Retornar dados com relacoes necessarias

7.2 Exemplo: API de Deals

// src/app/api/deals/route.ts - GET (listar)
export async function GET(req: NextRequest) {
  const user = await getAuthContext(req);
  if (!user) return NextResponse.json({ error: "Nao autorizado" }, { status: 401 });

  const { searchParams } = new URL(req.url);
  const stage = searchParams.get("stage");
  const assignedTo = searchParams.get("assignedTo");

  const isSeller = user.role === "SELLER";
  const where = {
    ...(isSeller ? { assignedToId: user.id } : {}),
    ...(stage ? { stage: stage as DealStage } : {}),
    ...(assignedTo ? { assignedToId: assignedTo } : {}),
  };

  const deals = await prisma.deal.findMany({
    where,
    include: { contact: true, assignedTo: true },
    orderBy: { createdAt: "desc" },
  });

  return NextResponse.json(deals);
}

7.3 Operacoes Bulk

POST /api/deals/bulk - operacoes em massa (mover estagio, editar campo, eliminar)
POST /api/contatos/bulk - importacao em massa de contactos

7.4 API Tokens para Integracoes

O CRM suporta autenticacao por API token para integracoes com n8n, Zapier, etc.:

Authorization: Bearer crm_abc123...

Prompt para Claude Code:

Cria o sistema de API tokens:
- Geracao com prefixo "crm_" + random bytes
- Armazenamento com hash SHA-256 (nunca guardar o token em texto)
- Validacao no middleware
- Tracking de ultimo uso
- Expiracao opcional
- Interface de gestao em Configuracoes

8. Pipeline Kanban (Drag & Drop)

Esta e a funcionalidade central do CRM.

8.1 Componente Kanban

Prompt para Claude Code:

Cria um board Kanban para o pipeline de vendas com @dnd-kit:

- 12 colunas (uma por estagio do pipeline)
- Cards de deals com: titulo, valor, contacto, badges (nicho, fonte)
- Drag and drop entre colunas (muda o estagio do deal)
- Drag and drop dentro da mesma coluna (reordenar)
- Contagem de deals e soma de valor por coluna
- Campos configuraveis nos cards (escolher quais campos mostrar)
- Auto-save ao arrastar
- Animacao fluida

Os estagios ativos (Nova Lead ate Contrato Assinado) aparecem
no board. Os inativos (Cliente Fechado, Perdido, etc.) aparecem
como filtros.

8.2 Vista Tabela Alternativa

Alem do Kanban, a pagina Pipeline tem uma vista de tabela com:

• Ordenacao por qualquer coluna
• Selecao multipla para operacoes bulk
• Filtros por estagio, responsavel, nicho, fonte
• Pesquisa por titulo

8.3 Formulario de Deal

O formulario de deal e o componente mais complexo (~94KB):

• Informacoes basicas (titulo, valor, estagio, probabilidade)
• Contacto associado (criar novo ou selecionar existente)
• Nicho e fonte com opcao de adicionar novos
• Follow-up scheduling
• Proposta (link + ficheiro)
• Reunioes associadas
• Historico de atividade
• Auto-save nos campos individuais

9. Gestao de Contactos

Prompt para Claude Code:

Cria o modulo de contactos com:

1. Pagina /contatos com:
   - Tabela com pesquisa, filtros (tags, fonte, empresa)
   - Botao criar contacto
   - Click para abrir detalhe

2. Pagina /contatos/[id] com:
   - Perfil completo (nome, email, telefone, empresa, cargo)
   - Tags editaveis
   - Lista de deals associados
   - Timeline de atividades
   - Emails trocados (integracao Gmail)
   - Notas

3. Dialog de contacto com:
   - Edicao inline de todos os campos
   - Adicionar/remover tags
   - Ver deals rapidamente

10. Tarefas e Calendario

10.1 Sistema de Tarefas

Prompt para Claude Code:

Cria o modulo de tarefas:
- Lista com filtros por tipo, status, responsavel, deal
- Criacao rapida com tipo, titulo, data limite
- Marcar como concluida com um click
- Tarefas atrasadas destacadas a vermelho
- Associacao a deals e contactos
- Vista Kanban opcional (por status)

10.2 Calendario

Prompt para Claude Code:

Cria uma pagina de calendario para reunioes:
- Vista mensal com navegacao
- Reunioes mostradas nos dias corretos
- Click num dia para ver detalhes
- Popup com info da reuniao e link para o deal
- Cores diferentes por tipo de reuniao
- Marcador de reunioes concluidas vs pendentes

11. Integracao Gmail

11.1 Setup OAuth

1. Criar projeto no Google Cloud Console
2. Ativar Gmail API
3. Criar credenciais OAuth 2.0
4. Configurar redirect URI: /api/gmail/callback
5. Guardar GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET no .env

11.2 Implementacao

Prompt para Claude Code:

Integra o Gmail no CRM:

1. OAuth flow:
   - POST /api/gmail/auth - redirecionar para Google
   - GET /api/gmail/callback - receber tokens e guardar no User
   - POST /api/gmail/disconnect - revogar acesso
   - GET /api/gmail/status - verificar se esta conectado

2. Funcionalidades:
   - GET /api/gmail/emails?contactEmail=x - buscar emails de um contacto
   - GET /api/gmail/threads/[id] - ver thread completa
   - POST /api/gmail/send - enviar email
   - Refresh automatico do access token quando expira

3. UI:
   - Componente EmailList - inbox do contacto
   - Componente EmailCompose - compor email
   - Componente EmailDetail - ver thread
   - Botao de conectar Gmail nas Configuracoes

12. Integracao WhatsApp

Prompt para Claude Code:

Integra WhatsApp via Unipile API:
- Configuracao de conta nas Definicoes (API key, account ID)
- Envio de mensagens para contactos com telefone
- Validacao de numero de telefone
- Status de conexao
- Usado tambem nas automacoes (acao "enviar WhatsApp")

13. Sistema de Automacoes Visuais

Este e o modulo mais avancado do CRM.

13.1 Arquitetura

src/lib/automations/
  types.ts       # Tipos: Trigger, Condition, Action, Step
  engine.ts      # Motor de execucao
  evaluator.ts   # Avaliacao de condicoes
  actions.ts     # Handlers de acoes
  variables.ts   # Substituicao de variaveis {{deal.title}}
  scheduler.ts   # Agendamento cron
  template.ts    # Templates pre-feitos

13.2 Workflow Editor Visual

Prompt para Claude Code:

Cria um editor visual de workflows com @xyflow/react:

1. Tipos de nos:
   - TRIGGER (quando algo acontece)
   - CONDITION (se/senao)
   - ACTION (fazer algo)

2. Triggers disponiveis (14):
   - Schedule (diario/semanal/mensal/custom cron)
   - Deal: stage changed, field updated, created, deleted
   - Contact: field updated, created, deleted
   - Task: created, completed, overdue
   - Meeting: created, completed

3. Condicoes:
   - Comparacao de campos (equals, contains, greater_than, etc.)
   - Condicoes de data (is_today, in_future, etc.)
   - Logica AND/OR
   - Variaveis: deal.*, contact.*, task.*, meeting.*

4. Acoes (7):
   - Editar deal (mudar campo, mudar estagio)
   - Editar contacto
   - Criar tarefa
   - Criar deal
   - Criar contacto
   - Enviar webhook (HTTP POST)
   - Enviar WhatsApp

5. Variaveis de template:
   - {{deal.title}}, {{deal.value}}, {{contact.name}}, etc.
   - Substituicao automatica na execucao

6. UI:
   - Canvas com nos arrastáveis
   - Painel lateral de configuracao por step
   - Botao de testar execucao
   - Historico de execucoes com resultado por step

13.3 Motor de Execucao

// Fluxo simplificado:
async function executeAutomation(automation, triggerData) {
  const execution = await createExecution(automation.id);

  for (const step of automation.steps) {
    if (step.type === "condition") {
      const result = evaluateCondition(step.config, triggerData);
      // seguir branch true ou false
    }
    if (step.type === "action") {
      await executeAction(step.config, triggerData);
    }
    await logStepResult(execution.id, step.id, result);
  }

  await completeExecution(execution.id);
}

14. Relatorios e Business Intelligence

14.1 Dashboard Principal

Prompt para Claude Code:

Cria o dashboard principal (/) com:
- KPI cards: revenue total, deals ganhos, taxa conversao, ticket medio
- Grafico de pipeline por valor
- Deals por nicho (bar chart)
- Atividade recente (timeline)
- Top deals em aberto

14.2 Pagina de Relatorios

Prompt para Claude Code:

Cria a pagina de relatorios com Recharts incluindo 16+ graficos:

Filtros: periodo, utilizador, nicho, fonte, estagio

Graficos:
1. Funil de pipeline (conversao entre estagios)
2. Revenue por periodo (line chart)
3. Deals ganhos vs perdidos (bar chart)
4. Taxa de conversao por fonte
5. Taxa de conversao por nicho
6. Ticket medio por periodo
7. Tempo medio ate fecho (time-to-cash)
8. Time-to-cash por nicho
9. Duracao media por estagio
10. Novos deals por periodo
11. Revenue por membro de equipa
12. Deals por membro de equipa
13. Distribuicao por estagio (pie chart)
14. Follow-ups cumpridos vs atrasados
15. Reunioes realizadas por periodo
16. Atividade por hora do dia (heatmap)

Cada secao de graficos pode ser exportada para PDF.

14.3 Exportacao PDF

// Usa html2canvas para capturar graficos + jsPDF para gerar PDF
async function exportToPDF(selectedCharts: string[]) {
  const pdf = new jsPDF("p", "mm", "a4");
  for (const chartId of selectedCharts) {
    const element = document.getElementById(chartId);
    const canvas = await html2canvas(element);
    pdf.addImage(canvas, "PNG", x, y, width, height);
  }
  pdf.save("relatorio.pdf");
}

15. Notificacoes em Tempo Real

15.1 Sistema de Eventos

Prompt para Claude Code:

Cria um sistema de notificacoes in-app:

1. Gerador de notificacoes baseado em dados:
   - Follow-ups atrasados (severidade alta)
   - Tarefas atrasadas (severidade alta)
   - Reunioes do dia (severidade media)
   - Deals parados ha mais de 7 dias (severidade baixa)

2. API GET /api/notifications - retorna notificacoes do utilizador

3. Componente NotificationBell no header:
   - Badge com contagem de nao lidos
   - Popover com lista de notificacoes
   - Click numa notificacao navega para o deal/tarefa
   - Opcao de dispensar notificacoes

4. Sistema de eventos para atualizacoes em tempo real:
   - Quando um deal muda, emitir evento
   - Componentes subscrevem a eventos relevantes
   - Polling periodico como fallback

15.2 Presenca de Utilizadores

// Hook de heartbeat - envia ping a cada 30s
useEffect(() => {
  const interval = setInterval(() => {
    fetch("/api/user/heartbeat", { method: "POST" });
  }, 30000);
  return () => clearInterval(interval);
}, []);

// Mostra utilizadores online no header
const isOnline = (lastSeen: Date) =>
  Date.now() - lastSeen.getTime() < 60000; // online se visto ha menos de 1 min

16. Importacao CSV e Exportacao PDF

16.1 Importacao CSV

Prompt para Claude Code:

Cria um sistema de importacao CSV:

1. API POST /api/import com suporte para:
   - Importacao de contactos (nome, email, telefone, empresa, tags)
   - Importacao de deals (com contactos, reunioes, estagios)
   - Detecao automatica de separador (virgula ou ponto-e-virgula)
   - Detecao de duplicados por email ou telefone
   - Criacao automatica de contactos ao importar deals
   - Suporte para multiplas reunioes por deal
   - Validacao por linha com report de erros

2. API GET /api/import?template=contacts|deals
   - Download de template CSV com todos os campos

3. UI na pagina de Configuracoes:
   - Escolher tipo (contactos ou deals)
   - Download do template
   - Upload do ficheiro
   - Resultado com contagem: importados, ignorados, erros
   - Referencia de campos disponiveis

17. Calculadora de Orcamentos

Prompt para Claude Code:

Cria uma calculadora de orcamentos para projetos de automacao:

1. Formulario com:
   - Numero de automacoes
   - Complexidade por automacao (simples/media/complexa)
   - Custos de ferramentas (HTTP requests, APIs externas)
   - Horas de consultoria
   - Custos de parceiros
   - Pacote de suporte
   - Urgencia (normal/media/super urgente)
   - Garantia

2. Calculo automatico com:
   - Preco base por automacao
   - Multiplicadores de complexidade
   - Surcharge de urgencia
   - Opcoes de split de pagamento

3. Geracao de PDF com resumo
4. Historico de orcamentos guardados

18. Tema Dark/Light e UX

18.1 Configurar Dark Mode

Prompt para Claude Code:

Configura suporte dark/light mode com next-themes:
- ThemeProvider no layout raiz
- Toggle na pagina de Configuracoes (visual, nao texto)
- Preferencia guardada na base de dados (sincroniza entre dispositivos)
- Tailwind classes com dark: prefix

18.2 Command Palette (Cmd+K)

Prompt para Claude Code:

Cria um command palette com cmdk:
- Atalho Cmd+K (ou Ctrl+K)
- Pesquisa global: deals, contactos, tarefas
- Navegacao rapida para qualquer pagina
- Acoes rapidas: criar deal, criar tarefa
- Resultados agrupados por tipo

18.3 Undo/Redo

// Sistema de undo para operacoes destrutivas
const { undo } = useUndo();

// Ao eliminar um deal, mostrar toast com botao "Desfazer"
toast("Deal eliminado", {
  action: { label: "Desfazer", onClick: () => undo(dealData) },
});

19. Deploy com Docker

19.1 Dockerfile

FROM node:20-alpine AS base

# Dependencias
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Build
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npx prisma generate
RUN npm run build

# Producao
FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/prisma ./prisma
COPY --from=builder /app/node_modules/.prisma ./node_modules/.prisma
COPY --from=builder /app/node_modules/@prisma ./node_modules/@prisma

USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]

19.2 Variaveis de Ambiente Necessarias

# Base de Dados
DATABASE_URL="postgresql://..."
DIRECT_URL="postgresql://..."  # Conexao direta (sem pooler)

# Auth
NEXTAUTH_SECRET="gerar-com-openssl-rand-base64-32"
NEXTAUTH_URL="<https://teu-dominio.com>"

# Google OAuth
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."
GOOGLE_REDIRECT_URI="<https://teu-dominio.com/api/gmail/callback>"

19.3 Fluxo de Deploy

# No servidor
git pull
docker build -t meu-crm:latest .
docker service update meu_crm --force

# Ou com docker-compose
docker compose up -d --build

20. Dicas para Trabalhar com Claude Code

20.1 Como Estruturar os Prompts

Sê especifico e contextual:

# Mau
"Cria um formulario de deals"

# Bom
"Cria um formulario de deals com os seguintes campos:
- Titulo (obrigatorio)
- Valor (numerico, formatado em EUR)
- Estagio (select com os 12 estagios do pipeline)
- Contacto (combobox com pesquisa, opcao de criar novo)
- Nicho (select com opcao de adicionar novo)
- Proximo follow-up (date picker)
- Probabilidade (slider 0-100%)
- Notas (textarea)
O formulario deve ter auto-save nos campos individuais
e mostrar toast de confirmacao."

20.2 Trabalhar Incrementalmente

Nao peças tudo de uma vez. Constrói feature a feature:

1. Comeca pelo schema da base de dados
2. Depois as API routes CRUD basicas
3. Depois os componentes UI pagina a pagina
4. Depois as integracoes (Gmail, WhatsApp)
5. Depois os extras (automacoes, relatorios, importacao)

20.3 Dar Contexto ao Claude Code

Quando pedes alteracoes, referencia ficheiros existentes:

"No componente kanban-board.tsx, adiciona suporte para reordenar
cards dentro da mesma coluna com drag and drop. Usa o @dnd-kit
que ja esta instalado. Mantem o comportamento existente de mover
entre colunas."

20.4 Debugging com Claude Code

Quando algo nao funciona:

"O endpoint GET /api/deals esta a retornar 500.
O erro no terminal e: 'PrismaClientKnownRequestError: Invalid
`prisma.deal.findMany()` invocation'.
Verifica o schema e a query e corrige."

20.5 Pedir Revisoes e Otimizacoes

"Revisa a pagina de relatorios e otimiza:
1. As queries Prisma estao a fazer muitas chamadas separadas?
   Consolida em menos queries.
2. Os graficos estao a re-renderizar desnecessariamente?
   Adiciona memoizacao onde fizer sentido.
3. A exportacao PDF esta lenta? Investiga o bottleneck."

20.6 Padrao de Trabalho Eficiente

1. Descreve o objetivo claramente
2. Deixa o Claude Code explorar o codebase antes de editar
3. Testa localmente apos cada mudanca
4. Itera rapidamente - pede ajustes se o resultado nao for perfeito
5. Faz commits frequentes para poder reverter
6. Pede deploy quando a feature estiver pronta

20.7 Exemplos de Prompts Uteis para CRM

# Adicionar nova funcionalidade
"Adiciona suporte para tags nos deals, similar ao que ja existe
nos contactos. As tags devem ser editaveis inline e aparecer como
badges no card do Kanban."

# Corrigir bug
"Quando arrasto um deal de 'Nova Lead' para 'Contactada', o estagio
muda mas a data de 'contactada' nao e preenchida. Corrige para que
a data do estagio seja registada automaticamente."

# Melhorar UX
"O formulario de deal esta muito longo. Organiza-o em tabs ou
sections colapsaveis para melhorar a experiencia."

# Integracao
"Cria um webhook que dispare quando um deal muda para 'Cliente Fechado'.
O webhook deve enviar um POST com os dados do deal para uma URL
configuravel nas definicoes."

# Performance
"A pagina de pipeline esta lenta com 500+ deals. Investiga e otimiza.
Possíveis melhorias: virtualizacao, paginacao, ou lazy loading dos cards."

Resumo Final

Construir um CRM completo com Claude Code e um processo iterativo. As chaves do sucesso:

1. Planear o schema primeiro - a base de dados e a fundacao
2. Construir feature a feature - nao tentar tudo de uma vez
3. Testar a cada passo - nao acumular mudancas sem verificar
4. Ser especifico nos prompts - quanto mais contexto, melhor o resultado
5. Usar o deploy continuo - commit, push, build, test em producao

O CRM descrito neste guia levou aproximadamente 2-3 semanas de trabalho com Claude Code, resultando em 50+ API routes, 36 componentes, 14 modelos de dados, e um sistema completo de vendas B2B pronto para producao.

Construido com Claude Code por KopkAI

Preferes que isto seja feito por nós? Conhece o nosso serviço de agentes de IA para vendas e atendimento.

Guias relacionados

• Claude e Prospecção Automática
• Quando Comprar vs Quando Construir com Claude
• Claude e o teu CRM