用途:解决外部服务通过 webhook 通知应用时可能出现的静默失败、乱序、重复或事件完全丢失,导致本地数据库与真实来源不一致的问题。核心原则是“webhook 求快,对账求准”:webhook 做实时乐观更新,周期性对账做防御性纠偏。
主要能力:提供四种模式。一是定时对账,用 cron 任务比对本地状态与外部服务(如 Stripe 订阅),发现漂移即修正,示例按每小时运行。二是按需对账,针对单个用户报告问题时拉取外部当前状态并修复。三是事件重放,按时间戳和事件类型拉取遗漏事件,跳过已处理事件后重新处理。四是幂等 webhook 处理,先按事件 ID 查重、记录后再处理,保证可安全重放。另附漂移诊断查询,用于找出订阅状态与 Stripe ID 不匹配或长时间未同步的用户。
使用方式:资料给出 Convex 风格的 internalAction、action、internalQuery 与 crons.ts 示例,涉及 Stripe SDK 调用(subscriptions.list、customers.retrieve、events.list)及内部查询/变更函数。对账时机建议:高价值数据每小时、用户资料每日、历史数据每周;也可在用户投诉、支持升级、事故恢复后、webhook 失败告警后或部署后触发。
最佳实践与限制:应记录所有漂移的前后值、存储事件 ID 保证幂等、分页拉取、限流避免触发 API 限制、对显著漂移告警;不应把本地状态当作外部数据的真实来源、不应跳过幂等检查、不应过于频繁对账、不应忽略失败的对账。资料还引用 stripe-reconciliation、clerk-reconciliation、monitoring 等参考文档,以及 stripe-best-practices、clerk-auth、verify-fix 等相关技能。具体安装命令、收费与平台支持暂未提供。