用途：在本地数据库中保存 Paddle 订阅与客户状态的副本，用于按订阅状态控制功能访问、渲染账户页面而无需每次调用 Paddle API，以及收入报表。前提是已具备带签名校验的 Webhook 端点，以及支持 UPSERT 的 SQL 数据库（示例用 Supabase）。
主要能力：定义 customers 与 subscriptions 两张最小表结构（含 customer_id、email、subscription_status、price_id、product_id、scheduled_change 等字段及索引）；订阅 customer.created/updated、subscription.created/updated/canceled 事件，可选 transaction.completed、subscription.activated；以 subscription_id 为键做 UPSERT，保证幂等与状态收敛。
使用方式：在 Webhook 路由处理器内按事件类型分发到 upsertSubscription/upsertCustomer；用 email 作为应用用户与 Paddle 客户的桥接，通过 getCustomerId 查询；读取一律走本地库，仅取消、暂停、恢复、升级、退款等写操作调用 Paddle API。Webhook 处理器须使用 service role key 的客户端（如 server-internal.ts），不能用 anon key，否则会被 RLS 拦截。
状态语义：active、trialing 通常允许访问；past_due 建议给宽限期并提示更新支付方式；paused、canceled 通常不允许访问。canceled 是终态；用户中途取消时状态仍为 active 且 scheduled_change 非空，到期后才翻转为 canceled。UI 可用 scheduled_change 是否非空显示“将于某日取消”。
回填与限制：已有数据需先回填再切换读取来源。Paddle MCP 每次 execute 上限 50 次 API 调用、30 秒超时、32KB 代码，per_page 200 时约 1 万客户；更大规模用一次性 SDK 脚本。常见坑包括用 anon key、结账前按 customer_id 映射、把 canceled 当作“刚点击取消”、只存 items 首项、忘记 customer.updated、依赖事件顺序等。验证可在沙箱创建订阅、取消并确认状态与 scheduled_change 变化。