订阅生命周期

订阅不是「付钱就完了」。试用、激活、续费、升降级、取消、付款失败、过期，每一步都有对应的状态和处理逻辑。Pay4SaaS 会管理这整套生命周期。

状态流转

                      ┌─────────┐
                      │ pending │  ← 发起结账
                      └────┬────┘
                           │
                ┌──────────┴──────────┐
                ▼                     ▼
          ┌──────────┐          ┌──────────┐
          │ trialing │──付款──▶│  active  │◀── 续费成功 / 恢复订阅
          └────┬─────┘          └────┬─────┘
               │                     │
               │ 试用结束付款失败     │ 用户取消，到期生效
               ▼                     ▼
          ┌──────────┐          ┌───────────┐
          │ past_due │          │ canceling │
          └────┬─────┘          └─────┬─────┘
               │                      │ 到期
      ┌────────┴────────┐             ▼
      ▼                 ▼       ┌──────────┐
  ┌────────┐       ┌────────┐   │ canceled │
  │ active │       │ unpaid │   └──────────┘
  └────────┘       └───┬────┘
                       │
               ┌───────┴───────┐
               ▼               ▼
          ┌────────┐      ┌──────────┐
          │ active │      │ canceled │
          └────────┘      └──────────┘

各状态说明

对于付款失败和短暂的支付平台延迟，Pay4SaaS 会使用一个短暂宽限窗口，再完全移除访问权限。这样可以避免因为 webhook 延迟或支付平台重试还在进行，就立刻把真实付费用户断权。

宽限窗口只是临时容错，不是失败付款的续期机制。如果付款没有恢复，窗口结束后访问权限会被移除。

试用期

配置试用期后，用户首次订阅时可以免费试用。

关键规则：

• 每个用户只能试用一次
• 已试用过的用户再次订阅时，系统自动使用无试用版本的商品 ID
• 试用期间，无限订阅模式下用户可以正常使用服务
• 配额订阅模式下没有试用概念，但你可以给用户送积分体验
• 试用期结束后自动扣款，扣款成功则转为 active，扣款失败则进入 past_due 等失败付款状态

升级与降级

系统通过比较实际价格来判断升级还是降级。新价格高于当前价格，就是升级。否则按降级处理。

升级，立即生效

• 新计划立即生效
• 支付方式自动按比例计算差价
• 配额订阅模式下，配额按新计划重置

降级，下个周期生效

• 当前周期不变，保留原计划权益
• 降级会排期到下个计费周期生效
• 下次续费成功后，系统自动应用降级
• 配额订阅模式下，当前周期保留原配额

如果需要在 UI 中展示待生效的降级信息，从 billing 或 access API 返回的订阅状态读取即可，不要在前端重复实现降级判断。

取消与恢复

取消

取消分两种：

• 到期取消，默认： 状态变为 canceling，当前周期结束前仍可使用，到期后变为 canceled
• 立即取消： 状态直接变为 canceled，立即失效

恢复

用户在 canceling 状态下，可以在当前周期结束前撤销取消：

• 状态恢复为 active
• 清除取消信息
• 继续正常扣费

续费

续费是自动的。支付方式在每个计费周期结束前自动扣款，并通过 Webhook 通知系统。

续费成功时：

1. 收到续费成功的 Webhook
2. 系统延长用户当前计费周期
3. 如果有待生效的降级计划，此时自动应用
4. 配额订阅模式下，重置月度配额

如果续费失败：

1. 收到付款失败的 Webhook
2. 系统将订阅标记为逾期
3. 用户在短暂宽限期内仍可访问
4. 如果付款恢复，订阅回到 active
5. 如果付款没有恢复，宽限期结束后移除访问权限

重复订阅处理

如果用户在已有订阅的情况下又发起了一次订阅：

• 相同计划： 延长到期时间，把新周期叠加到已有订阅上
• 不同计划： 取消旧订阅，激活新订阅

乱序保护

支付方式的 Webhook 可能乱序到达，比如取消事件先于激活事件到达。Pay4SaaS 会校验每次状态转换，只允许计费周期向前推进，并忽略不应该再改变访问权限的过期事件。