5.1 KiB
企业微信获客助手配置
管理端菜单：一诊 / 企业微信获客助手
该功能使用当前企业的内部自建应用配置，不使用服务商第三方应用，也不需要 SuiteID、suite_ticket、永久授权码或企业扫码安装。
系统直接复用 server/.env 已有配置：
[work_wechat]
CORP_ID = "当前企业 CorpID"
AGENT_ID = "内部自建应用 AgentID"
CUSTOMER_ACQUISITION_SECRET = "获客助手可调用应用的 Secret"
[app]
HOST = "https://公开访问域名"
兼容已有项目：没有 CUSTOMER_ACQUISITION_SECRET 时，会依次回退读取 AGENT_SECRET、SECRET。如果现有 SECRET 就是获客助手中配置的“可调用应用”Secret，无需重复配置。
企业微信管理后台还需完成三项外部配置：开通获客助手、将该内部应用设置为获客助手可调用应用、将接口服务器公网 IP 加入可信 IP。页面“验证获客助手 API”会通过只读列表接口检查这些条件。
官方 API 对接范围
按企业微信获客链接管理文档完成以下五个接口：
- 获取获客链接列表
list_link - 获取获客链接详情
get - 创建获客链接
create_link - 更新获客链接
update_link - 删除获客链接
delete_link
“永久删除企业微信链接”会调用官方删除接口且无法恢复；“从本地移除”只退出当前分流池，不会修改企业微信后台。
获客成员来自后台管理员的 work_wechat_userid。管理员可管理全量；组长、医助等账号只返回 DataScopeService 当前角色与部门范围内的成员。同步远端链接时，非全量账号只导入 range.user_list 与其可见成员有交集的数据；企业微信部门 ID 尚未建立本地映射时按安全原则隐藏，不会越权放行。
list_link 只返回当前获客助手可调用应用通过 API 创建的官方链接。后台历史手工粘贴的 work.weixin.qq.com/ca/... 链接，以及其他应用创建的链接，不会出现在当前应用的同步列表中，也无法仅凭 URL 反查为官方 link_id。需要官方客户、统计和消息归因时，应在本页面使用“创建官方获客链接”。
链接分流只接受企业微信获客助手生成的链接：
https://work.weixin.qq.com/ca/xxxxxxxx
“联系我”、客户群、自有网页或其他外部链接均会被拒绝；已有的非获客助手历史链接也不会参与随机分流。Secret 与 access_token 不会返回到浏览器，也不会写入接口错误日志。
如果需要为点击 IP 生成不可逆服务端哈希，可在 [qywx_promotion] 下额外设置独立的 CREDENTIAL_KEY。
公开 JS 示例：
<script src="https://你的域名/api/qywx-promotion/js/分流方案KEY" defer></script>
<a href="https://你的域名/api/qywx-promotion/go/分流方案KEY" data-wecom-promotion="分流方案KEY">添加企业微信</a>
公开浮窗
每个分流方案可选择是否由同一段公开 JS 自动挂载客服浮窗。关闭浮窗时，已有的
data-wecom-promotion、.wecom-promotion-link[data-pool] 和
window.WecomPromotion[KEY].open() 手动触发方式仍然可用。
浮窗配置保存在分流方案的 widget_config_json 中。当前配置版本为 v=1，支持：
- 模板：
bubble、pill、card、message、edge、bar - 位置：
bottom-right、bottom-left - 标题、副标题、按钮文案和
#RRGGBB主题色 - 16-160 像素底部距离、移动端展示开关和浮窗总开关
公开脚本仅下发经过白名单校验的展示配置，不下发兜底链接或真实获客链接池。模板
由脚本内置，管理端文案通过 DOM textContent 写入，不接受自定义 HTML、CSS 或脚本。
损坏配置、未知版本和非法枚举会按关闭浮窗处理。
脚本会暴露以下运行时方法：
window.WecomPromotion['分流方案KEY'].open()
window.WecomPromotion['分流方案KEY'].show()
window.WecomPromotion['分流方案KEY'].hide()
window.WecomPromotion['分流方案KEY'].destroy()
公开脚本缓存 60 秒，因此浮窗样式或开关更新最多延迟约 60 秒；方案运行状态仍会在
每次服务端跳转时即时校验。脚本会从自身 src 解析跳转接口域名，不会把公开请求的
Host 写入缓存内容。管理端安装代码优先使用 [app] HOST，请在生产环境配置唯一的
HTTPS 公开域名。
接入站点若启用了严格 CSP，需要允许脚本域名，并给安装 <script> 添加站点当前请求
的 nonce。公开脚本会把该 nonce 传给 Shadow DOM 内的动态样式：
<script nonce="当前请求的 nonce" src="https://你的域名/api/qywx-promotion/js/分流方案KEY" defer></script>
点击来源只上报页面的 origin 与 pathname，不包含查询参数或 fragment。推广页路径中也 不应放置手机号、患者 ID、重置令牌等敏感信息。
随机分流在服务端完成。候选链接必须同时满足：方案启用、链接上线、处于有效时间段、未超过当日上限。权重越大，被选中的概率越高。