🇧🇷 葡萄牙语 · 🇺🇸 English · 🇪🇸 Español

🛠️ DeskcommCRM —— 面向 WhatsApp 的开源 AI 销售操作系统

可在 WhatsApp 上接待客户、筛选线索并完成销售的 AI Agent——运行在部署于你自己服务器上的开源 CRM 中。 没有月费，没有功能锁定，数据由你掌控。这是 Kommo、Octadesk 和 Intercom 的开放替代方案。

⚡ 安装 · 🔄 更新 · 🧭 愿景 · 🏗️ 架构 · 🤝 贡献 · 🗺️ 路线图

---

☁️ 使用一条命令在生产环境运行此 CRM

DeskcommCRM 是与 HostGator 合作开发的：hostgator-setup-kit/ 可通过一条命令，在 VPS 上安装完整 CRM（应用 + WhatsApp + 数据库）；生产运行手册也已基于该环境编写。

👉 通过合作折扣订购 HostGator VPS —— 数据中心位于圣保罗，适合让 WhatsApp 全天候 24/7 运行。(合作链接——通过该链接订购既能支持项目，也更便宜)

还没有服务器？ 请在你的电脑上运行以下命令（macOS、Linux 或 WSL）。它会根据运行手册中的实际数据告诉你该选择什么套餐——不是一句“视情况而定”——并返回适合你情况的正确命令：

curl -fsSL https://raw.githubusercontent.com/melgarafael/DeskcommCRM/main/hostgator-setup-kit/comecar.sh | bash

(想先阅读再执行？请克隆仓库并运行 bash hostgator-setup-kit/comecar.sh ——未经你的确认，它不会安装任何内容。)

---

⚡ 在你的 VPS 上安装（主要路径）

在你的电脑上打开终端（Windows 使用 PowerShell；Mac 或 Linux 使用 Terminal），然后使用主机服务商通过邮件发送给你的 IP 地址和端口进行连接：

将 PORTA 和 SEU_IP 替换成你自己的值。如果主机服务商未提及端口，则使用默认端口（22），可省略端口：ssh root@SEU_IP。

系统会要求输入密码。输入时屏幕上不会显示任何内容——甚至不会出现星号。 这并非卡住，而是终端正在隐藏密码。输入（或粘贴）后按 Enter。

首次连接时，系统会询问 Are you sure you want to continue connecting? ——回答 yes。这是服务器首次向你提供身份信息。

进入 VPS 后：

git clone https://github.com/melgarafael/DeskcommCRM.git
cd DeskcommCRM
bash hostgator-setup-kit/install.sh

就是这样。你无需安装 Node、pnpm，也无需编译任何东西——应用镜像已经准备就绪。如果缺少 Docker，安装程序会询问并自动安装。

你需要准备的内容

项目	获取方式
带 Docker 的 VPS	HostGator（合作伙伴）——或任何支持 Docker 的 VPS。建议 4 GB RAM
域名	一条指向 VPS IP 的 A 记录（例如：crm.suaempresa.com.br）
数据库	在 supabase.com 创建免费账户——提供 3 个密钥及 Session pooler 的 connection string
AI	一个 OpenRouter、Anthropic 或 OpenAI 密钥——安装程序会询问你希望使用哪一个
WhatsApp	你的号码，在引导流程中通过 QR Code 连接（或使用 Meta 官方通道）

💡 Supabase 可由安装程序自行创建。 在运行前导出一个 SUPABASE_ACCESS_TOKEN，它就会创建项目、等待数据库健康就绪、获取 4 项凭据，并通过真实连接测试发现 pooler 主机——无需复制粘贴。

安装程序为你完成的工作

它只询问属于你的信息（域名、密钥、管理员密码），并且在继续之前验证每一项回答——错误的密钥会立刻被拒绝，而不是在三步之后才报错——其余工作全部由它处理：

1. 自动生成所有技术密钥（你无需自己编造任何密码）。
2. 创建 Postgres 扩展并应用完整 Schema（supabase/baseline.sql）。
3. 使用你指定的电子邮件和密码创建首个管理员。
4. 以自动 HTTPS启动整套服务，并在最后检查健康状态。
5. 安装自动化 cron 任务（没有它，WHEN/IF/THEN 规则会一直停留在队列中）以及更新 Agent，后者使界面中的“立即更新”按钮能够生效。

