技术栈
了解 MuseMVP 所选用的技术栈及其背后的设计考量。
本页面介绍 MuseMVP 所使用的核心技术，以及我们选择它们的原因。每个条目都附有官方文档链接，方便你在需要时快速深入了解。
Next.js & React
Next.js 16 是目前最成熟的 React 全栈框架之一，提供 App Router、Server Components、流式渲染等现代特性。我们使用 Next.js 同时承载前端页面渲染与后端 API 入口（通过路由桥接 Hono）。React 19 带来了更强大的 Server Actions 与并发特性，进一步减少客户端 JavaScript 体积。
Hono & TanStack Query
Hono 是一个轻量、极速的边缘友好 Web 框架，提供 RPC 客户端以实现从前端到后端的端到端类型安全调用。我们将 Hono 应用挂载在 Next.js 的 app/api/[[...rest]] 路由上，实现 Monorepo 内前后端共存。
TanStack Query 负责客户端的数据获取、缓存与状态同步，与 Hono RPC 配合极大简化了异步数据管理逻辑。
Better Auth
Better Auth 是一套为全栈应用设计的现代认证库，提供即用型的认证流程与插件化扩展机制。MuseMVP 在 Better Auth 的基础上启用了多个插件，覆盖从基础登录到高级安全的全套认证能力：
- 邮箱 + 密码登录 / 邮箱 OTP 验证码登录
- Google & GitHub OAuth 社交登录
- WebAuthn 无密码登录
- TOTP 双重验证（2FA）
- 管理员权限插件（
admin） - Cloudflare Turnstile 验证码防护
Drizzle ORM & PostgreSQL
Drizzle ORM 是一个类型安全的 TypeScript ORM，Schema 定义、查询构建与数据库迁移均具备完整的类型推导，无需额外的代码生成步骤。我们默认搭配 PostgreSQL，但 Drizzle 的灵活适配层使其可以轻松切换至 MySQL 或 SQLite。
Tailwind CSS & UI 组件
Tailwind CSS v4 是一个实用优先的 CSS 框架，我们以其为设计系统基础，搭配 shadcn/ui（基于 Radix Primitives 的可访问性组件）以及 Framer Motion 动画库，构建出一套高度一致且可扩展的 UI 体系。
所有主题颜色通过 CSS 变量统一管理，切换主题或调整品牌色无需修改任何组件代码。
Tailwind CSS v4
tailwindcss.com
shadcn/ui
ui.shadcn.com
Radix Primitives
radix-ui.com
Framer Motion
framer.com
表单与数据校验
React Hook Form 提供性能优先的非受控表单管理，Zod 负责 Schema 声明与运行时数据校验，两者在 MuseMVP 中深度集成。所有用户输入在客户端与服务端均经过校验，确保类型安全贯穿全链路。
支付：Stripe & Creem
Stripe 是全球最主流的 SaaS 支付解决方案。Creem 则是一个对独立开发者更友好（无需美国实体）的支付平台替代方案。MuseMVP 内置了两套支付网关的 Webhook 与回调处理逻辑，并通过统一的 Muse Billing 模块抽象定价策略，切换支付提供商时无需修改业务代码。
AI：Vercel AI SDK
Vercel AI SDK 是构建 AI 功能的首选工具集，原生支持流式文本、工具调用与 React 组件流式渲染（Generative UI）。MuseMVP 基于它实现了开箱即用的 AI 对话界面，并将会话记录持久化至数据库。
CMS：Fumadocs & Content Collections
Fumadocs 是本项目文档系统的核心（即你正在阅读的这套文档），提供专业级的内容组织、搜索与 MDX 渲染能力，并由 MuseMVP 扩展了付费内容管控（Pro Content）机制。Content Collections 负责博客、Changelog 等内容类型的类型安全数据源管理。
国际化：next-intl
next-intl 为 Next.js App Router 提供完整的 i18n 解决方案，涵盖路由、消息翻译与本地化格式处理。MuseMVP 的所有页面——落地页、控制台、文档与博客——均支持多语言平滑切换。
邮件：Resend & React Email
Resend 是专为开发者设计的现代邮件发送服务，React Email 则让你可以用 React 组件编写美观的 HTML 邮件模板。MuseMVP 提供多套预置模板，覆盖 OTP 验证码、密码重置、欢迎邮件等场景。
对象存储（S3 兼容）
MuseMVP 封装了标准 S3 协议的文件上传接口，无缝兼容 AWS S3、Cloudflare R2 或自建 MinIO，切换存储提供商只需修改环境变量。
数据分析
MuseMVP 同时集成 Google Analytics (GA4) 与百度统计，并通过统一的 useAnalytics hook 向两个平台同步发送自定义埋点事件，适合同时面向国内外市场的产品。
路由分层
| 路径 | 职责 |
|---|---|
src/app/(landing-page)/[locale] | 落地页、博客、文档等营销与 CMS 页面 |
src/app/(saas-page)/app | 登录后的应用控制台页面 |
src/app/api/[[...rest]]/route.ts | Next.js → Hono 的 API 桥接入口 |
src/backend/api/app.ts | Hono 路由注册与中间件组装入口 |
模块边界
| 目录 | 职责 |
|---|---|
src/modules/* | 按功能划分的业务模块（UI + 逻辑） |
src/backend/* | Hono 路由、API Client、数据库查询层 |
src/config/index.ts | 全局配置与功能开关 |
content/docs / content/posts | MDX 内容源（文档与博客） |
请求与数据流
src/modules 中的 UI 组件触发用户动作
src/backend/api-client 中的 React Query hook 发起 Hono RPC 调用
请求进入 src/backend/api/routes 的对应 Hono 路由
服务层（如 muse-billing/lib/orchestrator.ts）或数据库查询层（src/backend/database/queries）处理业务逻辑
响应返回后，React Query 更新缓存，UI 自动重渲染
官方文档速查
| 技术 | 官方文档 |
|---|---|
| Next.js | nextjs.org/docs |
| React | react.dev |
| Hono | hono.dev/docs |
| TanStack Query | tanstack.com/query/latest/docs |
| Better Auth | better-auth.com/docs |
| Drizzle ORM | orm.drizzle.team/docs |
| PostgreSQL | postgresql.org/docs |
| Tailwind CSS | tailwindcss.com/docs |
| shadcn/ui | ui.shadcn.com/docs |
| Radix UI | radix-ui.com/primitives/docs |
| Zod | zod.dev |
| React Hook Form | react-hook-form.com/docs |
| Stripe | stripe.com/docs |
| Creem | creem.io/docs |
| Vercel AI SDK | ai-sdk.dev/docs |
| Fumadocs | fumadocs.dev/docs |
| Content Collections | content-collections.dev/docs |
| next-intl | next-intl.dev/docs |
| Resend | resend.com/docs |
| React Email | react.email/docs |
| Framer Motion | framer.com/motion |