zyt/server/docs/qywx_promotion.md

企业微信推广助手配置

管理端菜单：一诊 / 企业微信推广助手

该功能使用企业微信“服务商第三方应用”授权模式。服务商参数只保存在服务器环境变量中，企业永久授权码会使用 AES-256-GCM 加密后存入数据库。

在 server/.env 中增加：

[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 后，管理端的“发起企业授权”按钮才会生成安装链接。

推广链接默认仅允许企业微信官方域名。如需跳转企业自有的可信中间页，可在环境变量中追加：

ALLOWED_LINK_HOSTS = "promo.example.com,crm.example.com"

公开 JS 示例：

<script src="https://你的域名/api/qywx-promotion/js/分流方案KEY" defer></script>
<a href="#" data-wecom-promotion="分流方案KEY">添加企业微信</a>

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