重复运行不会破坏任何内容——install.sh 是幂等的：不会重复创建 cron，不会重复创建用户，会从上次中断之处继续。

**非交互模式：**将 .env.hostgator.example 复制为 .env，填写内容后运行 bash hostgator-setup-kit/install.sh --yes。

使用其他主机？（Hostinger、Coolify、Dokploy、CapRover……）

同样可用。如果你的 VPS 已自带一个占用 80/443 端口的反向代理，安装程序会自行检测，并通过该代理发布 CRM，而非尝试启动无法容纳的 Caddy。对于一种特定情况——如 Hostinger 所采用的运行在 --network host 中的代理——它会询问而不是猜测，因为接入错误的代理会导致一个“安装成功”却没有响应的网站。详情见 hostgator-setup-kit/README.md。

打开 https://<你的域名>（锁形图标大约需要 1 分钟才会出现），使用管理员账号登录；如果你希望启用双因素认证，请准备好 Google Authenticator 或 Authy——它是可选项，位于“设置 › 安全”；首次登录不要求启用它。在引导流程中，用你号码对应的 WhatsApp 扫描 QR Code。

🤖 希望让 AI 为你安装？

将 hostgator-setup-kit/ 文件夹放入运行在 VPS 中的 Claude Code 聊天窗口，然后说：“帮我安装 DeskcommCRM”。它会读取工具包中的 CLAUDE.md——其中包含操作步骤和已识别的常见陷阱——并用葡萄牙语引导完成整个过程。

---

有新版本发布？有两种方式，第一种无需终端。

当存在新版本时，侧边菜单底部会亮起 “新版本”——仅对服务器所有者显示，因为向无权更新的人发出通知只是噪声。点击后将进入设置 → 更新页面；页面会展示变更内容、自动备份数据库，并跟踪每个阶段（备份 → 代码 → 数据库 → 上线），直至完成。无需 SSH。

如果新版本上线后出现故障，Agent 会自动回滚到上一个镜像，并将这次回滚写入 .env——否则下一次重启会再次静默启动故障版本。

底层机制：应用仅登记更新请求；实际执行的是 install.sh 安装在你的 VPS 上的 Agent，它通过 cron 每 5 分钟检查一次——因此点击后最多 5 分钟即可开始更新。如果该 Agent 不在线，界面会提示**“自动更新不可用”**，并显示以下命令——它不会假装更新已经成功。

cd /caminho/do/DeskcommCRM
bash hostgator-setup-kit/update.sh

该命令按以下顺序执行：(1) 检查是否确实有新版本——如果没有，立即退出；(2) 在触碰任何内容前备份数据库；(3) 下载新代码；(4) 通过重新应用幂等且可自我修复的 baseline.sql 更新数据库（它可自行修复旧版本造成的杂乱数据）；(5) 拉取新的应用镜像；(6) 最后检查健康状态。

目标是最新发布版本（v1.2.3），而不是 main 分支的最新提交——更新始终会进入一个已标记、已在 CHANGELOG.md 中说明的版本，绝不会进入未经测试的提交。它会拒绝回退到早于当前已安装版本的版本（那会关闭你已经拥有的功能）；为此特意提供了 --force。

**你可能看到的正常现象：**数据库部分会有大量 already exists / multiple primary keys——这是预期且无害的，它们表示对象已存在。脚本会过滤这些噪声，并显示 ✓ banco atualizado。如果出现 ⚠ avisos que não são os esperados，这时才需要保存相关消息。

**出问题了？**运行 bash hostgator-setup-kit/restore.sh 可恢复备份。**只想诊断？**运行 bash hostgator-setup-kit/healthcheck.sh。

⚠️ 对于尚未安装界面更新 Agent 的旧版本部署，请运行 update.sh 两次：第一次仍使用旧脚本执行（用于下载新版本）；第二次将安装 Agent 并启用该按钮。

简明步骤说明：docs/ATUALIZANDO.md。

脚本	功能
install.sh	安装全部内容（幂等——可重复运行）
update.sh	更新至新版本，并自动备份
backup.sh	备份数据库 + WhatsApp 会话
restore.sh	恢复备份
reset-password.sh	重置用户密码
reset-mfa.sh	为丢失手机的用户移除 MFA
healthcheck.sh	一次性诊断所有服务

