From 745c19269329669f0510db2cc745fcb3d10d2e27 Mon Sep 17 00:00:00 2001 From: jacy <18049821889@163.com> Date: Sun, 26 Jul 2026 08:37:11 +0800 Subject: [PATCH] =?UTF-8?q?=E7=9F=A5=E8=AF=86=E5=BA=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../src/integrations/wecom/wecom-handbook.ts | 5 +- 杜康好客-知识库.md | 101 +++++++++++++++--- 2 files changed, 91 insertions(+), 15 deletions(-) diff --git a/server/dukang-api/src/integrations/wecom/wecom-handbook.ts b/server/dukang-api/src/integrations/wecom/wecom-handbook.ts index 90a8d98..d9d2a18 100644 --- a/server/dukang-api/src/integrations/wecom/wecom-handbook.ts +++ b/server/dukang-api/src/integrations/wecom/wecom-handbook.ts @@ -95,8 +95,9 @@ export const WECOM_HANDBOOK_ENTRIES: HandbookEntry[] = [ title: '系统设置', keywords: ['系统设置', 'mock', '短信', '微信', 'oss', '企微'], body: [ - 'HQ「系统设置」：功能开关、短信、微信、企微机器人、OSS、应用链接、部署、酒厂账户。', - '企微可配置客服/技术支持/团队助手三组 BotID+Secret+权限。', + 'HQ「系统设置」：功能开关、短信、微信、OSS、应用链接、部署、酒厂账户。', + '企微机器人在独立菜单「企微机器人」维护；总开关在功能开关「启用企微机器人长连接」。', + '角色：客服 / 技术支持 / 团队助手；指令式，不依赖大模型。发「帮助」看命令。', '改完可「同步到 env」；密钥类变更后注意重启标识。', ].join('\n'), }, diff --git a/杜康好客-知识库.md b/杜康好客-知识库.md index 165594f..81f69c4 100644 --- a/杜康好客-知识库.md +++ b/杜康好客-知识库.md @@ -303,7 +303,8 @@ - **权限分配**：按角色 / 按账号配置权限目录 - **HQ 账户**：创建与维护总部账号 - **技术支持工单评审** -- **系统设置** 全部分组（功能开关、短信、微信、OSS、部署等） +- **系统设置** 全部分组（功能开关、短信、微信、OSS、部署等） +- **企微机器人**（与系统设置并列；总开关仍在功能开关） ### 5.7 HQ 菜单地图（速查） @@ -321,6 +322,7 @@ | 工单 | 工单中心；技术支持 | | 发票 | 发票管理 | | 资源 / 日志 | OSS；用户/商户/合伙人/HQ/第三方日志 | +| 企微机器人 | 多实例 Bot 配置（长连接指令助手，见 §17） | | 管理 | 权限分配；系统设置；HQ 账户 | --- @@ -698,8 +700,10 @@ SLA：**2 个工作日**内处理；超时可在列表以逾期标识预警。 | Mock 微信授权 | 关闭且 AppID/Secret 齐全时走真实微信 | | Mock 配送自动完成 | 联调自动推进配送状态 | | 门店自动审核通过 | 录店免人工审（试点） | +| 启用企微机器人长连接 | 总开关；开启后连接 HQ「企微机器人」中已启用实例（见 §17） | -标注「即时」的项保存后写入运行配置即可生效；「需重启」项改完需重启 API。 +标注「即时」的项保存后写入运行配置即可生效；「需重启」项改完需重启 API。 +企微 Bot 的 BotID/Secret **不在系统设置里配置**，改在独立菜单 **企微机器人**。 ### 16.2 短信 @@ -749,7 +753,12 @@ Webhook URL / Secret，供发版流水线回调（与 `@dukang-release` 发布 --- -## 17. 企业微信对接和说明 +## 17. 企业微信对接 + +本节区分两套能力，勿混用： + +1. **C 端在线客服链接**（用户进人工会话） +2. **HQ 企微智能机器人**（内部同事用指令操作业务；命令式，**不依赖大语言模型**） ### 17.1 在线客服（微信客服 / 企微客服） @@ -764,26 +773,92 @@ C 端「联系客服 → 在线客服」跳转企业微信 **微信客服** 链 小程序端优先使用小程序客服能力；非微信环境提示拨打电话。 -### 17.2 与总部客服角色的协作 +### 17.2 HQ 企微机器人（智能机器人长连接） -1. 用户企微会话说明问题并提供订单号 -2. HQ **客服** 在用户/订单/工单中心建单或处理 -3. 需研发介入时，客服创建 **技术支持工单** 等待超管评审 -4. 退款/补发结果回传用户（短信或会话） +入口：**HQ → 企微机器人**（权限键 `wecom_bots`）。 +技术通道：企业微信「智能机器人」长连接 SDK；产品名带「智能」，本系统实现为 **关键词/指令路由**，**不必接入 AI 语言模型即可生效**。 -### 17.3 微信生态相关（易混淆对照） +#### 配置字段 + +| 字段 | 说明 | +|------|------| +| 名称 | 会话内展示用名称 | +| 角色 | 客服 / 技术支持 / 团队助手 / 自定义（决定默认权限） | +| BotID / Secret | 企微管理后台创建智能机器人后下发；每实例一对 | +| 头像 | OSS 上传（可选） | +| 欢迎语 | 进入会话时推送（可选） | +| 权限 | 可勾选能力；创建时按角色带出默认值，可改 | +| 启用 | 关闭则不建立长连接 | + +保存后可用页内 **重载连接**，或依赖总开关变更后的自动重载。每个已启用 Bot 同时仅保持 **1 条** 长连接。 + +#### 总开关 + +**系统设置 → 功能开关 → 启用企微机器人长连接**（`WECOM_AIBOT_ENABLED`）。 +总开关关闭时，即使 HQ 里已配置 Bot，也不连企微。 + +#### 预置角色与默认权限 + +| 角色 | 默认权限 | 典型用途 | +|------|----------|----------| +| 客服机器人 | 创建售后工单；查用户（短信验证）；查快递 | 客服在企微会话内快速建单、核身份、跟物流 | +| 技术支持机器人 | 创建技术支持工单；查看开发进度 | 内部提单 BUG/建议、查工单状态 | +| 团队助手 | 查询使用手册 | 按关键词答运营/协作常识（摘自知识库摘要） | +| 自定义 | 无（自行勾选） | 组合权限 | + +权限目录：`ticket.create` · `user.view_sms` · `delivery.view` · `support_ticket.create` · `support_ticket.progress` · `handbook.query`。 + +#### 常用指令（会话内发文本） + +通用：`帮助` · `状态` + +| 权限 | 指令示例 | +|------|----------| +| 售后工单 | `工单 <订单号> <类型> [备注]`（类型：仅退款 / 破损补发 / 破损退货 / 退货退款） | +| 查用户 | `查用户 <手机号>` → `验证 <验证码>`（验证通过后返回用户摘要） | +| 查快递 | `快递 <订单号\|运单号>` | +| 技术支持提单 | `提单 <标题> [| 详情]` | +| 开发进度 | `进度`（最近）· `进度 <工单号>` | +| 使用手册 | `手册`（目录）· `手册 <关键词>`（如：开城、核销、订单） | + +未识别指令时回复「帮助」文案。暂仅支持 **文本**；图片/语音等会提示改发「帮助」。 + +#### 启用步骤（运营/研发） + +1. 企业微信管理后台创建「智能机器人」，取得 BotID、Secret +2. HQ「企微机器人」创建实例，填名称/角色/凭证/权限并启用 +3. 系统设置打开 **启用企微机器人长连接** +4. 在企微中把机器人加到会话，发送 `帮助` 验证 +5. 改配置或凭证后点 **重载连接**（或重启 API） + +> **说明**：不接大模型也能完成上表能力。若日后要「口语自动抽订单号建单」，才需在现有指令路由之上叠加 LLM，属体验增强而非上线前提。 + +### 17.3 与总部客服 / 技术支持的协作 + +**人工客服链路（C 端用户）** + +1. 用户通过在线客服链接进入企微/微信客服会话，说明问题并提供订单号 +2. HQ **客服** 在用户/订单/工单中心处理，或经 **客服机器人** 用指令建售后工单 +3. 需研发介入时，在 HQ 或经 **技术支持机器人** 创建技术支持工单，超管评审 +4. 退款/补发结果回传用户（短信或会话） + +**内部同事**：优先用对应角色机器人发指令，减少反复进后台翻页；敏感查用户仍须短信验证码。 + +### 17.4 微信生态相关（易混淆对照） | 能力 | 是否企微 | 配置位置 | |------|----------|----------| -| 企微微信客服链接 | 是 | 代码常量 / `VITE_CS_WECOM_URL` | +| C 端微信客服链接 | 是（客服入口） | 代码常量 / `VITE_CS_WECOM_URL` | +| HQ 企微智能机器人 | 是（长连接指令助手） | HQ「企微机器人」+ 功能开关总开关 | | 服务号 OAuth / 支付 | 否（微信开放平台/商户） | 系统设置 → 微信 | | 小程序登录支付与首页素材 | 否 | 系统设置 → 微信 / 微信小程序 | | 微信绑定查询 | 否 | HQ「微信绑定」页（OpenID/UnionID 多端身份） | -### 17.4 运营注意 +### 17.5 运营注意 -- 更换客服链接时同步改 shared-types 默认值或各端环境变量并重新发布前端 -- 客服账号权限与会话分配在企业微信管理后台维护，本系统不托管企微通讯录 +- 更换 C 端客服链接时同步改 shared-types 默认值或各端环境变量并重新发布前端 +- 企微侧客服账号、机器人可见范围、会话分配在 **企业微信管理后台** 维护；本系统不托管企微通讯录 +- Bot Secret 仅 HQ 创建/编辑时写入，列表不回明文；泄露后应在企微后台重置并更新 HQ 配置后重载 - 工作时间话术与 PRD OPT-012 对齐（上线后 3 日内更新） ---