crm-ai-demo/docs/twenty-crm-guide.md

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）：

{
  "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（工作流创建脚本）