备份很重要：Supabase 免费套餐不会自动备份。建议每天通过 cron 调度 backup.sh。update.sh 已会在每次更新前执行备份。

---

Deskcomm 源自 Desk（桌面）+ comm（商业）：桌面销售——将你的业务全部销售运营集中到一张桌面上，由人员和 AI Agent 协同运作。

该项目诞生时是一套电商 CRM，随后社区将它带得更远：如今它服务于诊所、房地产、信息产品、代理机构、商店和服务提供商——任何通过 WhatsApp 销售的业务。产品也随之转型为一个销售操作系统：具备按租户划分 RAG 的 AI Agent 可以接待客户、筛选线索、在漏斗中推进线索、触发自动化，并知道何时转交给人工；整个 CRM 通过 MCP 暴露给 Agent，使其能真正执行操作。完整故事见 VISION.md。

• 🤖 可操作 CRM 的 AI Agent ——按租户划分的 RAG、Agent 在接待过程中可自主执行的技能、运营记忆、情感分析、可审计的 AI→人工交接、作为一级受理人的 AI，以及按组织设定的支出上限。这不是装饰性的聊天机器人：Agent 会接待、筛选并推进销售漏斗。
• 🔁 不会有事项悄然消失 ——通过自适应时间和漏斗阶段触发器跟进冷却的对话；识别可能因无人回复而流失事项的雷达；以及针对需要人工决策事项的通知中心。
• 🧠 能够自我改进的 Agent ——已解决的对话会转化为新知识；AI 演进页面展示 Agent 是否正在改善、在哪些地方出错以及还需要教授什么；提案则是 AI 向自身提出的改进建议，可作为新版本应用——始终经过人工审批。
• 🧩 原生支持多垂直领域 ——每条 Pipeline 均可配置业务词汇：lead 可变为 客户、患者 或 买家；won 可变为 已付款、已预约 或 已成交。同一个核心可服务电商（项目起源，支持 Nuvemshop 集成）、诊所、房地产或信息产品业务。
• 💬 两种 WhatsApp 接入方式 ——通过 QR Code（WAHA、多号码，并具备反封禁机制：throttle + jitter + 时间窗口）或Meta 官方通道（Cloud API，支持已审批并已同步的模板）。媒体文件通过 Storage 存储，并支持 STOP 检测。
• 🔀 选择你的 AI ——可选 OpenRouter、Anthropic 或 OpenAI，在安装时决定，之后也可在界面中切换，并可按系统部分分别配置（负责对话的模型不必与负责索引的模型相同）。
• 👥 服务治理 ——真正的服务端 RBAC、可审计的分配/转交、轮转队列、按意图自动路由，以及按角色划分的可见范围。
• 🏢 多租户 + LGPD by-design ——所有感知租户的表均启用 RLS，并以隔离测试作为 CI 门槛；优先采用匿名化而非删除；追加式审计日志保留 5 年。
• 🖥️ 真正的自托管 ——你的数据位于你的 VPS；通过一条命令（或一次点击）完成安装和更新；没有付费版本，也没有功能锁定。

每个租户均可创建获客来源：一个公共地址（/api/v1/webhooks/in/<token>），可通过 POST 接收来自落地页、自有表单或 Zapier/n8n 等工具的线索（JSON 或 application/x-www-form-urlencoded），并直接将其加入所选的销售漏斗/阶段——

🇧🇷 Português · 🇺🇸 English · 🇪🇸 Español

🛠️ DeskcommCRM — o Sistema Operacional de Vendas com IA, open source, pro WhatsApp

Agentes de IA que atendem, qualificam e vendem no WhatsApp — dentro de um CRM open source rodando no seu servidor. Sem mensalidade, sem feature travada, seus dados com você. A alternativa aberta a Kommo, Octadesk e Intercom.

⚡ Instalar · 🔄 Atualizar · 🧭 Visão · 🏗️ Arquitetura · 🤝 Contribuir · 🗺️ Roadmap

---

☁️ Rode este CRM em produção com 1 comando

O DeskcommCRM foi desenvolvido em parceria com a HostGator : o hostgator-setup-kit/ instala o CRM completo (app + WhatsApp + banco) numa VPS com um único comando, e o runbook de produção já assume esse ambiente.

