ShipSaaS

💡 ShipSaaS：您的 AI 驱动 SaaS 启动平台

ShipSaaS.now 让您告别耗时数月的开发，轻松在几天内构建并上线真实可用的 SaaS 产品。我们精心打造了包含最新技术的生产级开发套件，助您事半功倍，快速实现商业价值。✨

---

🚀 核心亮点与优势

“不必重新发明轮子，将精力集中于您的核心业务逻辑。”

—— ShipSaaS，为开发者而生

• 🔥 最新技术栈：采用清爽的 Next.js 15 (App Router & Turbopack)、React 19 和 TypeScript，确保代码现代、高效且类型安全。
• 💰 完整支付系统：深度集成 Stripe 支付，支持多种订阅计划、结账方式、Webhook 处理及免费试用等功能。
• 🔒 强大权限控制：内置 RBAC（角色权限控制）与 CASL，提供 6 级权限管理和 API Key 管理，确保应用安全。
• 📊 高效数据管理：使用 Drizzle ORM 和 PostgreSQL，提供类型安全的数据库操作，结构清晰。
• 🧠 AI 智能代理：独特支持规则自动化 AI 代理，遵循严格架构指南，能生成、修改和增强代码，实现快速开发与质量一致。
• 🌐 多租户与团队协作：支持基于组织的多租户管理、团队邀请及成员角色分配，轻松构建协作型 SaaS。
• 🎨 精美 UI & DX：采用 Tailwind CSS v4 和 ShadCN UI 组件，提供优雅用户体验；严格分层架构，提升开发者体验。
• 🛡️ 生产级安全：内置 2FA、环境变量验证、SQL 注入保护等，保障SaaS应用安全稳定。

---

🎯 谁适合 ShipSaaS？

• SaaS 初创者：跳过繁琐的基础开发，专注于您的独特创意，快速验证市场。
• 开发团队：基于成熟的架构和编码标准，快速启动项目，保持团队协作高效。
• MVP 建造者：迅速构建功能完整的最小可行产品，支持真实用户和支付。
• 学习者：深入研究生产级代码库，掌握现代 React、Next.js 和 SaaS 开发模式。

---

🛠️ 详细技术栈概览

🏛️ 严格的分层架构

ShipSaaS 采用严谨的 5 层架构，分离关注点，确保代码可维护性和可扩展性：

1. 表现层 (Presentation Layer)：UI 组件和页面。
2. 数据访问层 (DAL)：使用 React 获取和缓存数据。
3. 门面层 (Facade Layer)：表现层与业务逻辑之间的接口。
4. 服务层 (Service Layer)：核心业务逻辑、验证和授权。
5. 持久层 (Persistence Layer)：数据库模型和操作。

📂 核心目录结构

• apps/*: 客户可见的 Next.js 应用。
• packages/*: 共享逻辑和公共工具库。

🤖 AI 驱动的开发哲学

ShipSaaS 的 AI 集成不仅是功能，更是一种开发哲学：

• 结构化指南：AI 代理遵循精确的架构规则生成代码。
• 智能代码生成：AI 生成与现有模式和约定一致的代码。
• 质量一致性：确保 AI 生成代码达到与人工编写代码相同的标准。
• 加速开发：快速实现复杂功能，同时维护架构完整性。

💡 AI 支持文件示例：

• CLAUDE.md：为 Claude Code (claude.ai/code) 提供全面的代码集成指南。
• AGENTS.md：为所有与代码库协作的 AI 代理提供通用指导。
• .cursor/rules/：约 21 个专业规则文件，为特定开发环节提供详细指令（如服务层、存储库、授权等）。

💾 持久层特性 (Drizzle ORM & PostgreSQL)

持久层负责所有数据库操作、模式定义和数据转换：

• Repository Pattern (DAO)：每个领域实体都有独立的 DAO，封装所有数据库操作。
• 类型转换：清晰地分离领域类型与 Drizzle 类型。
• 模式演进：基于迁移的数据库变更管理。
• 连接池：优化数据库连接，提高性能。

📂 持久层组织结构：

• src/db/models/：模式定义（Drizzle 实例、用户、订阅、组织模型）。
• src/db/repositories/：数据访问对象 (DAO)，如 user-repository.ts。
• src/db/migrations/：数据库迁移文件。
• src/db/helpers/：数据库工具函数。
• src/db/types/：数据库类型定义。

⚙️ 服务层特性

服务层包含所有业务逻辑、验证规则和授权检查，协调数据操作：

• 单一职责：每个服务专注于一个领域。
• 依赖注入：服务依赖抽象，而非具体实现。
• 分层验证：在业务逻辑之前进行输入验证。
• 授权优先：在执行操作之前进行权限检查。

📂 服务层组织结构：

• src/services/facades/：接口层，如 user-service-facade.ts。
• src/services/validation/：输入验证（Zod 模式）。
• src/services/authorization/：访问控制（RBAC 权限）。
• src/services/errors/：自定义错误类。
• src/services/interceptors/：横切关注点（日志、审计、性能）。
• src/services/helpers/：服务器端工具函数。
• src/services/types/：类型定义。

📁 文件管理系统

ShipSaaS 提供强大的文件管理功能：

• 存储架构：支持 Supabase Storage（默认）及 S3 等多提供商。
• React Dropzone：优雅的拖放上传界面。
• 文件组织：基于实体和时间戳的文件路径管理，如 users/{userId}/profile-1703123456789.webp。
• 文件分类：预定义文件类别（如 PROFILE, LOGO, IMAGE, DOCUMENT）。
• 环境隔离：开发/生产环境文件路径分离。
• 严格验证：使用 Zod 对文件类型、大小进行限制。

---

🚀 快速启动预览

只需几个命令，您就能在本地运行一个完整的 SaaS 应用：

# 克隆仓库并安装
git clone <repository-url>
cd next-saas-boilerplate
pnpm install

# 配置环境
cp .env.example .env.local
# 编辑 .env.local 填入您的密钥

# 设置数据库
pnpm db:push
pnpm db:seed

# 启动开发服务器
pnpm dev

您将拥有一个具备完整用户注册、认证、支付等功能的 SaaS 应用！