Initial commit: CRM AI Demo bridge + KB knowledge base + infrastructure
- Bridge server with LLM agent tool-use (search_kb, search_products, search_orders, search_inventory, escalate_human) - pgvector RAG knowledge base (95 FAQ chunks) - Auto opportunity creation in Twenty CRM - Auto follow-up task workflow - Chatwoot AgentBot integration (HMAC, webhook) - Docker compose infrastructure (PG18, Redis 8.8, node24-alpine) - Configuration templates (example files) - real secrets excluded via .gitignore
This commit is contained in:
AI Bridge Dev
229
docs/twenty-crm-guide.md
Normal file
229
docs/twenty-crm-guide.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# Twenty CRM 功能指南
|
||||
|
||||
> 本文档说明 Twenty CRM 在本系统中的集成方式、当前已用功能，以及 Twenty 本身的完整能力。
|
||||
> 适用于：系统运维、功能扩展、二次开发参考。
|
||||
|
||||
---
|
||||
|
||||
## 一、当前系统的集成现状
|
||||
|
||||
### Bridge 实际用到的 Twenty 功能（5 个 GraphQL 操作）
|
||||
|
||||
| 功能 | GraphQL 调用 | 代码位置 (`bridge/server.js`) | 作用 |
|
||||
|---|---|---|---|
|
||||
| 创建公司 | `createCompany` | :221 | 从对话提取公司名，自动建公司记录 |
|
||||
| 查公司（去重） | `companies(filter:{name})` | :227 | 避免重复创建同名公司 |
|
||||
| 创建联系人 | `createPerson` | :254 | 建联系人（姓名/邮箱/电话），关联到公司 |
|
||||
| 查联系人（去重） | `people(filter:{emails})` | :234 | 按邮箱去重 |
|
||||
| 创建商机 | `createOpportunity` | :276 | 建商机（名称/金额/阶段/公司/联系人） |
|
||||
| 创建笔记 | `createNote` + `createNoteTarget` | :333 | 把聊天记录挂到商机上 |
|
||||
| **创建跟进任务** | `createTask` + `createTaskTarget` | :329 | **自动化**：商机创建后自动生成 3 天到期的跟进任务 |
|
||||
|
||||
**Bridge 把 Twenty 当成「线索落地库 + 自动化起点」**——不仅结构化存储销售线索，还自动触发跟进流程。
|
||||
|
||||
### 商机创建的触发条件
|
||||
|
||||
Bridge 用 `EXTRACT_SYSTEM`（`server.js:516`）对每轮对话做信息提取，判断 `ready=true` 需要**三要素齐全**：
|
||||
|
||||
1. **公司名** — Company name（任意语言）
|
||||
2. **联系方式** — Email 或 Phone，或联系人姓名
|
||||
3. **产品/需求** — 客户感兴趣的产品或采购意向
|
||||
|
||||
三者缺任何一个，`ready=false`，继续对话收集，不创建商机。
|
||||
|
||||
---
|
||||
|
||||
## 二、Twenty CRM 完整数据对象
|
||||
|
||||
当前 workspace（`workspace_6o1rsmnm23f20gpxxzby7wab2`）包含 28 个数据表：
|
||||
|
||||
```
|
||||
当前已用（Bridge 自动写入） 未使用（可手动操作或扩展自动化）
|
||||
┌──────────────────────────┐ ┌────────────────────────────────────┐
|
||||
│ ✅ company 公司 │ │ 📅 calendarEvent 日历/会议 │
|
||||
│ ✅ person 联系人 │ │ 📧 message 邮件消息 │
|
||||
│ ✅ opportunity 商机 │ │ 📞 callRecording 通话录音 │
|
||||
│ ✅ note 笔记 │ │ 🔄 workflow 自动化工作流 │
|
||||
│ ✅ noteTarget 笔记关联 │ │ 📊 dashboard 仪表盘/报表 │
|
||||
│ ✅ task 跟进任务 │ │ 👥 workspaceMember 团队成员 │
|
||||
│ ✅ taskTarget 任务关联 │ │ 🚫 blocklist 屏蔽名单 │
|
||||
└──────────────────────────┘ │ 📎 attachment 附件 │
|
||||
│ 📝 messageCampaign 邮件营销 │
|
||||
│ 🕐 timelineActivity 活动时间线 │
|
||||
└────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、未使用功能详解
|
||||
|
||||
### 1. 任务管理（Task）— 跟进客户
|
||||
|
||||
给商机/联系人创建跟进任务，是商机转化为真实订单的关键环节。
|
||||
|
||||
**典型用法**：
|
||||
- "明天回电 Sophie 确认戒指款式"
|
||||
- "本周五前寄出报价单"
|
||||
- 设置截止日期、负责人、优先级
|
||||
|
||||
**位置**：Twenty 网页 → 左侧导航 Tasks
|
||||
|
||||
---
|
||||
|
||||
### 2. 日历（Calendar）— 安排会议
|
||||
|
||||
- 关联到联系人/商机
|
||||
- 记录客户会议、产品演示时间
|
||||
- 支持 Google/Microsoft 日历集成（需额外配置 OAuth）
|
||||
|
||||
**位置**：Twenty 网页 → 左侧导航 Calendar
|
||||
|
||||
---
|
||||
|
||||
### 3. 消息/邮件（Message）— 统一收件箱
|
||||
|
||||
- 集成 Gmail/Outlook，直接在 CRM 里收发邮件
|
||||
- 所有客户沟通集中管理，不再散落各处
|
||||
- 邮件营销（MessageCampaign）支持群发
|
||||
|
||||
**位置**：Twenty 网页 → 左侧导航 Messages
|
||||
|
||||
---
|
||||
|
||||
### 4. 自动化工作流（Workflow）— 最强大的未用功能
|
||||
|
||||
自动触发规则，目前完全没用上，潜力巨大。
|
||||
|
||||
**典型场景**：
|
||||
- "新商机创建 → 自动通知负责人 + 创建 3 天后跟进任务"
|
||||
- "商机阶段变为 PROPOSAL → 自动发邮件给客户"
|
||||
- "商机金额 > €5000 → 自动提升优先级 + 通知销售经理"
|
||||
|
||||
**位置**：Twenty 网页 → Settings → Workflows
|
||||
|
||||
---
|
||||
|
||||
### 5. 仪表盘（Dashboard）— 数据可视化
|
||||
|
||||
- 销售漏斗（各阶段商机数量/金额）
|
||||
- 自定义视图、过滤器、图表
|
||||
- 月度/季度业绩统计
|
||||
|
||||
**位置**：Twenty 网页 → 左侧导航 Dashboards
|
||||
|
||||
---
|
||||
|
||||
### 6. 自定义字段 — Twenty 的杀手锏
|
||||
|
||||
可以给任何对象（Company/Person/Opportunity）添加自定义字段：
|
||||
- 客户行业、Jewelry 偏好材质、年采购量、首次接触渠道
|
||||
- 当前 Bridge 提取的字段是固定的，可通过扩展 `EXTRACT_SYSTEM` 来填充自定义字段
|
||||
|
||||
**位置**：Twenty 网页 → Settings → Object 某个对象 → Fields
|
||||
|
||||
---
|
||||
|
||||
## 四、网页界面导航
|
||||
|
||||
```
|
||||
http://localhost:3000 → 登录后左侧导航栏：
|
||||
|
||||
📊 Dashboards 仪表盘
|
||||
🏢 Companies 公司列表
|
||||
👤 People 联系人
|
||||
💼 Opportunities 商机 ← Bridge 自动创建的数据在这里
|
||||
✅ Tasks 任务
|
||||
📅 Calendar 日历
|
||||
📧 Messages 消息
|
||||
⚙️ Settings 设置 ← 工作流 / 自定义字段 / 团队成员
|
||||
```
|
||||
|
||||
点开任意商机（如 Nordic Retail AB），可见多个标签页：
|
||||
- **Notes** — 笔记（Bridge 自动写入的聊天记录）
|
||||
- **Tasks** — 关联任务
|
||||
- **Timeline** — 活动时间线
|
||||
- **People** — 关联联系人
|
||||
|
||||
---
|
||||
|
||||
## 五、API Key 与认证配置
|
||||
|
||||
Bridge 通过 GraphQL API 访问 Twenty，认证链路：
|
||||
|
||||
```
|
||||
twenty.config.json
|
||||
├── baseURL: http://localhost:3000
|
||||
├── graphqlPath: /graphql
|
||||
├── workspaceId: 70a1901c-45ab-4b95-a7f0-de74be819b2e
|
||||
└── apiKey: <ES256 JWT，kid=2b878cf8...>
|
||||
```
|
||||
|
||||
**JWT 结构**（`bridge/twenty.config.json` 里的 apiKey）：
|
||||
```json
|
||||
{
|
||||
"alg": "ES256", "typ": "JWT", "kid": "2b878cf8-7d35-4906-899f-a0439b1c2116"
|
||||
}
|
||||
// payload:
|
||||
{
|
||||
"sub": "70a1901c-45ab-4b95-a7f0-de74be819b2e", // = workspaceId
|
||||
"type": "API_KEY",
|
||||
"workspaceId": "70a1901c-45ab-4b95-a7f0-de74be819b2e",
|
||||
"iat": 1784878461,
|
||||
"exp": 4922899200,
|
||||
"jti": "556d9fc0-7f32-4a5b-b041-78b30242cefb" // = apiKey 表的 id
|
||||
}
|
||||
```
|
||||
|
||||
**API Key 的两个必要绑定**（缺一不可）：
|
||||
1. `core."apiKey"` 表：记录 apiKey id → workspaceId
|
||||
2. `core."roleTarget"` 表：记录 apiKeyId → roleId（绑定权限角色，否则报 `INVALID_AUTH_CONTEXT`）
|
||||
|
||||
> 如需重新生成 API Key，参考项目根目录的 `gen_apikey.js` 脚本（用 HKDF 解密签名密钥后签发 JWT）。
|
||||
|
||||
---
|
||||
|
||||
## 六、扩展建议
|
||||
|
||||
### 已实现（✅）
|
||||
|
||||
| 扩展 | 做法 | 代码位置 | 价值 |
|
||||
|---|---|---|---|
|
||||
| **商机自动创建跟进任务** | Bridge 在 `createLeadInCRM` 里商机创建后自动建 Task | `server.js:329` | 商机不遗漏跟进 |
|
||||
|
||||
#### 自动跟进任务的工作方式
|
||||
|
||||
商机创建成功后，Bridge 自动执行（`server.js` createLeadInCRM 函数内）：
|
||||
|
||||
1. 创建一条 Task，标题 `跟进商机: <商机名>`
|
||||
2. 任务内容包含：客户公司、联系人、需求摘要、行动指引（3 个工作日内联系）
|
||||
3. 设置到期日为 **3 天后**
|
||||
4. 通过 `createTaskTarget` 把 Task 关联到刚创建的 Opportunity
|
||||
|
||||
**触发日志示例**（bridge 日志中可见）：
|
||||
```
|
||||
[workflow] conv=3 opp=b3ab3af2... -> 自动创建跟进任务 fcd6f300... (3天后到期)
|
||||
[CRM✓] conv=3 建线索: {新公司 + 新联系人 + 新商机} (新公司) (新联系人)
|
||||
```
|
||||
|
||||
> **注意**：本自动化在 Bridge 层实现，而非 Twenty 内置 Workflow 引擎。原因是 Twenty 的 API key 权限不支持通过 GraphQL 创建 `workflowVersion`（报 `FORBIDDEN`）。Bridge 层实现更可控、日志透明。如需更复杂的可视化编排，可在 Twenty 网页 **Settings → Workflows** 通过 UI 创建。
|
||||
|
||||
### 短期（低成本，高收益）
|
||||
|
||||
| 扩展 | 做法 | 价值 |
|
||||
|---|---|---|
|
||||
| **商机金额自动填充** | 扩展 `EXTRACT_SYSTEM`，让 LLM 估算 unit price × quantity | 漏斗金额更准确 |
|
||||
| **自定义字段：客户行业** | Twenty 加字段 + Bridge `EXTRACT_SYSTEM` 提取 | 销售分群分析 |
|
||||
| **商机阶段自动推进** | Bridge 根据"是否提供报价/是否确认订单"调用 `updateOpportunity` 改 stage | 漏斗自动化 |
|
||||
|
||||
### 中期（需开发）
|
||||
|
||||
| 扩展 | 做法 | 价值 |
|
||||
|---|---|---|
|
||||
| **销售漏斗仪表盘** | Twenty Dashboard 配置 | 可视化业绩 |
|
||||
| **双向同步** | Bridge 读 Twenty（如查客户历史商机） | AI 回复更智能 |
|
||||
| **邮件集成** | Twenty Settings 配置 Gmail/Outlook OAuth | 统一沟通 |
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026-07-24（新增：自动化跟进任务功能）*
|
||||
*相关文件：`bridge/server.js`（GraphQL 调用 + 自动化工作流）、`bridge/twenty.config.json`（连接配置）、`gen_apikey.js`（API Key 生成）、`create_workflow.js`（工作流创建脚本）*
|
||||
Reference in New Issue
Block a user