👉 Assinar a VPS HostGator com desconto da parceria — datacenter em São Paulo, ideal pro WhatsApp rodando 24/7. (link de parceiro — assinar por ele apoia o projeto e sai mais barato)

Ainda não tem servidor? Rode isto no seu computador (macOS, Linux ou WSL). Ele diz qual plano contratar — com os números do runbook, não um "depende" — e te devolve o comando certo pro seu caso:

curl -fsSL https://raw.githubusercontent.com/melgarafael/DeskcommCRM/main/hostgator-setup-kit/comecar.sh | bash

(prefere ler antes de executar? clone o repo e rodebash hostgator-setup-kit/comecar.sh — ele não instala nada sem você confirmar.)

---

⚡ Instalar na sua VPS (o caminho principal)

Abra o Terminal no seu computador (no Windows, o PowerShell ; no Mac ou Linux, o Terminal) e conecte com o IP e a porta que a hospedagem te mandou por e-mail:

Troque PORTA e SEU_IP pelos seus. Se a hospedagem não mencionou porta nenhuma, é a padrão (22) e você pode omitir: ssh root@SEU_IP.

Ele pede a senha. Ao digitar, não aparece nada na tela — nem asteriscos. Isso não é travamento: é o terminal escondendo a senha. Digite (ou cole) e dê Enter.

Na primeira conexão ele pergunta Are you sure you want to continue connecting? — responda yes. É o servidor se apresentando pela primeira vez.

Já dentro da VPS:

git clone https://github.com/melgarafael/DeskcommCRM.git
cd DeskcommCRM
bash hostgator-setup-kit/install.sh

É isso. Você não instala Node, nem pnpm, nem compila nada — a imagem do app já vem pronta. Se faltar Docker, o instalador pergunta e instala sozinho.

O que você precisa ter em mãos

Item	Onde conseguir
VPS com Docker	HostGator (parceria) — ou qualquer VPS com Docker. 4 GB de RAM recomendados
Domínio	Um registro A apontando pro IP da VPS (ex.: crm.suaempresa.com.br)
Banco	Conta grátis no supabase.com — 3 chaves + connection string do Session pooler
IA	Uma chave de OpenRouter , Anthropic ou OpenAI — o instalador pergunta qual você quer
WhatsApp	Seu número, conectado por QR code no onboarding (ou o canal oficial da Meta)

💡 O Supabase pode ser criado pelo próprio instalador. Exporte um SUPABASE_ACCESS_TOKEN antes de rodar e ele cria o projeto, espera o banco ficar saudável, busca as 4 credenciais e descobre o host do pooler testando conexão real — sem copiar e colar.

O que o instalador faz por você

Ele pergunta só o que é seu (domínio, chaves, senha do admin), valida cada resposta antes de seguir — chave errada ele recusa na hora, não três passos depois — e cuida do resto:

1. Gera todos os segredos técnicos sozinho (você não inventa senha nenhuma).
2. Cria as extensões do Postgres e aplica o schema completo (supabase/baseline.sql).
3. Cria o primeiro admin com o e-mail e a senha que você escolheu.
4. Sobe a stack inteira com HTTPS automático e confere a saúde no fim.
5. Instala o cron das automações (sem ele, as regras QUANDO/SE/ENTÃO ficam paradas na fila) e o agente de atualização , que é o que faz o botão "Atualizar agora" existir na tela.

Rodar de novo não quebra nada — o install.sh é idempotente: não duplica cron, não recria usuário, retoma de onde parou.

Modo não-interativo: copie .env.hostgator.example para .env, preencha e rode bash hostgator-setup-kit/install.sh --yes.

Outra hospedagem? (Hostinger, Coolify, Dokploy, CapRover…)

Funciona. Se a sua VPS já vem com um proxy reverso próprio ocupando as portas 80/443, o instalador detecta isso sozinho e publica o CRM através dele, em vez de tentar subir um Caddy que não caberia. Num caso específico — proxy em --network host, como faz a Hostinger — ele pergunta em vez de adivinhar , porque publicar atrás do proxy errado instala "com sucesso" um site mudo. Detalhes em hostgator-setup-kit/README.md.

