更新

server/docs/qywx_promotion.md

@@ -11,6 +11,9 @@
 CORP_ID = "当前企业 CorpID"
 AGENT_ID = "内部自建应用 AgentID"
 CUSTOMER_ACQUISITION_SECRET = "获客助手可调用应用的 Secret"
+
+[app]
+HOST = "https://公开访问域名"
 ```
 
 兼容已有项目：没有 `CUSTOMER_ACQUISITION_SECRET` 时，会依次回退读取 `AGENT_SECRET`、`SECRET`。如果现有 `SECRET` 就是获客助手中配置的“可调用应用”Secret，无需重复配置。
@@ -47,7 +50,48 @@ https://work.weixin.qq.com/ca/xxxxxxxx
 
 ```html
 <script src="https://你的域名/api/qywx-promotion/js/分流方案KEY" defer></script>
-<a href="#" data-wecom-promotion="分流方案KEY">添加企业微信</a>
+<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、重置令牌等敏感信息。
+
 随机分流在服务端完成。候选链接必须同时满足：方案启用、链接上线、处于有效时间段、未超过当日上限。权重越大，被选中的概率越高。