公众号订阅用户运行时支撑契约说明
查看文档来源信息
- 来源目录：
addons/sys_base/docs - 来源文件：
契约说明/公众号订阅用户运行时支撑契约说明.md
能力定位
- “公众号订阅用户”在中间件中的正式定位是“微信接入支撑能力”。
- 本能力保留 H5 登录、公众号绑定、openid/unionid 关联和必要同步写入能力。
- 本能力不是中间件治理主能力，不扩成系统治理页、应用治理页或 PCWEB 台账页。
当前正式口径
app_wechat_subscribe_user表实体保留，继续承接微信接入运行时数据。getSubscribeUserByOpenid只允许服务态受控调用，必须提供明确app-id。getSubscribeUserByOpenid的正式查询链路是：app-id + openid -> app_user_band -> unionid -> app_wechat_subscribe_usergetSubscribeUserByUnionid只允许服务态受控调用，必须提供明确app-id，仅用于绑定桥接、登录支撑或其他已确认正式链路。- 两个查询接口的正式返回口径统一收敛为：
openid、unionID、appId、subscribe。 - H5 授权写入与批量同步写入统一收口到
WechatSubscribeUserService，不再由 public API 层直接拼 SQL 或维护粗放流程。
运行规则
X-System-Key不能再通过系统只读白名单直接访问上述两个查询接口。X-App-Key + x-token形成的 user mode 不能复用上述两个查询接口。- H5 静默授权与用户信息授权产生的订阅用户写入，必须复用统一的单条保存/更新服务。
- 批量同步由统一服务负责：
- 负责拉取公众号用户列表
- 负责逐条拉取用户详情
- 负责单条保存或更新
- 负责同步状态写回
- 负责失败明细记录
- 同步游标按“稳定成功游标”推进：
- 在首次失败之前成功写入的最后一个 openid 记为稳定游标
- 出现失败后，后续成功记录可以继续落库，但游标不再越过首个失败点
- 下一轮同步从稳定游标继续，确保失败区间可以被重放
- 如需数据修复，只允许输出文档和脚本设计，不直接删除历史数据。
不允许的做法
- 不允许把本能力恢复为后台治理数据页。
- 不允许把本能力重新挂到系统治理菜单、应用治理菜单或 PCWEB 普通治理能力中。
- 不允许把
getSubscribeUserByUnionid当作宽松 public convenience 查询口继续复用。 - 不允许继续使用
fmt.Printf、调试残留字符串或REPLACE INTO粗放写法作为正式实现。 - 不允许无差别返回订阅用户完整实体给服务态查询接口。
- 不允许为了兼容旧调用而长期保留宽松 public 查询边界。
维护提示
- 下游若只需要判断是否已关注或桥接公众号身份，应优先使用最小返回结果，不得自行要求恢复全量字段。
- 新增微信接入链路时，优先复用
WechatSubscribeUserService，不要在新的 handler 中直接写app_wechat_subscribe_user。 - 若未来出现多公众号并行桥接场景，应在确认业务边界后补充更细的 app 约束，而不是回退到无上下文 unionid 查询。