Abra https://<seu-domínio> (o cadeado leva ~1 min pra aparecer), entre com o admin, e tenha o 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, escaneie o QR code com o WhatsApp do seu número.

🤖 Prefere que uma IA instale pra você?

Jogue a pasta hostgator-setup-kit/ no chat do Claude Code rodando dentro da VPS e diga "instala o DeskcommCRM pra mim". Ele lê o CLAUDE.md do kit — que traz o passo a passo e as armadilhas já mapeadas — e conduz tudo em português.

---

Saiu versão nova? Há dois caminhos, e o primeiro não exige terminal.

Quando existe versão nova, o rodapé do menu lateral acende "Nova versão" — só pro dono do servidor, porque avisar quem não pode atualizar é ruído. Clique e você cai em Configurações → Atualização , que mostra o que muda, faz backup do banco sozinha e acompanha cada fase (backup → código → banco → no ar) até terminar. Nada de SSH.

Se a versão nova subir quebrada, o agente volta pra imagem anterior sozinho e grava essa volta no .env — sem isso, o próximo restart traria o app quebrado de novo, em silêncio.

Por baixo: o app só registra o pedido; quem executa é o agente que o install.sh deixou na sua VPS, num cron que confere a cada 5 minutos — então a atualização começa em até 5 minutos depois do clique. Se esse agente estiver fora do ar, a tela avisa "Atualização automática indisponível" e mostra o comando abaixo — ela não finge que deu certo.

cd /caminho/do/DeskcommCRM
bash hostgator-setup-kit/update.sh

O comando faz, nesta ordem: (1) confere se há mesmo versão nova — se não houver, sai na hora; (2) faz backup do banco antes de tocar em qualquer coisa ; (3) baixa o código novo; (4) atualiza o banco re-aplicando o baseline.sql, que é idempotente e auto-curativo (conserta sozinho dados bagunçados por versões antigas); (5) puxa a imagem nova do app; (6) confere a saúde no fim.

O alvo é a última versão publicada (v1.2.3), não o topo da main — atualizar leva sempre a uma versão marcada e descrita no CHANGELOG.md, nunca a um commit não testado. Ele recusa voltar pra uma versão anterior à instalada (isso desligaria coisas que você já tem); pra isso existe --force, de propósito.

Coisas normais que você vai ver: um monte de already exists / multiple primary keys na parte do banco — é esperado e inofensivo , são coisas que já existiam. O script filtra esse ruído e mostra ✓ banco atualizado. Se aparecer ⚠ avisos que não são os esperados, aí sim guarde a mensagem.

Deu ruim? bash hostgator-setup-kit/restore.sh volta pro backup. Quer só diagnosticar? bash hostgator-setup-kit/healthcheck.sh.

⚠️ Numa instalação antiga que ainda não tem o agente da tela , rode update.sh duas vezes : a primeira execução ainda é a do script velho (que baixa o novo); a segunda instala o agente e liga o botão.

Passo a passo em linguagem simples: docs/ATUALIZANDO.md.

Script	Função
install.sh	Instala tudo (idempotente — pode rodar de novo)
update.sh	Atualiza pra versão nova, com backup automático
backup.sh	Backup do banco + sessões de WhatsApp
restore.sh	Restaura um backup
reset-password.sh	Redefine a senha de um usuário
reset-mfa.sh	Remove o MFA de quem perdeu o celular
healthcheck.sh	Diagnóstico de todos os serviços de uma vez

Backup importa: o plano grátis do Supabase não faz backup sozinho. Vale agendar backup.sh no cron diariamente. O update.sh já roda um backup antes de cada atualização.

---

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.

O 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.

• 🤖 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.
• 🔁 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.
• 🧠 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.
• 🧩 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.
• 💬 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.
• 🔀 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).
• 👥 Governança de atendimento — RBAC server-side de verdade, atribuição/transferência auditada, fila com rodízio, roteamento automático por intenção e escopo de visualização por papel.
• 🏢 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.
• 🖥️ 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.

Todo tenant pode criar fontes de captação : um endereço público (/api/v1/webhooks/in/<token>) que recebe leads de landing pages, formulários próprios ou ferramentas como Zapier/n8n via POST (JSON ou application/x-www-form-urlencoded) e já entra direto no funil/está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/SE/ENTÃ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.

