# 企业微信获客助手配置

管理端菜单：`一诊 / 企业微信获客助手`

该功能使用当前企业的内部自建应用配置，不使用服务商第三方应用，也不需要 SuiteID、suite_ticket、永久授权码或企业扫码安装。

系统直接复用 `server/.env` 已有配置：

```ini
[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 对接范围

按[企业微信获客链接管理文档](https://developer.work.weixin.qq.com/document/path/97297)完成以下五个接口：

- 获取获客链接列表 `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`。需要官方客户、统计和消息归因时，应在本页面使用“创建官方获客链接”。

链接分流只接受企业微信获客助手生成的链接：

```text
https://work.weixin.qq.com/ca/xxxxxxxx
```

“联系我”、客户群、自有网页或其他外部链接均会被拒绝；已有的非获客助手历史链接也不会参与随机分流。Secret 与 access_token 不会返回到浏览器，也不会写入接口错误日志。

如果需要为点击 IP 生成不可逆服务端哈希，可在 `[qywx_promotion]` 下额外设置独立的 `CREDENTIAL_KEY`。

公开 JS 示例：

```html
<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 或脚本。
损坏配置、未知版本和非法枚举会按关闭浮窗处理。

脚本会暴露以下运行时方法：

```js
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 内的动态样式：

```html
<script nonce="当前请求的 nonce" src="https://你的域名/api/qywx-promotion/js/分流方案KEY" defer></script>
```

点击来源只上报页面的 origin 与 pathname，不包含查询参数或 fragment。推广页路径中也
不应放置手机号、患者 ID、重置令牌等敏感信息。

随机分流在服务端完成。候选链接必须同时满足：方案启用、链接上线、处于有效时间段、未超过当日上限。权重越大，被选中的概率越高。