更新

server/docs/qywx_promotion.md

@@ -1,37 +1,48 @@
-# 企业微信推广助手配置
+# 企业微信获客助手配置
 
-管理端菜单：`一诊 / 企业微信推广助手`
+管理端菜单：`一诊 / 企业微信获客助手`
 
-该功能使用企业微信“服务商第三方应用”授权模式。服务商参数只保存在服务器环境变量中，企业永久授权码会使用 AES-256-GCM 加密后存入数据库。
+该功能使用当前企业的内部自建应用配置，不使用服务商第三方应用，也不需要 SuiteID、suite_ticket、永久授权码或企业扫码安装。
 
-在 `server/.env` 中增加：
+系统直接复用 `server/.env` 已有配置：
 
 ```ini
-[qywx_promotion]
-ENABLED = true
-PROVIDER_CORP_ID = "服务商企业 CorpID"
-SUITE_ID = "第三方应用 SuiteID"
-SUITE_SECRET = "第三方应用 SuiteSecret"
-TOKEN = "应用指令回调 Token"
-AES_KEY = "应用指令回调 EncodingAESKey"
-CREDENTIAL_KEY = "至少32字节的独立随机密钥"
-REDIRECT_URI = "https://你的域名/api/qywx-promotion/auth/callback"
-ADMIN_RETURN_URL = "https://你的域名/admin/first_visit/wecom_promotion"
+[work_wechat]
+CORP_ID = "当前企业 CorpID"
+AGENT_ID = "内部自建应用 AgentID"
+CUSTOMER_ACQUISITION_SECRET = "获客助手可调用应用的 Secret"
 ```
 
-企业微信服务商后台需要配置：
+兼容已有项目：没有 `CUSTOMER_ACQUISITION_SECRET` 时，会依次回退读取 `AGENT_SECRET`、`SECRET`。如果现有 `SECRET` 就是获客助手中配置的“可调用应用”Secret，无需重复配置。
 
-- 应用指令回调 URL：`https://你的域名/api/qywx-promotion/provider/callback`
-- 授权完成回调域名：与你的 `REDIRECT_URI` 域名一致
+企业微信管理后台还需完成三项外部配置：开通获客助手、将该内部应用设置为获客助手可调用应用、将接口服务器公网 IP 加入可信 IP。页面“验证获客助手 API”会通过只读列表接口检查这些条件。
 
-保存配置并让企业微信成功推送一次 `suite_ticket` 后，管理端的“发起企业授权”按钮才会生成安装链接。
+## 官方 API 对接范围
 
-推广链接默认仅允许企业微信官方域名。如需跳转企业自有的可信中间页，可在环境变量中追加：
+按[企业微信获客链接管理文档](https://developer.work.weixin.qq.com/document/path/97297)完成以下五个接口：
 
-```ini
-ALLOWED_LINK_HOSTS = "promo.example.com,crm.example.com"
+- 获取获客链接列表 `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
@@ -39,4 +50,4 @@ ALLOWED_LINK_HOSTS = "promo.example.com,crm.example.com"
 <a href="#" data-wecom-promotion="分流方案KEY">添加企业微信</a>
 ```
 
-随机分流在服务端完成。候选链接必须同时满足：方案启用、链接上线、授权企业有效、处于有效时间段、未超过当日上限。权重越大，被选中的概率越高。
+随机分流在服务端完成。候选链接必须同时满足：方案启用、链接上线、处于有效时间段、未超过当日上限。权重越大，被选中的概率越高。