Na UI, tudo mora em Webhooks na sidebar (visível só pra quem tem papel manager/admin). A tela tem três abas: Receber dados (criar fonte, copiar o endereço/formulá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).

Por baixo, cada evento vira uma linha em event_log — nenhum trigger de banco faz chamada HTTP diretamente. Quem drena essa fila é a rota /api/v1/cron/event-log-drain, chamada a cada minuto. Oinstall.sh/update.sh já configuram esse cron sozinhos — sem ele, as automações são criadas normalmente mas nunca rodam.

---

🖥️ O que você opera (as telas)

Grupo	Telas
Atendimento	Inbox (conversas de WhatsApp, você e a IA lado a lado) · Radar (quem esfriou e ainda está aberto) · Respostas rápidas
CRM	Kanban (onde cada negócio está no funil) · Contatos · Funis (etapas, vocabulário do negócio e motivos de perda)
Agente de IA	Agentes · Follow-ups · Roteadores · Provedores e Credenciais · Conhecimento (RAG) · Memória · Skills · Casos · Alertas · Propostas · Execuções · Uso e orçamento
Canais	Conexões (QR ou canal oficial da Meta, com saúde, reconexão e templates) · Nuvemshop · Webhooks
Análise	Desempenho (funil e performance por atendente) · Evolução da IA · Audit Log
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

Toda tela tem porta na navegação — o CI reprova tela que existe mas em que só se chega digitando a URL.

---

Camada	Escolha	Por quê
Frontend	Next.js 16 App Router (Turbopack) + React 19 + TypeScript 6 estrito	Server Components + Route Handlers no mesmo repo
Estilo	Tailwind + shadcn/ui (new-york, neutral)	Customizável sem lock-in
DB	Supabase (Postgres + RLS + vector)	Multi-tenant nativo, embedding pra RAG
Auth	Supabase Auth via @supabase/ssr	Cookie SameSite=Strict, HttpOnly
Realtime	Supabase Realtime	postgres_changes + broadcast
Storage	Supabase Storage (URLs assinadas)	Bucket privado whatsapp-media
WhatsApp	WAHA Plus (engine NOWEB) + Meta Cloud API	QR pra começar rápido; canal oficial pra escala
Filas	event_log table + workers (cron)	Trigger de banco nunca faz HTTP
Rate limit	Upstash Redis (sliding window)	Serverless, free tier suficiente
AI	Vercel AI SDK v7 — OpenRouter, Anthropic, OpenAI e Google	Instalador pergunta qual; troca depois pela tela
Validação	Zod	Input externo, env, payloads
Observability	Sentry (scrub em erro, transação, span e breadcrumb)	Telemetria opt-in no install
Hospedagem	VPS com Docker (HostGator/SP na parceria)	App + WhatsApp + workers na sua máquina

Detalhes: ARCHITECTURE.md.

---

🧑‍💻 Desenvolvimento (só pra contribuir com o código)

⚠️ Se você quer USAR o CRM, não é aqui — use o instalador da VPS. Esta seção é pra quem vai mexer no código.

git clone https://github.com/melgarafael/DeskcommCRM.git
cd DeskcommCRM

nvm use                     # Node 22
npm install -g pnpm && pnpm install

cp .env.example .env.local  # guia completo em docs/SETUP.md

docker compose up -d        # WAHA local (opcional em dev sem WhatsApp)

# Schema: aplique o baseline, NÃO as migrations.
# As migrations 0001-0009 e 0013 são stubs `SELECT 1;` — a cadeia não sobe do zero.
# O schema real vive no baseline.sql, o mesmo que o install.sh aplica na VPS.
# `supabase db push` "passa" e deixa o banco vazio.
supabase link --project-ref <seu-ref>

# Num projeto Supabase NOVO, habilite antes as extensões que o schema usa —
# sem elas o baseline para em `type public.vector does not exist`.
psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 -c \
  'create extension if not exists vector with schema public;
   create extension if not exists citext with schema public;
   create extension if not exists pg_trgm with schema public;'

psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 -f supabase/baseline.sql

pnpm dev

App: http://localhost:3000 · Health check: http://localhost:3000/api/v1/health

docs/SETUP.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.

---

