用途
该技能用于把 Shopify 的订单已发货（orders/fulfilled）事件接线到 Podium 的点评请求，并在生产环境中运营投递层。它不是活动搭建教程，而是系统实际运行的集成代码，用于应对诸如黑五期间一次性发货 300 单、客户在请求发出 30 分钟后发起退款、运营商静默丢弃短信、1 星点评响应 webhook 始终未到达、以及来自其他营销流程的退订需要抑制点评请求路径等生产场景。
主要能力：六类生产故障的预防
- 冷却期内发送点评请求：客户 5 天前已收到点评请求，新的 Shopify 发货又触发一次，落在冷却窗口内，客户反感并回复 STOP，Podium 因垃圾模式量暂停账号。该技能提供冷却门。
- Shopify 发货事件与退款的竞态：订单发货触发 webhook、发出点评请求，30 分钟后客户发起退款，请求即显得尴尬且损害品牌。技能通过缓冲期解决。
- 发送静默拒绝：Podium 接受 POST /v4/review-invitations 并返回 200 与 invitation_id，但数小时后运营商实际短信发送被拒。集成误以为成功，商家点评速度悄然下降。技能提供发送失败检测。
- 点评响应 webhook 丢失：客户留下 1 星点评，Podium 触发 review.received webhook，接收方因部署返回 500，Podium 重试 3 次后放弃。技能提供持久化、重放与幂等处理。
- 多平台路由错误配置：活动配置将点评请求路由到 Facebook，但客户没有 Facebook，请求悄然未落地，而 Podium 响应显示 delivered。技能提供按客户平台校验。
- 退订合规缺口：客户 6 个月前退订营销短信，但退订标志只存在于邮件营销流程，点评请求流程有自己的同意路径并照常发送，导致 TCPA 投诉。技能提供统一退订检查。
前置条件
- Python 3.10+，含 httpx 与 redis（或使用 sqlite3 作为 SQLite 冷却后端）
- 通过 podium-auth 同级技能认证的 Podium OAuth 应用，本技能假设 auth.get_token() 可用
- 配置了 orders/fulfilled webhook 并指向本集成的 Shopify 商店
- Redis（生产）或 SQLite（单节点）用于冷却状态，以电话号码为键，值为 last_contact_at epoch 秒
- 用于 Podium review.received webhook 的持久收件箱，见 podium-webhook-reliability 同级技能的持久队列模式
- 一个退订单一真值表，将营销短信、事务短信和点评流程的退订聚合为联系人级布尔值，见 podium-contact-dedup 同级技能的合并语义
使用方式
按顺序构建，每一节消除一类生产故障模式。
1. 冷却门：冷却为联系人级速率限制，而非活动级。按规范化 E.164 电话作为键存储 last_contact_at，默认冷却窗口 30 天，可在 config/settings.yaml 按商家调整。mark_sent 在 Podium 接受 API 调用后运行，但冷却门是决策门，绝不能让两个并发的 webhook 处理器都通过检查并都发送。
2. 退款竞态缓冲：Shopify 的 orders/fulfilled 会在商家标记包裹已打包贴单时触发，客户收到包裹以及退款决策窗口在此后数小时到数天。以可配置延迟（默认自发货时间起 5 天）缓冲发送，并在发送时重新检查订单退款状态。延迟队列必须能跨进程重启存活，可使用 Redis streams、带 DLQ 的 SQS 或 Postgres 的 pgmq。
3. 发送失败检测：Podium API 的 POST /v4/review-invitations 响应只确认邀请记录已创建，不确认短信已送达运营商。应单独订阅 review_invitation.failed 和 review_invitation.delivered webhook，按 invitation_id 持久化，并在 24 小时 SLA 窗口后对账投递状态。发送失败时回滚冷却，因为客户从未收到消息，阻止其未来接收请求是错误的。
4. 点评响应 webhook 处理器：Podium 在客户于任一已路由平台留下点评时触发 review.received。webhook 必须幂等（Podium 对任何非 2xx 最多重试 3 次），并须分类情感，使负面点评升级而正面点评进入致谢流程。
5. 多平台路由校验：在请求时根据客户资料校验平台路由，当配置目标不确定时回退到已知可用的默认值（Podium 自己的 webchat 点评）。优先级为：客户显式偏好 > 活动默认 > podium-webchat 回退。对未知平台客户倾向 Google 而非 Facebook，因为 Google 点评无需登录账号即可渲染，而 Facebook 点评需要登录账号。
6. 统一退订检查：客户对任一流程退订，都应抑制所有触及该客户的流程。统一检查置于 mark_sent 之前。必须在排期时和触发时都运行同一断言，在 5 天退款缓冲期内退订的联系人不得收到已排期的发送。
错误处理
- 400 Bad Request / invalid_phone：号码非 E.164 或不可达，跳过并记录，不重试。
- 409 Conflict / cooldown_violation：Podium 侧冷却拒绝发送，信任 Podium，记录并跳过，不绕过。
- 429 Too Many Requests / rate_limited：触达活动速率限制，遵守 Retry-After，见 podium-rate-limit-survival。
- review_invitation.failed / carrier_filtered：运营商拒绝短信，回滚冷却，标记该号码待人工复查。
- review_invitation.failed / recipient_optout：客户回复 STOP，在联系人上标记 podium_keyword_optout=true，并传播到退订单一真值表。
- review.received：校验签名、分类情感、路由。
- 签名不匹配：返回 401，不处理；持续性不匹配需告警（可能密钥轮换漂移）。
适用场景与限制
适用于使用 Shopify 与 Podium、需要在生产环境稳定运行点评请求投递层的场景。技能依赖 Podium OAuth、Shopify webhook、Redis 或 SQLite、持久 webhook 收件箱及联系人合并退订表等外部条件。文档中的冷却天数、退款缓冲天数、评分阈值等为默认示例值，可按商家配置调整。有关收费、价格、平台支持范围及其他未在资料中明确的信息暂未提供。