DeskcommCRM

<div align="center"> # 🛠️ DeskcommCRM **多租户电商CRM，配备原生对话式AI、WAHA WhatsApp和LGPD合规功能。** [](https://nextjs.org) [](https://www.typescriptlang.org) [](https://supabase.com) [](https://tailwindcss.com) [](LICENSE) [**📘 安装指南**](docs/SETUP.md) · [**🏗️ 架构**](ARCHITECTURE.md) · [**🤝 贡献**](CONTRIBUTING.md) · [**📋 PRDs**](docs/prd/) · [**🗺️ 路线图**](#%EF%B8%8F-roadmap) </div> --- > ### ☁️ 一键部署生产环境 > > DeskcommCRM 与 **HostGator** 合作开发：[`hostgator-setup-kit/`](hostgator-setup-kit/) > 安装完整的CRM（应用 + WAHA + 数据库）到VPS，只需一个命令。 > 生产环境运行手册已针对此环境进行配置。 > > **[👉 点击注册HostGator VPS，享受合作伙伴折扣](https://www.hostgator.com.br/52708-141-3-52.html)** — > 位于巴西圣保罗的数据中心，非常适合24/7运行的WhatsApp。 *(通过此链接注册支持项目并更便宜)* ## ✨ 关于 DeskcommCRM 将 **人工客服**、**租户级AI代理**、**订单管理** 和 **售后流程** 统一到一个平台上。 主要渠道： **通过WAHA使用WhatsApp**。 从一开始就是多租户的。 LGPD原生支持。 > **当前模式：** 内部BPO（一个运营商服务多个租户）。 > **未来模式：** 直接面向商家的SaaS。 ### 优势 - 🤖 **AI驱动的客服** — 每个租户都有RAG代理，情绪分析，IA与人工交接和预算控制。 不是装饰性的聊天机器人，而是真正的分诊。 - 🛒 **电商原生** — 词汇设计适用于购物车放弃 -> 支付 -> 运送 -> 交付 -> 售后流程。 - 🇧🇷 **LGPD合规设计** — Nuvemshop的webhooks作为一类合同；优先匿名处理；审计日志仅追加，保留5年。 - 👥 **客服治理** — 真正的服务端RBAC，审计的分配/转移，带有位置的队列，自动路由和按角色划分的可见范围。 - 🔌 **MCP-ready** — 内部MCP服务器；外部代理的公共合同正在建设中。 - 🏢 **真正的多租户** — 整个tenant-aware表格的RLS，隔离测试作为CI门控。 ### 🔌 Webhooks & 自动化 每个租户都可以创建 **捕获源**：一个公共地址（`/api/v1/webhooks/in/<token>`），接收来自着陆页、自定义表单或Zapier/n8n等工具的线索，通过POST（JSON或`application/x-www-form-urlencoded`）直接进入选定的渠道/阶段 — 无需代码，无需定制集成。在这些源（以及CRM的其他事件 - 线索改变阶段，获得标签，WhatsApp消息到达）的基础上，租户可以构建 **自动化**：QUANDO/SE/ENTÃO格式的规则，触发诸如添加标签，将线索移动到渠道，分配给客服人员，发送WhatsApp消息或通过输出webhook通知其他系统。 在UI中，所有内容都在侧边栏的 **Webhooks** 中（仅对具有`manager`/`admin`角色的人员可见 - `agent`/`viewer`看不到该项，也无法访问该路由，并且会重定向到收件箱）。 该页面有三个选项卡： **接收数据** （创建源，复制准备好的地址/表单，发送测试线索，查看最近的接收）， **自动化** （构建规则，始终暂停直到租户审查和启用）和 **活动** （每个执行的时序，带有每个动作的结果和手动重新发送失败的外部webhook调用时）。 在后台，每个事件（创建线索，添加标签等）变成`event_log`中的一行 - 没有数据库触发器直接调用HTTP。 排空此队列并实际触发自动化的是 `/api/v1/cron/event-log-drain` 路由，每分钟调用一次。 在Vercel上，这是一个托管的Cron作业； **在HostGator自托管套件（`hostgator-setup-kit/`）** 中，`install.sh`/`update.sh`已经自动配置了一个`crontab`行，每分钟使用`.env`中的`INTERNAL_SECRET`运行此路由。 没有此Cron作业，源和自动化仍然可以创建，但事件将堆积在`event_log`中，不会触发任何实际自动化。 --- ## 🚀 快速开始（5分钟内看到运行中的应用） ```bash # 1. 克隆 git clone https://github.com/melgarafael/DeskcommCRM.git cd DeskcommCRM # 2. Node 20 + pnpm nvm use # 或安装Node 20+ npm install -g pnpm pnpm install # 3. 环境变量 cp .env.example .env.local # 编辑.env.local - 完整指南见docs/SETUP.md # 4. 本地WAHA（可选，在没有WhatsApp的开发环境中） docker compose up -d # 5. Supabase迁移 supabase link --project-ref <您的引用> supabase db push # 6. 启动应用 pnpm dev ``` 应用：<http://localhost:3000> · 健康检查：<http://localhost:3000/api/v1/health> > 🆕 **第一次使用？不要跳过步骤。** [`docs/SETUP.md`](docs/SETUP.md) 是 **所有集成** 的完整逐步教程（Supabase，WAHA，Anthropic，Upstash，Sentry，Resend，Nuvemshop）- 为以前从未配置过这些的人准备。 ~60–90分钟从零到应用运行。 --- ## 🧱 技术栈 | 层 | 选择 | 原因 | |---|---|---| | **前端** | Next.js 16 应用路由器（Turbopack）+ React 19 + TypeScript 6严格模式 | 服务器组件 + 路由处理器在同一个仓库 | | **样式** | Tailwind + shadcn/ui (`new-york`, 中性) | 可定制，无锁定 | | **数据库** | Supabase（Postgres + RLS + `vector`） | 原生多租户，嵌入式RAG | | **身份验证** | Supabase Auth via `@supabase/ssr` | Cookie SameSite=Strict, HttpOnly | | **实时** | Supabase Realtime | postgres_changes + broadcast | | **存储** | Supabase Storage（签名URL） | 私有存储桶 `whatsapp-media` | | **WhatsApp** | WAHA Plus（engine NOWEB） | 多租户，重试，S3 | | **队列** | `event_log` 表 + 工作线程（cron） | 没有Inngest/Trigger的MVP | | **速率限制** | Upstash Redis（滑动窗口） | 无服务器，免费层足够 | | **AI** | Vercel AI SDK v7（providers Anthropic/Google/OpenAI v4）via AI Gateway | 自动故障转移，ZDR | | **验证** | Zod | 外部输入，环境，payloads | | **可观察性** | Sentry（带有`beforeSend`清理） | 没有PII的breadcrumb | | **托管** | Vercel（应用）+ Hostgator VPS图灵/SP（WAHA） | 边缘 + WhatsApp专用；巴西数据中心 | 详情： [`ARCHITECTURE.md`](ARCHITECTURE.md). --- ## 📁 结构 ``` DeskcommCRM/ ├── app/ # Next.js 应用路由器 │ ├── (admin)/ # 超级管理员路由（模拟，租户） │ ├── (public)/ # 登录，恢复 │ ├── app/ # 身份验证路由：收件箱，kanban，联系人， │ │ # 连接，AI（代理），集成， │ │ # 指标，LGPD，审计，团队，设置 │ └── api/v1/ # 规范的REST API ├── components/ # React（ui/，inbox/，kanban/，shell/，...） ├── lib/ # supabase/，waha/，ai/，api/，routing/，env.ts ├── hooks/ ├── supabase/migrations/ # 版本控制SQL（+ baseline.sql用于自托管） ├── workers/ # event_log消费者（AI，RAG，LGPD，例行程序） ├── tests/{e2e,unit,invariants}/ ├── scripts/ # seeds，qa-waves，维护 ├── docs/ # PRDs，规格，故事，SETUP.md └── hostgator-setup-kit/ # 使用1个命令进行自托管安装 ``` --- ## 🧪 测试 ```bash pnpm typecheck # tsc --noEmit（严格） pnpm lint # eslint next/core-web-vitals pnpm test:unit # Vitest pnpm test:e2e # Playwright（需要开发服务器） ``` CI在合并前运行所有这些。 **RLS隔离测试是必填门控** - 创建2个租户并检查不泄漏。 **治理不变性套件**（100+测试）阻止RBAC，分配，范围和路由的回归。 --- ## 📚 文档 | 文档 | 内容 | |---|---| | [`docs/SETUP.md`](docs/SETUP.md) | **完整逐步安装指南**，涵盖所有集成 | | [`CLAUDE.md`](CLAUDE.md) | 不可协商的约定（必填阅读） | | [`ARCHITECTURE.md`](ARCHITECTURE.md) | 架构的一页视图 | | [`CONTRIBUTING.md`](CONTRIBUTING.md) | PR流程 + 史诗执行者 | | [`docs/prd/`](docs/prd/) | PRDs（主平台，客户360，WhatsApp，管道，AI-RAG，Nuvemshop） | | [`docs/specs/`](docs/specs/) | 技术规格01-13（SQL模式，负载，MCP，治理） | | [`docs/business-rules/`](docs/business-rules/) | 代码外部的业务规则 | | [`docs/DEPLOY-CHECKLIST.md`](docs/DEPLOY-CHECKLIST.md) | 上线前检查清单 | | [`docs/runbooks/waha-hostgator.md`](docs/runbooks/waha-hostgator.md) | 生产环境WAHA运行手册（Hostgator VPS） | | [`docs/ATUALIZANDO.md`](docs/ATUALIZANDO.md) | 如何更新自托管安装 | --- ## 🤝 贡献 该项目是针对社区的开放源代码。 欢迎所有贡献 - 从文档中的类型错误到新功能。 **在开启PR之前：** 1. 阅读 [`CLAUDE.md`](CLAUDE.md)（~5分钟）- 不可协商的约定（多租户，RLS，审计，LGPD）。 2. 阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) - 分支流程，提交，史诗执行者。 3. 遵循 [行为准则](CODE_OF_CONDUCT.md). **快速流程：** ```bash git checkout -b feat/短描述 # 实现 + 测试 pnpm typecheck && pnpm lint && pnpm test:unit git commit -m "feat(范围): 描述" # 开启PR - 模板已经带有完成清单 ``` **完成定义：** typecheck zero，lint zero，相关测试绿色，RLS测试如果触及租户感知表，审计日志在突变中发出，版本控制迁移如果更改模式。 详情见 [`CLAUDE.md`](CLAUDE.md#definition-of-done). --- ## 🐛 报告错误 开启一个 [问题](https://github.com/melgarafael/DeskcommCRM/issues/new/choose) - 模板要求我们需要的内容（环境，`/api/v1/health`, 步骤）。 对于 **安全漏洞**，**不要公开问题** - 使用 [私有漏洞报告](https://github.com/melgarafael/DeskcommCRM/security/advisories/new). 详情见 [`SECURITY.md`](SECURITY.md). --- ## 🗺️ 路线图 ### ✅ 已交付 - **基础&平台** - 认证（管理员MFA），多租户与RLS +隔离测试，RBAC 4个角色，审计日志仅追加，租户入职。 - **WhatsApp客服** - 实时3面板收件箱，WAHA多号码连接，媒体通过存储库，防封（限流+抖动+时间窗口）STOP检测。 - **CRM&订单** - 带有电商词汇的kanban（分数索引），客户360，联系人，标签，Nuvemshop集成。 - **原生AI** - 每个租户的RAG代理（pgvector），情绪分析，IA→人交接，按组织预算控制，内部MCP服务器。 - **LGPD** - 通过工作线程导出和redact，级联匿名化，审计同意。 - **自托管** - `hostgator-setup-kit`（应用+WAHA+数据库1个命令），`baseline.sql`自我修复，生产运行手册。 - **Webhooks&自动化** - CRM事件触发外部系统。 - **客服治理** - 全API服务端RBAC，审计分配和转移（AI作为一级assignee），按角色可见性（RLS）+指标，自动路由，带有队列和治理面板，AI外部代理的治理合同（[`docs/specs/14`](docs/specs/14-contrato-governanca-agentes-externos.md））。 由100+不变性引导（G1-G6）。 - **可见操作** - 面板让操作员理解代理：翻译的防封原因，对话中的中央警报，发送保护控制（窗口/节奏/上限）和飞轮提案作为新版本（带有人工门控）。 ### 🔮 下一步 - **FG阶段** - 代理Vendaval通过`ai_dispatch_mode=external`消费治理 🔜 *(等待优先级所有者)* - **公开MCP** - CRM功能暴露给代理生态系统。 - **集成** - VTEX和Shopify通过适配器模式（Nuvemshop已交付）。 - **概率身份** - 跨渠道联系人统一。 - **SaaS模式** - 商家直接自服务（目前：单个BPO）。 --- ## 💬 社区 - **讨论：** [GitHub Discussions](https://github.com/melgarafael/DeskcommCRM/discussions) - 用于提问，想法，展示。 - **问题：** [GitHub Issues](https://github.com/melgarafael/DeskcommCRM/issues) - 错误和任务。 - **Instagram：** [@melgarafael](https://www.instagram.com/melgarafael) - **YouTube：** [youtube.com/@melgarafael](https://www.youtube.com/@melgarafael) --- ## 📜 许可证 在 **MIT** 许可证下分发 - 查看 [`LICENSE`](LICENSE). 您可以免费使用，修改和分发，包括商业用途。 软件按“现状”提供，**无保证**（查看 `LICENSE`中的免责声明条款）。 --- ## 🛟 支持&责任（自托管） 该项目是 **自托管**：每个人都在自己的基础设施（VPS，Supabase数据库和AI密钥）上运行CRM。这意味着： - **支持是社区的“as-is”.** 像 [问题](https://github.com/melgarafael/DeskcommCRM/issues) 或 [讨论](https://github.com/melgarafael/DeskcommCRM/discussions) 一样进入。 没有SLA或保证支持 - 开源由善意维护。 - **您负责您的安装.** 更新不是自动的（`bash hostgator-setup-kit/update.sh`），您自己的服务器维护/备份也是如此。 - **LGPD - 注意：** 托管实例是 **数据控制器** （处理的个人数据），具有相关的法律义务。 项目维护者 **没有访问** 您的资料且 **不是** 您实例的控制器或运营者。 - **遥测（Sentry）：** 默认情况下，**匿名**错误（删除CPF/电话/电子邮件）被发送到社区的Sentry以帮助修复影响所有内容的错误。 **关闭** 使用 `.env`中的`SENTRY_DSN=off`；发送到 **您的** Sentry，使用`SENTRY_DSN=<您的DSN>`。 查看 [`lib/sentry/dsn.ts`](lib/sentry/dsn.ts). ## 🙏 致谢 - **WAHA** ([devlikeapro](https://waha.devlikeapro.com/)）- WhatsApp引擎。 - **Supabase** - Postgres + Auth + Storage + Realtime 一体化堆栈。 - **Vercel** - 托管 + AI Gateway。 - **Anthropic**（Claude）- 对话式AI。 - **Anthropic** （Claude）- 对话式AI。 - **shadcn/ui** - 组件库。 - **巴西电商社区** - 验证了最初的假设。 --- <div align="center"> **用 ☕ 在巴西构建** · **为社区制作** 关注开发进度： [Instagram](https://www.instagram.com/melgarafael) · [YouTube](https://www.youtube.com/@melgarafael) </div>