DeskcommCRM/
├── app/                    # Next.js App Router
│   ├── (admin)/            # Rotas super-admin (impersonate, tenants)
│   ├── (public)/           # Login, recovery
│   ├── app/                # Rotas autenticadas: inbox, radar, kanban, contacts,
│   │                       #   connections, ai/*, integrations, metrics, lgpd,
│   │                       #   audit, team, settings
│   └── api/v1/             # API REST canônica (196 route handlers)
├── components/             # React (ui/, inbox/, kanban/, shell/, ...)
├── lib/                    # supabase/, waha/, channels/, ai/, agent-engine/,
│                           #   api/, routing/, navigation/, env.ts
├── workers/                # consumers de event_log (IA, RAG, LGPD, mídia, rotinas)
├── supabase/migrations/    # SQL versionado (+ baseline.sql pro self-host)
├── tests/{e2e,unit,invariants,shell}/
├── scripts/                # seeds, qa-waves, manutenção
├── docs/                   # PRDs, specs, runbooks, SETUP.md, ATUALIZANDO.md
└── hostgator-setup-kit/    # instalação e atualização self-host

---

pnpm typecheck     # tsc --noEmit (estrito)
pnpm lint          # eslint next/core-web-vitals
pnpm test:unit     # Vitest (NÃO inclui tests/invariants/**)
pnpm test:db       # Postgres efêmero + baseline install/update + invariantes
pnpm test:e2e      # Playwright (requer dev server)

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 :

gh api repos/melgarafael/DeskcommCRM/branches/main/protection \
  --jq '.required_status_checks.contexts|join(", ")'
# em 2026-08-14: verify, build-and-size, invariants, e2e, imagens-ok

Check	O que faz
verify	typecheck + lint + lint:channels + test:unit + test:shell
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
build-and-size	pnpm build em Node 22
e2e	sobe Supabase local, aplica o baseline.sql e roda 48 das 49 specs Playwright pelo frontend
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

A ú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.

Entre os invariantes está o teste de isolamento RLS : cria 2 organizações, simula os claims JWT pelo mesmo caminho auth.uid() / 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.

---

Doc	O que tem
hostgator-setup-kit/README.md	Instalação self-host — o kit, os scripts, as hospedagens com proxy próprio
docs/ATUALIZANDO.md	Como atualizar sua instalação, em linguagem simples
VISION.md	Visão e posicionamento — o que o projeto é, no que acredita e pra onde vai
CHANGELOG.md	O que mudou em cada versão — leia a seção da versão antes de atualizar
docs/SETUP.md	Setup de desenvolvimento, passo a passo de todas as integrações
docs/white-label.md	Instalar para clientes — trocar a marca, uma instalação por cliente vs compartilhada, revenda
docs/runbooks/waha-hostgator.md	Runbook de WAHA em produção (dimensionamento, recuperação)
docs/runbooks/deploy.md	Deploy em produção
CLAUDE.md	Convenções não-negociáveis (leitura obrigatória pra contribuir)
ARCHITECTURE.md	Visão de 1 página da arquitetura
docs/index.md	Índice dos 157 documentos, com regra de precedência
docs/prd/ · docs/specs/	PRDs e specs técnicas (schema SQL, payloads, MCP, governança)

---

Esse projeto é open source pra comunidade. Toda contribuição é bem-vinda — desde fix de typo em doc até feature nova.

Antes de abrir PR:

1. Leia CLAUDE.md (~5 min) — convenções não-negociáveis (multi-tenancy, RLS, audit, LGPD).
2. Leia CONTRIBUTING.md — fluxo de branches, commits, epic-executor.
3. Siga o Código de Conduta.

Fluxo curto:

git checkout -b feat/short-slug
# implementa + testes
pnpm typecheck && pnpm lint && pnpm lint:channels && pnpm test:unit && pnpm test:shell && pnpm build
pnpm test:db   # precisa de Docker — é o job `invariants`, obrigatório no merge
git commit -m "feat(escopo): descrição"
# abre PR — o template já traz o checklist de Definition of Done

Essas duas linhas são tudo o que dá para rodar na sua máquina , de propósito: rodar só metade e descobrir o resto como surpresa vermelha depois de horas de espera é a pior primeira experiência que este repositório sabe entregar.

