用途：这是 cmux 计费工作的运行手册，在改动或调试计费、定价、Stripe、Pro 权益、结账、Webhook、订阅相关代码前应先阅读。
主要能力与架构：/api/billing/checkout 在设置 STRIPE_SECRET_KEY 时为 Pro 创建 Stripe Checkout Session，将 client_reference_id 设为 Stack 用户 id，为未登录买家自动创建匿名 Stack 用户，未配置 Stripe 或 plan=team 时回退到旧 Stack 购买路径，并在此处短路“已激活”。/api/billing/portal 解析当前用户、查 stripe_customers 行并创建返回 /pricing 的客户门户会话。/api/billing/subscription 取消或恢复活跃 Stripe Pro 订阅；/dashboard/billing 渲染本地化的仪表盘套餐状态与自助操作。web/services/billing/purchase.ts 是 /api/billing/complete 与 /api/stripe/webhook 共用的幂等记录器，将邮箱附加到购买者，冲突时记录 billing_email_claims，绝不基于未验证邮箱跨账户授权。VM 代码从 Stack clientReadOnlyMetadata 读取套餐：非空 cmuxVmPlan（运营覆盖）优先，否则由 cmuxPlan（Stripe 镜像）提供权益。仅员工可用的 /api/admin/* 路由允许管理员搜索用户、团队和邮箱，授予或移除用户/团队覆盖、为尚无账户的邮箱授予 Pro、在周期末取消 Stripe 订阅以降级付费客户；services/admin/routeAuth.ts 的 requireAdmin 是入口，非管理员 API 返回 403，管理 UI 不在本仓库中。
使用方式：开发流程使用 web/scripts/stripe/dev-stack.sh；本地 bun dev 账户在 CMUX_LOCAL_DEV_PRO=1、NODE_ENV=development、VERCEL_ENV 未设置且 NEXT_PUBLIC_STACK_PROJECT_ID 为开发项目时自动获得非持久 Pro 权益。测试显式手动授权或非本地部署时用 dev-grant.sh。用 web/scripts/stripe/dev-reset.sh <email> 在重测结账前取消 Pro。测试模式结账输入促销码 CMUXDEV100 可走完整 $0 结账路径。生产运行手册：用运营密钥运行 web/scripts/stripe/provision-live.sh，添加两个 Vercel 环境变量，部署，用 100% 折扣促销码购买验证后取消。数据库迁移顺序为 bun run cloud-vm:preflight、bun run cloud-vm:migrate -- staging、staging 部署、bun run cloud-vm:migrate -- production，切勿在构建中运行迁移。
限制与注意：价格位于 web/services/billing/plans.ts，由 provision-catalog.sh 配置；Stripe 金额不可变，改价需生成新 lookup key 并把旧 key 加入 LEGACY_PRICE_LOOKUP_KEYS。付费 Cloud VM 配额在 machineSpec.ts 与 entitlements.ts 中，资源按池共享而非按 VM 计。测试不得依赖 DATABASE_URL 已设置；bun mock.module 是进程全局的，每个模块 mock 必须携带其他测试文件导入的全部真实导出。app/[locale] 之外的页面需要 proxy.ts 绕过，否则会被 next-intl 重写并 404。