[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-96223":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":9,"totalLinesOfCode":9,"stars":12,"forks":13,"watchers":14,"openIssues":14,"contributorsCount":9,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":16,"fork":16,"defaultBranch":17,"hasWiki":16,"hasPages":16,"topics":9,"createdAt":9,"pushedAt":9,"updatedAt":18,"readmeContent":19,"aiSummary":20,"trendingCount":14,"starSnapshotCount":14,"syncStatus":21,"lastSyncTime":9,"discoverSource":22},96223,"DeskcommCRM","melgarafael\u002FDeskcommCRM","melgarafael","Open-source AI sales OS — self-hosted CRM with native AI agents + WhatsApp (WAHA). Open alternative to Kommo, Octadesk & Intercom for any business that sells by chat. MCP-ready, multi-tenant, LGPD.",null,"https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM","TypeScript",1071,460,0,52.99,false,"main","2026-09-20 04:01:32","\u003Cdiv align=\"center\">\n\n🇧🇷 Português · [🇺🇸 English](README.en.md) · [🇪🇸 Español](README.es.md)\n\n\u003Cpicture>\n  \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs\u002Fbrand\u002Fdeskcomm-logo-dark.svg\">\n  \u003Cimg src=\"docs\u002Fbrand\u002Fdeskcomm-logo.svg\" alt=\"Deskcomm CRM\" width=\"420\">\n\u003C\u002Fpicture>\n\n# 🛠️ DeskcommCRM — o Sistema Operacional de Vendas com IA, open source, pro WhatsApp\n\n**Agentes de IA que atendem, qualificam e vendem no WhatsApp — dentro de um CRM open source rodando no seu servidor.**\n**Sem mensalidade, sem feature travada, seus dados com você. A alternativa aberta a Kommo, Octadesk e Intercom.**\n\n[![Next.js 16](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FNext.js-16-black?logo=next.js)](https:\u002F\u002Fnextjs.org)\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-strict-3178c6?logo=typescript)](https:\u002F\u002Fwww.typescriptlang.org)\n[![Supabase](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSupabase-Postgres%2BAuth%2BStorage-3ecf8e?logo=supabase)](https:\u002F\u002Fsupabase.com)\n[![Self-hosted](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fself--hosted-1%20comando-orange)](hostgator-setup-kit\u002F)\n[![CI](https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM\u002Factions\u002Fworkflows\u002Fci.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green)](LICENSE)\n\n[**⚡ Instalar**](#-instalar-na-sua-vps-o-caminho-principal) · [**🔄 Atualizar**](#-atualizar) · [**🧭 Visão**](VISION.md) · [**🏗️ Arquitetura**](ARCHITECTURE.md) · [**🤝 Contribuir**](CONTRIBUTING.md) · [**🗺️ Roadmap**](#%EF%B8%8F-roadmap)\n\n\u003C\u002Fdiv>\n\n---\n\n> ### ☁️ Rode este CRM em produção com 1 comando\n>\n> O DeskcommCRM foi desenvolvido em **parceria com a HostGator**: o [`hostgator-setup-kit\u002F`](hostgator-setup-kit\u002F)\n> instala o CRM completo (app + WhatsApp + banco) numa VPS com um único comando, e o\n> [runbook de produção](docs\u002Frunbooks\u002Fwaha-hostgator.md) já assume esse ambiente.\n>\n> **[👉 Assinar a VPS HostGator com desconto da parceria](https:\u002F\u002Fwww.hostgator.com.br\u002F52708-141-3-52.html)** —\n> datacenter em São Paulo, ideal pro WhatsApp rodando 24\u002F7. *(link de parceiro — assinar por ele apoia o projeto e sai mais barato)*\n>\n> **Ainda não tem servidor?** Rode isto **no seu computador** (macOS, Linux ou WSL). Ele diz\n> qual plano contratar — com os números do runbook, não um \"depende\" — e te devolve o\n> comando certo pro seu caso:\n>\n> ```bash\n> curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fmain\u002Fhostgator-setup-kit\u002Fcomecar.sh | bash\n> ```\n>\n> *(prefere ler antes de executar? clone o repo e rode `bash hostgator-setup-kit\u002Fcomecar.sh` —\n> ele não instala nada sem você confirmar.)*\n\n---\n\n## ⚡ Instalar na sua VPS (o caminho principal)\n\n### 1. Entre na sua VPS\n\nAbra o **Terminal** no seu computador (no Windows, o **PowerShell**; no Mac ou Linux, o\n**Terminal**) e conecte com o IP e a porta que a hospedagem te mandou por e-mail:\n\n```bash\nssh -p PORTA root@SEU_IP\n```\n\nTroque `PORTA` e `SEU_IP` pelos seus. Se a hospedagem não mencionou porta nenhuma, é a padrão\n(22) e você pode omitir: `ssh root@SEU_IP`.\n\nEle pede a senha. **Ao digitar, não aparece nada na tela — nem asteriscos.** Isso não é\ntravamento: é o terminal escondendo a senha. Digite (ou cole) e dê Enter.\n\n> Na primeira conexão ele pergunta `Are you sure you want to continue connecting?` — responda\n> `yes`. É o servidor se apresentando pela primeira vez.\n\n### 2. Rode o instalador\n\nJá dentro da VPS:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM.git\ncd DeskcommCRM\nbash hostgator-setup-kit\u002Finstall.sh\n```\n\nÉ isso. **Você não instala Node, nem pnpm, nem compila nada** — a imagem do app já vem pronta.\nSe faltar Docker, o instalador pergunta e instala sozinho.\n\n### O que você precisa ter em mãos\n\n| Item | Onde conseguir |\n|---|---|\n| **VPS com Docker** | [HostGator](https:\u002F\u002Fwww.hostgator.com.br\u002F52708-141-3-52.html) (parceria) — ou qualquer VPS com Docker. 4 GB de RAM recomendados |\n| **Domínio** | Um registro **A** apontando pro IP da VPS (ex.: `crm.suaempresa.com.br`) |\n| **Banco** | Conta grátis no [supabase.com](https:\u002F\u002Fsupabase.com) — 3 chaves + connection string do **Session pooler** |\n| **IA** | Uma chave de **OpenRouter**, **Anthropic** ou **OpenAI** — o instalador pergunta qual você quer |\n| **WhatsApp** | Seu número, conectado por QR code no onboarding (ou o canal oficial da Meta) |\n\n> 💡 **O Supabase pode ser criado pelo próprio instalador.** Exporte um\n> `SUPABASE_ACCESS_TOKEN` antes de rodar e ele cria o projeto, espera o banco ficar saudável,\n> busca as 4 credenciais e descobre o host do pooler testando conexão real — sem copiar e colar.\n\n### O que o instalador faz por você\n\nEle **pergunta só o que é seu** (domínio, chaves, senha do admin), **valida cada resposta antes\nde seguir** — chave errada ele recusa na hora, não três passos depois — e cuida do resto:\n\n1. Gera todos os segredos técnicos sozinho (você não inventa senha nenhuma).\n2. Cria as extensões do Postgres e aplica o schema completo (`supabase\u002Fbaseline.sql`).\n3. Cria o primeiro admin com o e-mail e a senha que você escolheu.\n4. Sobe a stack inteira com **HTTPS automático** e confere a saúde no fim.\n5. Instala o **cron das automações** (sem ele, as regras QUANDO\u002FSE\u002FENTÃO ficam paradas na fila)\n   e o **agente de atualização**, que é o que faz o botão \"Atualizar agora\" existir na tela.\n\n**Rodar de novo não quebra nada** — o `install.sh` é idempotente: não duplica cron, não recria\nusuário, retoma de onde parou.\n\n> **Modo não-interativo:** copie `.env.hostgator.example` para `.env`, preencha e rode\n> `bash hostgator-setup-kit\u002Finstall.sh --yes`.\n\n### Outra hospedagem? (Hostinger, Coolify, Dokploy, CapRover…)\n\nFunciona. Se a sua VPS já vem com um **proxy reverso próprio** ocupando as portas 80\u002F443, o\ninstalador **detecta isso sozinho** e publica o CRM através dele, em vez de tentar subir um\nCaddy que não caberia. Num caso específico — proxy em `--network host`, como faz a Hostinger —\nele **pergunta em vez de adivinhar**, porque publicar atrás do proxy errado instala \"com\nsucesso\" um site mudo. Detalhes em [`hostgator-setup-kit\u002FREADME.md`](hostgator-setup-kit\u002FREADME.md#vps-que-já-vem-com-proxy-próprio-hostinger-coolify-dokploy).\n\n### Primeiro acesso\n\nAbra `https:\u002F\u002F\u003Cseu-domínio>` (o cadeado leva ~1 min pra aparecer), entre com o admin, e tenha o\n**Google Authenticator** ou **Authy** à mão *se* você quiser ligar a verificação em duas etapas — ela é **opcional** e fica em Configurações › Segurança; o primeiro login **não** a exige. No onboarding,\nescaneie o QR code com o WhatsApp do seu número.\n\n### 🤖 Prefere que uma IA instale pra você?\n\nO repositório traz **guias do assistente** que carregam sozinhos no Claude Code, Codex, Cursor,\nOpenCode ou Antigravity: instalar, montar um cliente por nicho, analisar métricas, afinar o prompt\ndo agente e contribuir. Para tê-los em **qualquer pasta** — inclusive antes de clonar, no seu\ncomputador —, rode uma vez:\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fmain\u002Fscripts\u002Finstalar-guias.sh | bash\n```\n\nDepois abra uma sessão nova do seu assistente e diga *\"quero instalar o CRM na minha VPS\"*: pedir o\nassunto em português aciona o guia certo em qualquer um dos cinco. Para chamar um guia pelo nome,\ncada um tem o seu jeito — `\u002Fdeskcomm-instalar` no Claude Code, no Cursor e no Antigravity;\n`$deskcomm-instalar` no Codex; no OpenCode, peça pelo nome, em linguagem natural.\n\nOs guias **não** se atualizam sozinhos: rodar o mesmo comando de novo traz a versão nova. Para\ndesfazer:\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fmain\u002Fscripts\u002Finstalar-guias.sh | bash -s -- --remover\n```\n\nCom o repositório já clonado, os guias vêm dentro dele (`.agents\u002Fskills\u002F`) e nem isso é preciso. Se\nvocê rodou o comando mesmo assim, saiba que no Claude Code o guia instalado vale mais que o do clone\n— e fica na versão do dia em que rodou, até rodar de novo (ou desfazer).\nTambém funciona o jeito antigo: jogar só a pasta `hostgator-setup-kit\u002F` no chat do **Claude Code**\ndentro da VPS — ele lê o [`CLAUDE.md`](hostgator-setup-kit\u002FCLAUDE.md) do kit e conduz tudo em português.\n\n---\n\n## 🔄 Atualizar\n\nSaiu versão nova? Há dois caminhos, e o primeiro **não exige terminal**.\n\n### Pela tela (recomendado)\n\nQuando existe versão nova, o rodapé do menu lateral acende **\"Nova versão\"** — só pro dono do\nservidor, porque avisar quem não pode atualizar é ruído. Clique e você cai em\n**Configurações → Atualização**, que mostra o que muda, faz **backup do banco sozinha** e\nacompanha cada fase (backup → código → banco → no ar) até terminar. Nada de SSH.\n\nSe a versão nova subir quebrada, o agente **volta pra imagem anterior sozinho** e grava essa\nvolta no `.env` — sem isso, o próximo restart traria o app quebrado de novo, em silêncio.\n\n> Por baixo: o app só registra o pedido; quem executa é o agente que o `install.sh` deixou na\n> sua VPS, num cron que confere **a cada 5 minutos** — então a atualização começa em até 5\n> minutos depois do clique. Se esse agente estiver fora do ar, a tela avisa\n> **\"Atualização automática indisponível\"** e mostra o comando abaixo — ela não finge que deu certo.\n\n### Pelo terminal\n\n```bash\ncd \u002Fcaminho\u002Fdo\u002FDeskcommCRM\nbash hostgator-setup-kit\u002Fupdate.sh\n```\n\nO comando faz, nesta ordem: (1) confere se há mesmo versão nova — se não houver, sai na hora;\n(2) **faz backup do banco antes de tocar em qualquer coisa**; (3) baixa o código novo;\n(4) atualiza o banco re-aplicando o `baseline.sql`, que é idempotente e **auto-curativo**\n(conserta sozinho dados bagunçados por versões antigas); (5) puxa a imagem nova do app;\n(6) confere a saúde no fim.\n\n**O alvo é a última versão publicada** (`v1.2.3`), não o topo da `main` — atualizar leva sempre\na uma versão marcada e descrita no [`CHANGELOG.md`](CHANGELOG.md), nunca a um commit não testado.\nEle **recusa** voltar pra uma versão anterior à instalada (isso desligaria coisas que você já tem);\npra isso existe `--force`, de propósito.\n\n**Coisas normais que você vai ver:** um monte de `already exists` \u002F `multiple primary keys` na\nparte do banco — **é esperado e inofensivo**, são coisas que já existiam. O script filtra esse\nruído e mostra `✓ banco atualizado`. Se o banco estiver ocupado com o CRM atendendo, ele aplica de\nnovo sozinho (até 3 passadas) e conta isso na tela — isso vale a partir da atualização seguinte à\nque instalar esta correção. Se aparecer `⚠ Apareceram avisos no banco que NÃO são os esperados`, aí sim guarde a\nmensagem: o **fim** da saída diz o que fazer em cada caso (repetir com `--force` quando foi o banco\nocupado, declarar `SUPABASE_DB_ADMIN_URL` quando foi permissão). Restaurar o backup é o último recurso.\n\n**Deu ruim?** `bash hostgator-setup-kit\u002Frestore.sh` volta pro backup.\n**Quer só diagnosticar?** `bash hostgator-setup-kit\u002Fhealthcheck.sh`.\n\n> ⚠️ **Numa instalação antiga que ainda não tem o agente da tela**, rode `update.sh` **duas\n> vezes**: a primeira execução ainda é a do script velho (que baixa o novo); a segunda instala\n> o agente e liga o botão.\n\nPasso a passo em linguagem simples: [`docs\u002FATUALIZANDO.md`](docs\u002FATUALIZANDO.md).\n\n### Outros comandos do kit\n\n| Script | Função |\n|---|---|\n| `install.sh` | Instala tudo (idempotente — pode rodar de novo) |\n| `update.sh` | Atualiza pra versão nova, com backup automático |\n| `backup.sh` | Backup do banco + sessões de WhatsApp |\n| `restore.sh` | Restaura um backup |\n| `reset-password.sh` | Redefine a senha de um usuário |\n| `reset-mfa.sh` | Remove o MFA de quem perdeu o celular |\n| `healthcheck.sh` | Diagnóstico de todos os serviços de uma vez |\n\n> **Backup importa:** o plano grátis do Supabase **não faz backup sozinho**. Vale agendar\n> `backup.sh` no cron diariamente. O `update.sh` já roda um backup antes de cada atualização.\n\n---\n\n## ✨ O que é\n\n**Deskcomm** vem de **Desk** (mesa) + **comm** (comércio): **o comercial de mesa** — toda a operação de vendas do seu negócio numa mesa só, operada por pessoas e agentes de IA juntos.\n\nO projeto nasceu como CRM de e-commerce e a comunidade o levou muito além: hoje roda em **clínicas, imobiliárias, infoprodutos, agências, lojas e prestadores de serviço** — qualquer negócio que vende pelo WhatsApp. O produto acompanhou essa virada e virou um **sistema operacional de vendas**: agentes de IA com RAG por tenant atendem, qualificam, movem leads no funil, disparam automações e sabem a hora de passar pra um humano — com o CRM inteiro exposto via **MCP** pros agentes operarem de verdade. A história completa está em [`VISION.md`](VISION.md).\n\n### Diferenciais\n\n- 🤖 **Agentes de IA que operam o CRM** — RAG por tenant, skills que o agente executa sozinho durante o atendimento, memória da operação, análise de sentimento, handoff IA→humano auditado, IA como assignee de primeira classe e teto de gasto por organização. Não é chatbot decorativo: o agente atende, qualifica e move o funil.\n- 🔁 **Nada morre no silêncio** — follow-up que retoma a conversa esfriada (com tempo adaptativo e gatilhos por etapa do funil), radar do que está em risco de morrer sem resposta, e central de avisos pro que precisa de decisão humana.\n- 🧠 **Agentes que se auto-aprimoram** — conversas resolvidas viram conhecimento novo; a tela de **Evolução da IA** mostra se o agente está melhorando, onde erra e o que falta ensinar; **Propostas** são melhorias que a IA sugere pra si mesma, aplicáveis como versão nova — sempre com gate humano.\n- 🧩 **Multi-nicho por design** — vocabulário configurável por pipeline: lead vira *Cliente*, *Paciente* ou *Comprador*; won vira *Pago*, *Agendado* ou *Fechado*. O mesmo core serve e-commerce (nosso berço, com integração Nuvemshop), clínica, imobiliária ou infoproduto.\n- 💬 **WhatsApp de duas formas** — por **QR code** (WAHA, multi-número, com anti-banimento: throttle + jitter + janela de horário) ou pelo **canal oficial da Meta** (Cloud API, com templates aprovados e sincronizados). Mídia via Storage, STOP detection.\n- 🔀 **Escolha sua IA** — OpenRouter, Anthropic ou OpenAI, decidido na instalação e trocável depois pela tela, **por parte do sistema** (o que conversa não precisa ser o que indexa).\n- 👥 **Governança de atendimento** — RBAC server-side de verdade, atribuição\u002Ftransferência auditada, fila com rodízio, roteamento automático por intenção e escopo de visualização por papel.\n- 🏢 **Multi-tenant + LGPD by-design** — RLS em toda tabela tenant-aware com teste de isolamento como gate de CI; anonimização preferida sobre delete; audit append-only com retenção 5 anos.\n- 🖥️ **Self-hosted de verdade** — seus dados na sua VPS; instalação e atualização com 1 comando (ou 1 clique); sem versão paga, sem feature travada.\n\n### 🔌 Webhooks & Automações\n\nTodo tenant pode criar **fontes de captação**: um endereço público (`\u002Fapi\u002Fv1\u002Fwebhooks\u002Fin\u002F\u003Ctoken>`) que recebe leads de landing pages, formulários próprios ou ferramentas como Zapier\u002Fn8n via POST (JSON ou `application\u002Fx-www-form-urlencoded`) e já entra direto no funil\u002Festágio escolhido — sem código, sem integração customizada por tenant. Em cima dessas fontes (e dos outros eventos do CRM — lead mudou de etapa, ganhou tag, chegou mensagem no WhatsApp), o tenant monta **automações**: regras no formato QUANDO\u002FSE\u002FENTÃO que disparam ações como adicionar tag, mover o lead no funil, atribuir a um atendente, mandar uma mensagem de WhatsApp ou avisar outro sistema via webhook de saída.\n\nNa UI, tudo mora em **Webhooks** na sidebar (visível só pra quem tem papel `manager`\u002F`admin`). A tela tem três abas: **Receber dados** (criar fonte, copiar o endereço\u002Fformulário pronto, disparar um lead de teste, ver os últimos recebimentos), **Automações** (montar a regra, que sempre nasce pausada até você revisar e ligar) e **Atividade** (timeline de cada execução, com o resultado de cada ação e reenvio manual quando uma chamada externa falha).\n\nPor baixo, cada evento vira uma linha em `event_log` — nenhum trigger de banco faz chamada HTTP diretamente. Quem drena essa fila é a rota `\u002Fapi\u002Fv1\u002Fcron\u002Fevent-log-drain`, chamada a cada minuto. **O `install.sh`\u002F`update.sh` já configuram esse cron sozinhos** — sem ele, as automações são criadas normalmente mas nunca rodam.\n\n---\n\n## 🖥️ O que você opera (as telas)\n\n| Grupo | Telas |\n|---|---|\n| **Atendimento** | **Inbox** (conversas de WhatsApp, você e a IA lado a lado) · **Radar** (quem esfriou e ainda está aberto) · **Respostas rápidas** |\n| **CRM** | **Kanban** (onde cada negócio está no funil) · **Contatos** · **Funis** (etapas, vocabulário do negócio e motivos de perda) |\n| **Agente de IA** | **Agentes** · **Follow-ups** · **Roteadores** · **Provedores** e **Credenciais** · **Conhecimento** (RAG) · **Memória** · **Skills** · **Casos** · **Alertas** · **Propostas** · **Execuções** · **Uso e orçamento** |\n| **Canais** | **Conexões** (QR ou canal oficial da Meta, com saúde, reconexão e templates) · **Nuvemshop** · **Webhooks** |\n| **Análise** | **Desempenho** (funil e performance por atendente) · **Evolução da IA** · **Audit Log** |\n| **Organização** | **Equipe** · **Distribuição de atendimento** · **Organização** · **LGPD** · **API Tokens** · **Segurança** (MFA, códigos de recuperação, sessões) · Perfil, Notificações, Billing |\n\nToda tela tem porta na navegação — o CI reprova tela que existe mas em que só se chega digitando a URL.\n\n---\n\n## 🧱 Stack\n\n| Camada | Escolha | Por quê |\n|---|---|---|\n| **Frontend** | Next.js 16 App Router (Turbopack) + React 19 + TypeScript 6 estrito | Server Components + Route Handlers no mesmo repo |\n| **Estilo** | Tailwind + shadcn\u002Fui (`new-york`, neutral) | Customizável sem lock-in |\n| **DB** | Supabase (Postgres + RLS + `vector`) | Multi-tenant nativo, embedding pra RAG |\n| **Auth** | Supabase Auth via `@supabase\u002Fssr` | Cookie SameSite=Strict, HttpOnly |\n| **Realtime** | Supabase Realtime | postgres_changes + broadcast |\n| **Storage** | Supabase Storage (URLs assinadas) | Bucket privado `whatsapp-media` |\n| **WhatsApp** | WAHA Plus (engine NOWEB) + Meta Cloud API | QR pra começar rápido; canal oficial pra escala |\n| **Filas** | `event_log` table + workers (cron) | Trigger de banco nunca faz HTTP |\n| **Rate limit** | Upstash Redis (sliding window) | Serverless, free tier suficiente |\n| **AI** | Vercel AI SDK v7 — OpenRouter, Anthropic, OpenAI e Google | Instalador pergunta qual; troca depois pela tela |\n| **Validação** | Zod | Input externo, env, payloads |\n| **Observability** | Sentry (scrub em erro, transação, span e breadcrumb) | Telemetria opt-in no install |\n| **Hospedagem** | VPS com Docker (HostGator\u002FSP na parceria) | App + WhatsApp + workers na sua máquina |\n\nDetalhes: [`ARCHITECTURE.md`](ARCHITECTURE.md).\n\n---\n\n## 🧑‍💻 Desenvolvimento (só pra contribuir com o código)\n\n> ⚠️ **Se você quer USAR o CRM, não é aqui** — use o [instalador da VPS](#-instalar-na-sua-vps-o-caminho-principal).\n> Esta seção é pra quem vai mexer no código.\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM.git\ncd DeskcommCRM\n\nnvm use                     # Node 22\nnpm install -g pnpm && pnpm install\n\ncp .env.example .env.local  # guia completo em docs\u002FSETUP.md\n\ndocker compose up -d        # WAHA local (opcional em dev sem WhatsApp)\n\n# Schema: aplique o baseline, NÃO as migrations.\n# As migrations 0001-0009 e 0013 são stubs `SELECT 1;` — a cadeia não sobe do zero.\n# O schema real vive no baseline.sql, o mesmo que o install.sh aplica na VPS.\n# `supabase db push` \"passa\" e deixa o banco vazio.\nsupabase link --project-ref \u003Cseu-ref>\n\n# Num projeto Supabase NOVO, habilite antes as extensões que o schema usa —\n# sem elas o baseline para em `type public.vector does not exist`.\npsql \"$SUPABASE_DB_URL\" -v ON_ERROR_STOP=1 -c \\\n  'create extension if not exists vector with schema public;\n   create extension if not exists citext with schema public;\n   create extension if not exists pg_trgm with schema public;'\n\npsql \"$SUPABASE_DB_URL\" -v ON_ERROR_STOP=1 -f supabase\u002Fbaseline.sql\n\npnpm dev\n```\n\nApp: \u003Chttp:\u002F\u002Flocalhost:3000> · Health check: \u003Chttp:\u002F\u002Flocalhost:3000\u002Fapi\u002Fv1\u002Fhealth>\n\n[`docs\u002FSETUP.md`](docs\u002FSETUP.md) é o tutorial completo de **todas as integrações** (Supabase, WAHA, provedores de IA, Upstash, Sentry, Resend, Nuvemshop) — ~60–90 min do zero ao app rodando.\n\n---\n\n## 📁 Estrutura\n\n```\nDeskcommCRM\u002F\n├── app\u002F                    # Next.js App Router\n│   ├── (admin)\u002F            # Rotas super-admin (impersonate, tenants)\n│   ├── (public)\u002F           # Login, recovery\n│   ├── app\u002F                # Rotas autenticadas: inbox, radar, kanban, contacts,\n│   │                       #   connections, ai\u002F*, integrations, metrics, lgpd,\n│   │                       #   audit, team, settings\n│   └── api\u002Fv1\u002F             # API REST canônica (196 route handlers)\n├── components\u002F             # React (ui\u002F, inbox\u002F, kanban\u002F, shell\u002F, ...)\n├── lib\u002F                    # supabase\u002F, waha\u002F, channels\u002F, ai\u002F, agent-engine\u002F,\n│                           #   api\u002F, routing\u002F, navigation\u002F, env.ts\n├── workers\u002F                # consumers de event_log (IA, RAG, LGPD, mídia, rotinas)\n├── supabase\u002Fmigrations\u002F    # SQL versionado (+ baseline.sql pro self-host)\n├── tests\u002F{e2e,unit,invariants,shell}\u002F\n├── scripts\u002F                # seeds, qa-waves, manutenção\n├── docs\u002F                   # PRDs, specs, runbooks, SETUP.md, ATUALIZANDO.md\n└── hostgator-setup-kit\u002F    # instalação e atualização self-host\n```\n\n---\n\n## 🧪 Testes\n\n```bash\npnpm typecheck     # tsc --noEmit -p tsconfig.typecheck.json (inclui tests\u002F)\npnpm lint          # eslint next\u002Fcore-web-vitals\npnpm test:unit     # Vitest (NÃO inclui tests\u002Finvariants\u002F**)\npnpm test:db       # Postgres efêmero + baseline install\u002Fupdate + invariantes\npnpm test:e2e      # Playwright (requer dev server)\n```\n\n**Estes checks são obrigatórios** pra mergear na `main`. A lista abaixo já disse \"quatro\" e depois \"cinco\" — **meça, não confie nela**:\n\n```bash\ngh api repos\u002Fmelgarafael\u002FDeskcommCRM\u002Fbranches\u002Fmain\u002Fprotection \\\n  --jq '.required_status_checks.contexts|join(\", \")'\n# em 2026-08-14: verify, build-and-size, invariants, e2e, imagens-ok\n```\n\n\n| Check | O que faz |\n|---|---|\n| `verify` | typecheck + lint + `lint:channels` + `test:unit` + `test:shell` |\n| `invariants` | sobe um Postgres limpo, aplica o `baseline.sql` em modo **install** e depois em modo **update** — as duas passadas com `ON_ERROR_STOP=1`, que é o que torna a segunda uma prova de idempotência e não só um \"terminou\" —, e roda os invariantes de RBAC, atribuição, escopo, roteamento, follow-up, webhooks e automações |\n| `build-and-size` | `pnpm build` em Node 22 |\n| `e2e` | sobe Supabase local, aplica o `baseline.sql` e roda **48 das 49 specs** Playwright pelo frontend |\n| `imagens-ok` | reprova quando qualquer uma das três imagens Docker (`app`, `worker`, `scheduler`) não constrói — é o artefato que o self-hoster instala |\n\nA única spec fora do `e2e` é `vps-fresh-onboarding` — ela precisa de WAHA + Redis + Resend + Nuvemshop de verdade. Ela é a **P0** da nossa doutrina de QA visual, então `e2e` verde **não** prova a jornada de instalação fresca; essa se prova numa VPS.\n\nEntre os invariantes está o **teste de isolamento RLS**: cria 2 organizações, simula os claims JWT pelo mesmo caminho `auth.uid()` \u002F `fn_user_org_ids()` que as policies de produção usam, e prova que um usuário da org A enxerga **zero linhas** da org B em `conversations`, `messages`, `contacts` e `crm_leads`. Antes disso, um caso de controle prova que as linhas da org B realmente existem — sem ele, o teste passaria com a tabela vazia.\n\n---\n\n## 📚 Documentação\n\n| Doc | O que tem |\n|---|---|\n| [`hostgator-setup-kit\u002FREADME.md`](hostgator-setup-kit\u002FREADME.md) | **Instalação self-host** — o kit, os scripts, as hospedagens com proxy próprio |\n| [`docs\u002FATUALIZANDO.md`](docs\u002FATUALIZANDO.md) | **Como atualizar** sua instalação, em linguagem simples |\n| [`VISION.md`](VISION.md) | **Visão e posicionamento** — o que o projeto é, no que acredita e pra onde vai |\n| [`CHANGELOG.md`](CHANGELOG.md) | O que mudou em cada versão — **leia a seção da versão antes de atualizar** |\n| [`docs\u002FSETUP.md`](docs\u002FSETUP.md) | Setup de desenvolvimento, passo a passo de todas as integrações |\n| [`docs\u002Fwhite-label.md`](docs\u002Fwhite-label.md) | **Instalar para clientes** — trocar a marca, uma instalação por cliente vs compartilhada, revenda |\n| [`docs\u002Frunbooks\u002Fwaha-hostgator.md`](docs\u002Frunbooks\u002Fwaha-hostgator.md) | Runbook de WAHA em produção (dimensionamento, recuperação) |\n| [`docs\u002Frunbooks\u002Fdeploy.md`](docs\u002Frunbooks\u002Fdeploy.md) | Deploy em produção |\n| [`CLAUDE.md`](CLAUDE.md) | Convenções não-negociáveis (leitura obrigatória pra contribuir) |\n| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Visão de 1 página da arquitetura |\n| [`docs\u002Findex.md`](docs\u002Findex.md) | Índice dos 157 documentos, com regra de precedência |\n| [`docs\u002Fprd\u002F`](docs\u002Fprd\u002F) · [`docs\u002Fspecs\u002F`](docs\u002Fspecs\u002F) | PRDs e specs técnicas (schema SQL, payloads, MCP, governança) |\n\n---\n\n## 🤝 Contribuindo\n\nEsse projeto é open source pra comunidade. Toda contribuição é bem-vinda — desde fix de typo em doc até feature nova.\n\n**Antes de abrir PR:**\n\n1. Leia [`CLAUDE.md`](CLAUDE.md) (~5 min) — convenções não-negociáveis (multi-tenancy, RLS, audit, LGPD).\n2. Leia [`CONTRIBUTING.md`](CONTRIBUTING.md) — fluxo de branches, commits, epic-executor.\n3. Siga o [Código de Conduta](CODE_OF_CONDUCT.md).\n\n**Fluxo curto:**\n\n```bash\ngit checkout -b feat\u002Fshort-slug\n# implementa + testes\npnpm typecheck && pnpm lint && pnpm lint:channels && pnpm test:unit && pnpm test:shell && pnpm build\npnpm test:db   # precisa de Docker — é o job `invariants`, obrigatório no merge\ngit commit -m \"feat(escopo): descrição\"\n# abre PR — o template já traz o checklist de Definition of Done\n```\n\nEssas duas linhas são **tudo o que dá para rodar na sua máquina**, de propósito: rodar só metade e\ndescobrir o resto como surpresa vermelha depois de horas de espera é a pior primeira experiência\nque este repositório sabe entregar.\n\nDois gates obrigatórios **não** cabem aí e só rodam no CI: o `e2e` (precisa de Supabase local) e\no `imagens-ok` (constrói as três imagens Docker). Verde na sua máquina não é verde no merge.\n\n**Definition of Done:** typecheck zero, lint zero, testes relevantes verdes, RLS testada se toca tabela tenant-aware, audit log emitido em mutações, migration versionada **+ apêndice no `baseline.sql`** se muda schema (senão a mudança não chega em quem se auto-hospeda). Detalhes em [`CLAUDE.md`](CLAUDE.md#definition-of-done).\n\n---\n\n## 🐛 Reportando bugs\n\nAbra uma [issue](https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fissues\u002Fnew\u002Fchoose) — o template pede o que precisamos (ambiente, `\u002Fapi\u002Fv1\u002Fhealth`, steps). Rodar `bash hostgator-setup-kit\u002Fhealthcheck.sh` e colar a saída ajuda muito.\n\nPra **vulnerabilidades de segurança**, **NÃO abra issue pública** — use o [relato privado de vulnerabilidades](https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fsecurity\u002Fadvisories\u002Fnew). Detalhes em [`SECURITY.md`](SECURITY.md).\n\n---\n\n## 🗺️ Roadmap\n\n### ✅ Entregue\n\n- **Fundação & plataforma** — auth (MFA pra admin), multi-tenancy com RLS + teste de isolamento, RBAC 4 papéis, audit log append-only, onboarding de tenant.\n- **Atendimento WhatsApp** — inbox 3 painéis em tempo real, conexões multi-número por **QR (WAHA)** ou **canal oficial da Meta** (templates aprovados e sincronizados), mídia via Storage, anti-banimento (throttle + jitter + janela de horário), STOP detection.\n- **CRM & pedidos** — kanban com vocabulário configurável por nicho (fractional indexing), gestão de funis pela tela, customer 360, contatos, tags, integração Nuvemshop.\n- **IA nativa** — agentes com RAG por tenant (pgvector), **skills** que o agente executa sozinho, **memória da organização**, roteador de intenção por número, análise de sentimento, handoff IA→humano, teto de gasto por org, MCP server interno.\n- **Escolha de provedor de IA** — OpenRouter, Anthropic ou OpenAI, decidido na instalação e trocável por parte do sistema pela tela.\n- **Follow-up vivo** — retomada de conversa esfriada com tempo adaptativo, gatilhos por etapa do funil e por caso, fila com rodízio, e o Radar do que corre risco de morrer sem resposta.\n- **LGPD** — export e redact via workers, anonimização em cascata, consentimento auditado.\n- **Self-host** — `hostgator-setup-kit` (app + WhatsApp + banco com 1 comando), `baseline.sql` auto-curativo, **atualização pela tela** com backup automático, runbook de produção.\n- **Webhooks & automação** — fontes de captação + regras QUANDO\u002FSE\u002FENTÃO + gatilhos pra sistemas externos.\n- **Governança de atendimento** — RBAC server-side em toda a API, atribuição e transferência auditadas (IA como assignee de 1ª classe), visualização por papel (RLS) + métricas por atendente, roteamento automático com fila e painel de gestão, e contrato de governança pra agentes de IA externos ([`docs\u002Fspecs\u002F14`](docs\u002Fspecs\u002F14-contrato-governanca-agentes-externos.md)).\n- **Operação visível** — motivo da retenção anti-ban traduzido na conversa, central de avisos com severidade, aviso de mensagem presa, controle de proteção de envio (janela\u002Fritmo\u002Fteto), capacidades declaradas do agente e propostas do flywheel aplicáveis como versão nova (com gate humano).\n\n### 🔮 Próximo\n\n- **MCP público** — capabilities do CRM expostas pro ecossistema de agentes: plugue o agente que quiser e ele opera o Deskcomm.\n- **Templates por nicho** — pipelines e vocabulários prontos pra clínica, imobiliária, infoproduto e serviços (e-commerce já entregue).\n- **Integrações** — VTEX e Shopify via adapter pattern (Nuvemshop já entregue).\n- **Identity probabilística** — unificação de contatos entre canais.\n\n---\n\n## 💬 Comunidade\n\n- **Discussões:** [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fdiscussions) — pra perguntas, ideias, showcase.\n- **Issues:** [GitHub Issues](https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fissues) — bugs e tasks.\n- **Instagram:** [@melgarafael](https:\u002F\u002Fwww.instagram.com\u002Fmelgarafael)\n- **YouTube:** [youtube.com\u002F@melgarafael](https:\u002F\u002Fwww.youtube.com\u002F@melgarafael)\n\n---\n\n## 📜 Licença\n\nDistribuído sob a licença **MIT** — veja [`LICENSE`](LICENSE). Você pode usar, modificar\ne distribuir livremente, inclusive comercialmente. O software é fornecido **\"como está\",\nsem garantias** (ver cláusula de isenção no `LICENSE`).\n\n---\n\n## 🛟 Suporte & responsabilidades (self-host)\n\nEste é um projeto **self-host**: cada pessoa roda o CRM na **própria infraestrutura**\n(VPS, banco Supabase e chave de IA próprios). Isso implica:\n\n- **Suporte é comunitário e \"as-is\".** Dúvidas e bugs entram como\n  [Issues](https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fissues) ou\n  [Discussions](https:\u002F\u002Fgithub.com\u002Fmelgarafael\u002FDeskcommCRM\u002Fdiscussions). Não há SLA nem\n  suporte garantido — é open source mantido por boa vontade.\n- **Você é responsável pela sua instalação.** Atualizações não são automáticas (você clica\n  ou roda `update.sh` quando quiser), e manter\u002Fbackup do seu servidor é com você.\n- **LGPD — atenção:** quem **hospeda** a instância é o **controlador** dos dados pessoais\n  ali tratados (clientes, conversas, pedidos), com as obrigações legais decorrentes. Os\n  mantenedores do projeto **não são** controladores nem operadores da sua instância, e não\n  têm acesso ao seu banco, ao seu WhatsApp nem ao seu storage. A única coisa que pode sair\n  da sua máquina para nós é o relatório de erro descrito abaixo — e só se você deixar.\n- **Telemetria (Sentry):** o `install.sh` **pergunta** durante a instalação e respeita a\n  sua resposta; em modo não-interativo, sem `SENTRY_DSN` definido, a telemetria fica\n  **desligada**. Se você aceitar o Sentry da comunidade, o que é enviado são **relatórios\n  de erro** (stack trace) com CPF, telefone e e-mail substituídos, cabeçalhos sensíveis\n  removidos, e token de webhook\u002Fconvite redigido da URL — **sem** rastreamento de\n  performance e **sem** replay de sessão, que ficam em 0 nesse caminho. Para desligar a\n  qualquer momento: `SENTRY_DSN=off` no `.env`. Para mandar ao **seu** Sentry (aí sim com\n  performance e replay): `SENTRY_DSN=\u003Cseu-dsn>`. O que é redigido, e por quê, está em\n  [`lib\u002Fsentry\u002Fscrub.ts`](lib\u002Fsentry\u002Fscrub.ts); a resolução do DSN em\n  [`lib\u002Fsentry\u002Fdsn.ts`](lib\u002Fsentry\u002Fdsn.ts).\n\n---\n\n## 🙏 Agradecimentos\n\n- **WAHA** ([devlikeapro](https:\u002F\u002Fwaha.devlikeapro.com\u002F)) — engine WhatsApp.\n- **Supabase** — Postgres + Auth + Storage + Realtime numa stack só.\n- **HostGator** — parceria de infraestrutura que tornou o self-host de 1 comando possível.\n- **Anthropic**, **OpenAI** e **OpenRouter** — os provedores de IA que o CRM sabe usar.\n- **shadcn\u002Fui** — base de componentes.\n- A comunidade que nos levou do e-commerce pra clínicas, imobiliárias, infoprodutos e além — vocês definiram o que este projeto é.\n\n---\n\n\u003Cdiv align=\"center\">\n\n**Built with ☕ in Brasil** · **Made for the community**\n\nSiga o desenvolvimento: [Instagram](https:\u002F\u002Fwww.instagram.com\u002Fmelgarafael) · [YouTube](https:\u002F\u002Fwww.youtube.com\u002F@melgarafael)\n\n\u003C\u002Fdiv>\n","DeskcommCRM 是一个开源、可自托管的智能销售操作系统，专为通过 WhatsApp 进行销售的业务设计。它集成了原生 AI 代理（自动接待、线索筛选与销售跟进）、WhatsApp 集成（基于 WAHA）、多租户支持、LGPD 合规能力，并具备 MCP（Model Context Protocol）就绪架构。技术栈基于 TypeScript、Next.js 和 Supabase（PostgreSQL + Auth + Storage），支持一键部署到 VPS 或本地开发环境。适用于中小型企业、电商客服团队及独立销售顾问等需私有化部署、数据自主且依赖聊天渠道成交的场景。",2,"trending"]