Dois gates obrigatórios não cabem aí e só rodam no CI: o e2e (precisa de Supabase local) e o imagens-ok (constrói as três imagens Docker). Verde na sua máquina não é verde no merge.

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 nobaseline.sql se muda schema (senão a mudança não chega em quem se auto-hospeda). Detalhes em CLAUDE.md.

---

Abra uma issue — o template pede o que precisamos (ambiente, /api/v1/health, steps). Rodar bash hostgator-setup-kit/healthcheck.sh e colar a saída ajuda muito.

Pra vulnerabilidades de segurança , NÃO abra issue pública — use o relato privado de vulnerabilidades. Detalhes em SECURITY.md.

---

• 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.

• 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.

• 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.

• 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.

• Escolha de provedor de IA — OpenRouter, Anthropic ou OpenAI, decidido na instalação e trocável por parte do sistema pela tela.

• 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.

• LGPD — export e redact via workers, anonimização em cascata, consentimento auditado.

• 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.

• Webhooks & automação — fontes de captação + regras QUANDO/SE/ENTÃO + gatilhos pra sistemas externos.

• 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/specs/14).

• 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/ritmo/teto), capacidades declaradas do agente e propostas do flywheel aplicáveis como versão nova (com gate humano).

• MCP público — capabilities do CRM expostas pro ecossistema de agentes: plugue o agente que quiser e ele opera o Deskcomm.

• Templates por nicho — pipelines e vocabulários prontos pra clínica, imobiliária, infoproduto e serviços (e-commerce já entregue).

• Integrações — VTEX e Shopify via adapter pattern (Nuvemshop já entregue).

• Identity probabilística — unificação de contatos entre canais.

---

---

Distribuído sob a licença MIT — veja LICENSE. Você pode usar, modificar e distribuir livremente, inclusive comercialmente. O software é fornecido "como está", sem garantias (ver cláusula de isenção no LICENSE).

---

🛟 Suporte & responsabilidades (self-host)

Este é um projeto self-host : cada pessoa roda o CRM na própria infraestrutura (VPS, banco Supabase e chave de IA próprios). Isso implica:

• Suporte é comunitário e "as-is". Dúvidas e bugs entram como Issues ou Discussions. Não há SLA nem suporte garantido — é open source mantido por boa vontade.
• Você é responsável pela sua instalação. Atualizações não são automáticas (você clica ou roda update.sh quando quiser), e manter/backup do seu servidor é com você.
• LGPD — atenção: quem hospeda a instância é o controlador dos dados pessoais ali tratados (clientes, conversas, pedidos), com as obrigações legais decorrentes. Os mantenedores do projeto não são controladores nem operadores da sua instância, e não têm acesso ao seu banco, ao seu WhatsApp nem ao seu storage. A única coisa que pode sair da sua máquina para nós é o relatório de erro descrito abaixo — e só se você deixar.
• Telemetria (Sentry): o install.sh pergunta durante a instalação e respeita a sua resposta; em modo não-interativo, sem SENTRY_DSN definido, a telemetria fica desligada. Se você aceitar o Sentry da comunidade, o que é enviado são relatórios de erro (stack trace) com CPF, telefone e e-mail substituídos, cabeçalhos sensíveis removidos, e token de webhook/convite redigido da URL — sem rastreamento de performance e sem replay de sessão, que ficam em 0 nesse caminho. Para desligar a qualquer momento: SENTRY_DSN=off no .env. Para mandar ao seu Sentry (aí sim com performance e replay): SENTRY_DSN=<seu-dsn>. O que é redigido, e por quê, está em lib/sentry/scrub.ts; a resolução do DSN em lib/sentry/dsn.ts.

---

• WAHA (devlikeapro) — engine WhatsApp.
• Supabase — Postgres + Auth + Storage + Realtime numa stack só.
• HostGator — parceria de infraestrutura que tornou o self-host de 1 comando possível.
• Anthropic , OpenAI e OpenRouter — os provedores de IA que o CRM sabe usar.
• shadcn/ui — base de componentes.
• A comunidade que nos levou do e-commerce pra clínicas, imobiliárias, infoprodutos e além — vocês definiram o que este projeto é.

---

Built with ☕ in Brasil · Made for the community

Siga o desenvolvimento: Instagram · YouTube