企业微信集成指南
本指南覆盖 MihootCRM 与企业微信的三大集成能力：营销集成、侧边栏、AI 智能机器人。完成集成后，你可以在企业微信中直接管理客户、执行工作流、使用 AI 助手。
1. 集成准备
前提条件
- 拥有企业微信管理员权限
- 企业微信应用已完成创建和配置
- 已获得以下信息：企业 ID（Corp ID）、应用 Agent ID、应用 Secret
环境变量配置
集成需要以下环境变量（由管理员在部署时配置）：
NEXT_PUBLIC_WECOM_CORP_ID：企业微信企业 IDNEXT_PUBLIC_WECOM_AGENT_ID：企业微信应用 Agent IDWEBHOOK_BFF_SECRET：回调安全密钥
2. 营销集成
2.1 活码管理
使用场景：为不同的获客渠道（线下活动、线上广告、合作伙伴）创建独立的企微活码，追踪各渠道添加效果。
操作步骤：
- 进入 企业微信营销 页面
- 在活码列表区域，点击"创建活码"
- 填写活码信息：
- 名称：如"618活动活码""知乎广告活码"
- 渠道标识：自动生成或自定义（用于区分来源）
- 创建后，活码生成对应的二维码或链接
- 将活码投放到不同渠道（海报、网页、社交媒体）
- 客户扫码添加企微后，系统自动记录来源渠道
在 CRM 中查看效果：
- 活码列表显示每个活码的添加客户数量
- 客户详情页的来源字段会显示对应的活码渠道
2.2 群发任务
使用场景：向特定客户群体批量发送营销消息、活动海报、产品介绍。
操作步骤：
- 在 /wecom-marketing 的群发任务区域，点击"新建群发"
- 选择目标客户群（按标签、分群、来源渠道筛选）
- 编辑消息内容（文本、图片、链接）
- 可选择立即发送或定时发送
- 提交后，系统通过企微 API 执行群发
查看效果：
- 群发任务列表显示每个任务的状态（进行中/已完成/失败）和覆盖客户数
- 客户 Timeline 中会记录群发消息的触达事件
2.3 数据映射
集成完成后，企微数据与 CRM 数据建立双向映射：
- external_userid ↔ 联系人/线索/活动参与者
- 企微聊天中的客户标记、标签同步到 CRM
- 详细数据映射见内部文档
docs/wecom-data-mapping.md
3. 企业微信侧边栏
什么是侧边栏
侧边栏是嵌入企业微信聊天窗口右侧的 CRM 操作面板。销售人员在企微中与客户聊天时，无需切换应用就能查看客户资料、发送素材、执行工作流、使用 AI 助手。
3.1 侧边栏启动流程
侧边栏打开后自动执行初始化：
- 租户解析：从企微获取 corpId，匹配对应 CRM 租户
- OAuth 授权：引导用户完成企微 OAuth，获取 userId
- JSSDK 注入：注入企业微信 JSSDK（
wx.config+wx.agentConfig），获取应用权限 - 客户解析：通过
externalUserId匹配 CRM 中的联系人和商机数据
3.2 CRM 状态说明
侧边栏根据当前聊天客户返回三种 CRM 状态：
| 状态 | 含义 | 侧边栏行为 |
|---|---|---|
| Linked | 客户已关联 CRM 联系人 | 正常显示 Tab 和完整客户数据 |
| Unlinked | 客户未关联 CRM | 显示引导创建/关联提示 |
| Forbidden | 无权限查看 | 显示权限受限提示 |
3.3 六个 Tab 视图
| Tab | 功能 | 典型使用场景 |
|---|---|---|
| Customer | 客户信息 | 查看客户姓名、标签、阶段、来源、关联商机 |
| Scripts | 销售话术 | 选择预设话术快速回复客户，保持沟通一致性 |
| Materials | 营销素材 | 发送产品海报、活动文章、电子文档给客户 |
| Products | 产品目录 | 展示 CRM 中的产品/治疗方案卡片 |
| Workflows | 工作流 | 一键执行已发布的工作流（如触发跟进任务） |
| Assistant | AI 助手 | 对话式查询和操作 CRM 数据，自动感知当前客户 |
3.4 典型使用流程
场景：客户在企微中询问正畸方案
- 打开右侧侧边栏，Customer Tab 自动显示该客户信息和现有商机
- 切换到 Products Tab，选择正畸产品卡片发送给客户
- 切换到 Scripts Tab，选择正畸话术模板快速回复
- 切换到 Workflows Tab，执行"创建正畸咨询跟进"工作流
- 切换到 Assistant Tab，问 AI："预估一下这个客户的正畸预算范围"
全程未离开企微聊天窗口。
4. 企业微信 AI 智能机器人（WeCom AI Bot）
什么是 AI Bot
AI Bot 是一个独立的 Node.js 进程，通过 WebSocket 长连接与企业微信开放平台通信。用户可以在企微中直接向 Bot 发送消息，Bot 调用 CRM AI 助手的能力回复。
4.1 Bot 的能力
Bot 底层复用 CRM AI 助手的完整 Agent 运行时（runAgent），包括：
- 所有 47 个 CRM 工具（查询、创建、更新、分析）
- AI 技能匹配和调用
- MCP 工具注入
- 语义层理解
- 已发布工作流执行
4.2 启动方式
命令：npm run aibot
前置依赖（须先启动）：
| 服务 | 默认地址 | 用途 |
|---|---|---|
| Java CRM 后端 | http://127.0.0.1:9090/crm | 配置、命令队列、用户解析 |
| Next.js | http://localhost:3000 | Agent 能力、已发布工作流 |
| Redis | .env.local 中的 REDIS_URL | 对话历史缓存 |
4.3 连接流程
- 启动
npm run aibot，保持终端窗口运行 - 打开 CRM /integrations 页面
- 在「企业微信 AI 智能机器人」卡片中填写 Bot ID、Bot Secret 并保存
- 点击卡片上的「连接」按钮
- 观察 aibot 终端日志，确认 WebSocket 已建立
- 此时在企微中向 Bot 发送消息，Bot 开始响应
4.4 Bot 使用示例
在企微聊天中向 Bot 发送：
- "查一下张三" → Bot 返回 CRM 中的张三信息
- "我今天有哪些任务" → Bot 返回你的待办任务列表
- "创建明天回访李四的任务" → Bot 创建任务并确认
4.5 Bot 对话管理
- 命令控制：管理员通过 Java 后端的命令队列控制 Bot 的启动、停止、重启
- 对话历史：存储在 Redis 中（
aibot:history:{tenant}:{sessionId}），保留最近 3 轮对话，30 分钟 TTL
5. 相关文档
- AI 智能助理指南 — AI 能力配置
- 对话式 CRM 操作指南 — 对话式操作参考
- 自动化工作流指南 — 侧边栏工作流执行
- 营销管理指南 — 企微营销功能