技术栈
了解 MuseMVP 所选用的技术栈及其背后的设计考量。
本页面介绍 MuseMVP 所使用的核心技术，以及我们选择它们的原因。每个条目都附有官方文档链接，方便你在需要时快速深入了解。
Next.js & React
Next.js 16 是目前最成熟的 React 全栈框架之一，提供 App Router、Server Components、流式渲染等现代特性。我们使用 Next.js 同时承载前端页面渲染与后端 API 入口（通过路由桥接 Hono）。React 19 带来了更强大的 Server Actions 与并发特性，进一步减少客户端 JavaScript 体积。类型系统使用 TypeScript 7。package.json 的 engines.node 为 >=22。
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 社交登录
- TOTP 双重验证（2FA）
- 管理员权限插件（
admin） - Cloudflare Turnstile 验证码防护
Drizzle ORM 与 D1
Drizzle ORM 为通过 Worker DB 绑定访问的 D1 / SQLite提供类型化查询。应用包装层绑定 packages/db/src/schema-d1.ts 与对应迁移历史。
Tailwind CSS & UI 组件
Tailwind CSS v4 是一个实用优先的 CSS 框架，我们以其为设计系统基础，搭配 shadcn/ui（基于 Radix Primitives 的可访问性组件）以及 Motion（原 Framer Motion）动画库，构建出一套高度一致且可扩展的 UI 体系。
所有主题颜色通过 CSS 变量统一管理，切换主题或调整品牌色无需修改任何组件代码。
表单与数据校验
React Hook Form 提供性能优先的非受控表单管理，Zod 负责 Schema 声明与运行时数据校验，两者在 MuseMVP 中深度集成。所有用户输入在客户端与服务端均经过校验，确保类型安全贯穿全链路。
支付：Stripe、Creem、Dodo 与 Waffo
Stripe 是全球最主流的 SaaS 支付解决方案。Creem 则是一个对独立开发者更友好（无需美国实体）的支付平台替代方案。Dodo Payments 与 Waffo Pancake 是另外两套托管结账选项。MuseMVP 内置了四套支付网关的 Webhook 与回调处理逻辑，并通过统一的 Muse Billing 模块抽象定价策略，切换支付提供商时无需修改业务代码。
CMS：Fumadocs MDX
Fumadocs 与 Fumadocs MDX 编译每个应用的文档、博客、法律页和更新日志。内容 schema 在应用 source.config.ts；编辑源 MDX，不编辑 .source/。当前默认正文没有旧版 ProContent 付费遮罩。
国际化：next-intl
next-intl 为 Next.js App Router 提供完整的 i18n 解决方案，涵盖路由、消息翻译与本地化格式处理。MuseMVP 的所有页面——落地页、控制台、文档与博客——均支持多语言平滑切换。
邮件
Cloudflare Email Sending 负责生产投递。共享 React Email 模板位于 packages/mail/src/templates。
对象存储
原生 R2 使用 R2_BUCKET。头像与资产经同源 /files/avatars/* 访问，校验会话与所有权。
数据分析
MuseMVP 同时集成 Google Analytics (GA4) 与百度统计，并通过统一的 useAnalytics hook 向两个平台同步发送自定义埋点事件，适合同时面向国内外市场的产品。
路由分层
| 路径 | 职责 |
|---|---|
apps/web-cloudflare/src/app/(landing-page)/[locale] | 落地页在各路由文件中顺序拼装，以及博客、文档等营销与 CMS 页面 |
apps/web-cloudflare/src/app/(saas-page)/app | 登录后的应用控制台页面 |
apps/web-cloudflare/src/app/api/[[...rest]]/route.ts | Next.js → Hono 的 API 桥接入口 |
apps/web-cloudflare/src/backend/api/app.ts | Hono 路由注册与中间件组装入口 |
模块边界
| 目录 | 职责 |
|---|---|
apps/web-cloudflare/src/modules/* | 按功能划分的业务模块（UI + 逻辑） |
apps/web-cloudflare/src/backend/* | Hono 路由、API Client、应用数据库包装层 |
packages/config | 运行时配置：认证、账单、主题、联系表单投递 |
apps/web-cloudflare/content/docs / apps/web-cloudflare/content/posts | MDX 内容源（文档与博客） |
请求与数据流
apps/web-cloudflare/src/modules 中的 UI 组件触发用户动作
apps/web-cloudflare/src/backend/api-client 中的 React Query hook 发起 Hono RPC 调用
请求进入 apps/web-cloudflare/src/backend/api/routes 的对应 Hono 路由
服务层（如 muse-billing/lib/orchestrator.ts）或数据库查询层（packages/db/src/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 |
| 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 |
| Dodo Payments | docs.dodopayments.com |
| Waffo Pancake | docs.waffo.ai |
| Fumadocs | fumadocs.dev/docs |
| Fumadocs MDX | fumadocs.dev/docs |
| next-intl | next-intl.dev/docs |
| React Email | react.email/docs |
| Motion | framer.com/motion |
测试与 workspace
Node 22.x、pnpm 10.26.2、Biome、Vitest 和 Playwright。包逻辑放 packages/*，页面保留双副本；pnpm apps:parity 检查。分层测试与真实服务验收见 测试。当前没有启用 passkey/WebAuthn；Better Auth 的库能力不等于模板已接入。