更新

server/docs/qywx_promotion.md

@@ -0,0 +1,42 @@
+# 企业微信推广助手配置
+
+管理端菜单：`一诊 / 企业微信推广助手`
+
+该功能使用企业微信“服务商第三方应用”授权模式。服务商参数只保存在服务器环境变量中，企业永久授权码会使用 AES-256-GCM 加密后存入数据库。
+
+在 `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"
+```
+
+企业微信服务商后台需要配置：
+
+- 应用指令回调 URL：`https://你的域名/api/qywx-promotion/provider/callback`
+- 授权完成回调域名：与你的 `REDIRECT_URI` 域名一致
+
+保存配置并让企业微信成功推送一次 `suite_ticket` 后，管理端的“发起企业授权”按钮才会生成安装链接。
+
+推广链接默认仅允许企业微信官方域名。如需跳转企业自有的可信中间页，可在环境变量中追加：
+
+```ini
+ALLOWED_LINK_HOSTS = "promo.example.com,crm.example.com"
+```
+
+公开 JS 示例：
+
+```html
+<script src="https://你的域名/api/qywx-promotion/js/分流方案KEY" defer></script>
+<a href="#" data-wecom-promotion="分流方案KEY">添加企业微信</a>
+```
+
+随机分流在服务端完成。候选链接必须同时满足：方案启用、链接上线、授权企业有效、处于有效时间段、未超过当日上限。权重越大，被选中的概率越高。