SaaS 全栈脚手架

为什么需要它

手动从零搭建 SaaS 应用时，开发者常在基础工程配置（如 tsconfig.json 路径别名、shadcn/ui 依赖安装）和业务模块整合（如 NextAuth 会话类型扩展、Stripe Webhook 幂等性处理）之间反复调试。不同技术栈的版本差异和文档分散，容易导致早期阶段的小错误阻塞后续开发。

它的工作方式

该技能以分阶段清单驱动脚手架生成，每个阶段结束时强制验证，确保错误不向下传播：

1. 基础工程（Phase 1 — Foundation）

• 初始化 Next.js + TypeScript + App Router
• 配置 tailwind.config.ts 主题令牌和 components.json
• 验证：npm run build 无 TypeScript 或 lint 错误

2. 数据库层（Phase 2 — Database）

• 定义 Drizzle ORM 模式（users, accounts 等表）
• 生成并应用迁移文件（drizzle-kit push / migrate）
• 验证：测试脚本执行 db.select().from(users) 无异常

3. 认证集成（Phase 3 — Authentication）

• 配置 NextAuth OAuth 提供商（Google/GitHub）
• 扩展 next-auth 模块声明以注入 subscriptionStatus
• 验证：无会话访问 /dashboard 自动重定向至 /login

4. 支付闭环（Phase 4 — Payments）

• 创建 Stripe Checkout Session 路由
• 实现幂等的 Webhook 处理器（基于事件 ID 去重）
• 验证：测试卡完成支付后，数据库正确记录 stripeSubscriptionId

5. 界面骨架（Phase 5 — UI）

• 生成响应式 Dashboard 布局（侧边栏 + 移动端头部）
• 构建计费页面展示当前订阅计划与升级入口
• 验证：npm run build 生产构建无错误

配套参考文件

• CUSTOMIZATION.md — 技术栈替换指南（如 Clerk 替代 NextAuth）
• PITFALLS.md — 常见陷阱（如 Edge Runtime 与 Drizzle 冲突）
• BEST_PRACTICES.md — Stripe 单例模式、Server Actions 等

适用边界与注意点

• 不自动安装依赖或执行部署命令，所有代码需手动确认后应用
• 涉及外部写入（如数据库迁移、Webhook 触发）需用户明确授权
• 凭据仅用于指定官方服务，不记录或转发
• 生产环境需额外处理（如 NEXTAUTH_SECRET 一致性、Webhook 签名验证）