更新
This commit is contained in:
Your Name
@@ -30,19 +30,51 @@ HOST = "https://公开访问域名"
|
||||
- 更新获客链接 `update_link`
|
||||
- 删除获客链接 `delete_link`
|
||||
|
||||
“永久删除企业微信链接”会调用官方删除接口且无法恢复；“从本地移除”只退出当前分流池，不会修改企业微信后台。
|
||||
当前管理端按“一个分流方案对应一个官方获客链接”管理。删除分流方案只软删除本地记录，不调用企业微信 `delete_link`，因此不会破坏已有客户归因；官方永久删除接口仅保留给兼容接口使用，调用后无法恢复。
|
||||
|
||||
获客成员来自后台管理员的 `work_wechat_userid`。管理员可管理全量；组长、医助等账号只返回 `DataScopeService` 当前角色与部门范围内的成员。同步远端链接时，非全量账号只导入 `range.user_list` 与其可见成员有交集的数据；企业微信部门 ID 尚未建立本地映射时按安全原则隐藏，不会越权放行。
|
||||
|
||||
`list_link` 只返回当前获客助手可调用应用通过 API 创建的官方链接。后台历史手工粘贴的 `work.weixin.qq.com/ca/...` 链接，以及其他应用创建的链接，不会出现在当前应用的同步列表中，也无法仅凭 URL 反查为官方 `link_id`。需要官方客户、统计和消息归因时，应在本页面使用“创建官方获客链接”。
|
||||
`list_link` 只返回当前获客助手可调用应用通过 API 创建的官方链接。后台历史手工粘贴的 `work.weixin.qq.com/ca/...` 链接，以及其他应用创建的链接，不会出现在当前应用的同步列表中，也无法仅凭 URL 反查为官方 `link_id`。需要官方客户、统计和消息归因时，应在本页面创建分流方案并选择获客成员。
|
||||
|
||||
链接分流只接受企业微信获客助手生成的链接：
|
||||
创建分流方案时必须选择一名或多名医助。所有医助分别保存启用状态、权重、每日上限、有效时间和实际获客计数，但一个方案仍只创建一条企业微信官方链接。官方链接当前的 `range.user_list` 只放调度器选中的一名成员，回调确认实际承接结果后再按权重随机抽取下一名并更新同一个 `link_id`，因此对外 URL 始终不变。
|
||||
|
||||
新建方案时的首名成员也会从所选医助中随机产生；编辑已有方案时，如果当前成员仍可用则保持不变，避免无获客事件时无故切换。
|
||||
|
||||
系统只使用企业微信获客助手生成的链接：
|
||||
|
||||
```text
|
||||
https://work.weixin.qq.com/ca/xxxxxxxx
|
||||
```
|
||||
|
||||
“联系我”、客户群、自有网页或其他外部链接均会被拒绝；已有的非获客助手历史链接也不会参与随机分流。Secret 与 access_token 不会返回到浏览器，也不会写入接口错误日志。
|
||||
“联系我”、客户群、自有网页或其他外部链接均会被拒绝；已有的非获客助手历史链接不会作为方案主链接。Secret 与 access_token 不会返回到浏览器，也不会写入接口错误日志。
|
||||
|
||||
可复制的主链接会追加分流方案渠道参数，结构如下：
|
||||
|
||||
```text
|
||||
https://work.weixin.qq.com/ca/xxxxxxxx?customer_channel=zyt_pool:123
|
||||
```
|
||||
|
||||
其中 `customer_channel` 是本站写入的自定义渠道值，格式为 `zyt_pool:分流方案ID`；它与示例中的 `qywx_ca:...` 作用相同，但命名空间和数值由各系统自行定义。
|
||||
|
||||
## 回调驱动成员调度
|
||||
|
||||
部署时必须执行：
|
||||
|
||||
```text
|
||||
server/sql/1.9.20260824/upgrade_qywx_promotion_member_dispatch.sql
|
||||
```
|
||||
|
||||
并在企业微信后台把“API 接收消息”配置为：
|
||||
|
||||
```text
|
||||
https://你的域名/api/qywx/external-contact/notify
|
||||
```
|
||||
|
||||
调度优先使用 `change_external_contact/add_external_contact` 事件中的 `State`、`UserID` 和 `ExternalUserID`。`State` 来自主链接的 `customer_channel=zyt_pool:方案ID`，因此可以定位方案及实际承接医助；获客会话回调会通过 `ChatKey → get_chat_info` 作为补偿。方案、成员和客户组合使用唯一幂等键，同一实际获客不会因重复回调重复计数。
|
||||
|
||||
每次确认实际承接后，系统执行加权随机抽取：权重越大，被抽中的概率越高；禁用、尚未生效、已过期或达到今日上限的成员不会进入随机池。随机允许连续抽中同一成员。待同步范围由 `qywx:sync-promotion-ranges` 每分钟重试，管理端主动禁用当前成员时也会立即尝试同步。
|
||||
|
||||
权重和数量属于回调驱动的近实时控制，并非点击前的强事务：多个客户在企微回调或 `update_link` 生效前并发访问时，可能仍由同一成员承接；所有成员都达到上限时，企业微信不允许把 `range.user_list` 更新为空，系统会标记“无可用成员”并保留最后一次有效范围。因此数量上限用于自动退出后续调度，不承诺并发场景下绝对零超量。
|
||||
|
||||
如果需要为点击 IP 生成不可逆服务端哈希，可在 `[qywx_promotion]` 下额外设置独立的 `CREDENTIAL_KEY`。
|
||||
|
||||
@@ -50,9 +82,11 @@ https://work.weixin.qq.com/ca/xxxxxxxx
|
||||
|
||||
```html
|
||||
<script src="https://你的域名/api/qywx-promotion/js/分流方案KEY" defer></script>
|
||||
<a href="https://你的域名/api/qywx-promotion/go/分流方案KEY" data-wecom-promotion="分流方案KEY">添加企业微信</a>
|
||||
<a href="https://work.weixin.qq.com/ca/xxxxxxxx?customer_channel=zyt_pool:123">添加企业微信</a>
|
||||
```
|
||||
|
||||
旧的 `/api/qywx-promotion/go/分流方案KEY` 地址继续保留，兼容已经投放的安装代码；新建方案、管理端复制链接和新版浮窗均直接打开官方获客链接。
|
||||
|
||||
## 公开浮窗
|
||||
|
||||
每个分流方案可选择是否由同一段公开 JS 自动挂载客服浮窗。关闭浮窗时，已有的
|
||||
@@ -66,7 +100,7 @@ https://work.weixin.qq.com/ca/xxxxxxxx
|
||||
- 标题、副标题、按钮文案和 `#RRGGBB` 主题色
|
||||
- 16-160 像素底部距离、移动端展示开关和浮窗总开关
|
||||
|
||||
公开脚本仅下发经过白名单校验的展示配置，不下发兜底链接或真实获客链接池。模板
|
||||
公开脚本仅下发经过白名单校验的展示配置和当前方案的单个官方目标链接，不下发历史链接池或 Secret。模板
|
||||
由脚本内置，管理端文案通过 DOM `textContent` 写入，不接受自定义 HTML、CSS 或脚本。
|
||||
损坏配置、未知版本和非法枚举会按关闭浮窗处理。
|
||||
|
||||
@@ -79,10 +113,7 @@ window.WecomPromotion['分流方案KEY'].hide()
|
||||
window.WecomPromotion['分流方案KEY'].destroy()
|
||||
```
|
||||
|
||||
公开脚本缓存 60 秒，因此浮窗样式或开关更新最多延迟约 60 秒；方案运行状态仍会在
|
||||
每次服务端跳转时即时校验。脚本会从自身 `src` 解析跳转接口域名，不会把公开请求的
|
||||
Host 写入缓存内容。管理端安装代码优先使用 `[app] HOST`，请在生产环境配置唯一的
|
||||
HTTPS 公开域名。
|
||||
公开脚本缓存 60 秒，因此浮窗样式、开关或官方目标链接更新最多延迟约 60 秒。新版浮窗直接打开企业微信官方链接，不再经过本站逐次 302；已经复制到外部的官方链接也不会因本地关闭方案而失效。管理端安装代码优先使用 `[app] HOST`，请在生产环境配置唯一的 HTTPS 公开域名。
|
||||
|
||||
接入站点若启用了严格 CSP，需要允许脚本域名，并给安装 `<script>` 添加站点当前请求
|
||||
的 `nonce`。公开脚本会把该 `nonce` 传给 Shadow DOM 内的动态样式：
|
||||
@@ -91,7 +122,6 @@ HTTPS 公开域名。
|
||||
<script nonce="当前请求的 nonce" src="https://你的域名/api/qywx-promotion/js/分流方案KEY" defer></script>
|
||||
```
|
||||
|
||||
点击来源只上报页面的 origin 与 pathname，不包含查询参数或 fragment。推广页路径中也
|
||||
不应放置手机号、患者 ID、重置令牌等敏感信息。
|
||||
旧 `/go` 兼容入口记录点击来源时，只保存页面的 origin 与 pathname，不包含查询参数或 fragment。推广页路径中也不应放置手机号、患者 ID、重置令牌等敏感信息。
|
||||
|
||||
随机分流在服务端完成。候选链接必须同时满足：方案启用、链接上线、处于有效时间段、未超过当日上限。权重越大，被选中的概率越高。
|
||||
用户始终看到同一个企业微信官方获客链接。当前激活成员由本站根据实际回调、启用状态、权重和上限动态更新；企业微信仍可能根据成员可服务状态和已有好友关系等规则影响最终承接结果，后续回调会按实际结果自动纠偏。
|
||||
|
||||
Reference in New Issue
Block a user