更新

server/docs/qywx_promotion.md

@@ -30,15 +30,15 @@ HOST = "https://公开访问域名"
 - 更新获客链接 `update_link`
 - 删除获客链接 `delete_link`
 
-当前管理端按“一个分流方案对应一个官方获客链接”管理。删除分流方案只软删除本地记录，不调用企业微信 `delete_link`，因此不会破坏已有客户归因；官方永久删除接口仅保留给兼容接口使用，调用后无法恢复。
+当前管理端按“一个分流方案对应一个官方获客链接”管理。删除方案时先调用企业微信 `delete_link` 永久删除关联的官方链接，成功后再软删除本地方案、成员和链接记录；如果企业微信删除失败，本地方案会保留并返回错误，避免两端状态不一致。官方链接删除后无法恢复，已投放 URL 会失效，历史本地客户归因记录仍保留。
 
 获客成员来自后台管理员的 `work_wechat_userid`。管理员可管理全量；组长、医助等账号只返回 `DataScopeService` 当前角色与部门范围内的成员。同步远端链接时，非全量账号只导入 `range.user_list` 与其可见成员有交集的数据；企业微信部门 ID 尚未建立本地映射时按安全原则隐藏，不会越权放行。
 
 `list_link` 只返回当前获客助手可调用应用通过 API 创建的官方链接。后台历史手工粘贴的 `work.weixin.qq.com/ca/...` 链接，以及其他应用创建的链接，不会出现在当前应用的同步列表中，也无法仅凭 URL 反查为官方 `link_id`。需要官方客户、统计和消息归因时，应在本页面创建分流方案并选择获客成员。
 
-创建分流方案时必须选择一名或多名医助。所有医助分别保存启用状态、权重、每日上限、有效时间和实际获客计数，但一个方案仍只创建一条企业微信官方链接。官方链接当前的 `range.user_list` 只放调度器选中的一名成员，回调确认实际承接结果后再按权重随机抽取下一名并更新同一个 `link_id`，因此对外 URL 始终不变。
+创建分流方案时必须选择一名或多名医助。一个方案只创建一条企业微信官方链接，当前全部可用医助会同时写入该链接的 `range.user_list`，由企业微信在打开、添加阶段执行官方多人路由。成员可配置启用状态、每日上限和有效时间，系统按实际获客回调累计数量。
 
-新建方案时的首名成员也会从所选医助中随机产生；编辑已有方案时，如果当前成员仍可用则保持不变，避免无获客事件时无故切换。
+企业微信 `range.user_list` 只接受成员 userid 列表，不提供逐成员权重字段，因此本站不再展示或执行 2:1:1 一类权重规则。官方多人路由的实际承接还会受到成员可服务状态、客户已有好友关系等企业微信规则影响，不能承诺每次刷新严格随机或短期样本绝对平均。
 
 系统只使用企业微信获客助手生成的链接：
 
@@ -56,7 +56,7 @@ https://work.weixin.qq.com/ca/xxxxxxxx?customer_channel=zyt_pool:123
 
 其中 `customer_channel` 是本站写入的自定义渠道值，格式为 `zyt_pool:分流方案ID`；它与示例中的 `qywx_ca:...` 作用相同，但命名空间和数值由各系统自行定义。
 
-## 回调驱动成员调度
+## 回调统计与成员范围维护
 
 部署时必须执行：
 
@@ -70,11 +70,11 @@ server/sql/1.9.20260824/upgrade_qywx_promotion_member_dispatch.sql
 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` 作为补偿。方案、成员和客户组合使用唯一幂等键，同一实际获客不会因重复回调重复计数。
+回调优先使用 `change_external_contact/add_external_contact` 事件中的 `State`、`UserID` 和 `ExternalUserID`。`State` 来自主链接的 `customer_channel=zyt_pool:方案ID`，因此可以定位方案及实际承接医助；获客会话回调会通过 `ChatKey → get_chat_info` 作为补偿。方案和客户组合使用唯一幂等键，同一实际获客不会因重复回调或后续更换跟进成员而重复计数。
 
-每次确认实际承接后，系统执行加权随机抽取：权重越大，被抽中的概率越高；禁用、尚未生效、已过期或达到今日上限的成员不会进入随机池。随机允许连续抽中同一成员。待同步范围由 `qywx:sync-promotion-ranges` 每分钟重试，管理端主动禁用当前成员时也会立即尝试同步。
+创建或编辑方案时，系统把所有已启用、已生效且未达到今日上限的成员一次写入同一个官方链接。禁用、尚未生效、已过期或达到今日上限的成员会从官方范围移出；跨日或重新进入有效期后会自动加入。`qywx:sync-promotion-ranges` 每分钟重算全部方案并重试失败同步，管理端修改成员规则时也会立即尝试同步。
 
-权重和数量属于回调驱动的近实时控制，并非点击前的强事务：多个客户在企微回调或 `update_link` 生效前并发访问时，可能仍由同一成员承接；所有成员都达到上限时，企业微信不允许把 `range.user_list` 更新为空，系统会标记“无可用成员”并保留最后一次有效范围。因此数量上限用于自动退出后续调度，不承诺并发场景下绝对零超量。
+每日数量属于回调驱动的近实时软上限，并非点击前的强事务：多个客户在企微回调或 `update_link` 生效前并发访问时，可能出现少量超量；所有成员都达到上限时，企业微信不允许把 `range.user_list` 更新为空，系统会标记“无可用成员”并保留最后一次有效范围。因此该上限用于自动退出后续官方路由，不承诺并发场景下绝对零超量。
 
 如果需要为点击 IP 生成不可逆服务端哈希，可在 `[qywx_promotion]` 下额外设置独立的 `CREDENTIAL_KEY`。
 
@@ -124,4 +124,4 @@ window.WecomPromotion['分流方案KEY'].destroy()
 
 旧 `/go` 兼容入口记录点击来源时，只保存页面的 origin 与 pathname，不包含查询参数或 fragment。推广页路径中也不应放置手机号、患者 ID、重置令牌等敏感信息。
 
-用户始终看到同一个企业微信官方获客链接。当前激活成员由本站根据实际回调、启用状态、权重和上限动态更新；企业微信仍可能根据成员可服务状态和已有好友关系等规则影响最终承接结果，后续回调会按实际结果自动纠偏。
+用户始终看到同一个企业微信官方获客链接。本站只维护该链接的可用成员集合，实际多人分流由企业微信完成；回调负责记录实际承接结果，并在成员达到上限后更新集合。