架构 - Vibestrap

Vibestrap 是一个 Next.js 15 应用，TypeScript strict、Drizzle on Postgres、 Better Auth 管 session、next-intl 做 i18n、Tailwind v4 出样式。设计目标是「一个周末把付费 SaaS 上线」——每个架构决定都为这个目标服务，并且有一小撮关键决定撑住整体。本页就是那一小撮。

技术栈

层	技术	为什么
框架	Next.js 15（App Router、RSC、Turbopack）	server-first 渲染、生态成熟。
Runtime	React 19	async server components、`use()` hook。
语言	TypeScript 5（strict）	上线前抓住类型形状错误。
样式	Tailwind v4 + shadcn/ui	OKLCH 色彩、`globals.css` 里 CSS-first 配置。
ORM	Drizzle	类型化 schema、无 codegen、可写裸 SQL。
数据库	仅 Postgres	真相单一来源、事务、JSONB。
认证	Better Auth + Drizzle adapter	服务端 session、OAuth、邮件验证。
i18n	next-intl	EN/ZH 双语，URL 前缀 `as-needed`。
文档	Fumadocs MDX	双语 `*.zh.mdx`，按 locale 查找。
支付	Stripe / Creem / NOWPayments	同一个 facade 后面。
AI	Mock / OpenRouter / OpenAI / Anthropic / Replicate / fal	同样的 facade 模式；mock 离线可跑。
邮件	Resend + React Email	模板化、类型安全、dev 可预览。

目录结构

vibestrap/
├── content/                 # MDX 内容（双语）
│   ├── docs/                # *.mdx + *.zh.mdx 平行对
│   ├── blog/
│   └── changelog/
├── messages/                # next-intl 文案 bundle
│   ├── en.json
│   └── zh.json
├── public/                  # 静态资源、OG 图、logo
├── drizzle/                 # 生成的 SQL migration（已 commit）
├── src/
│   ├── app/                 # Next.js App Router
│   │   ├── [locale]/        # 带 locale 前缀的路由
│   │   │   ├── (marketing)/ # 公共页——home、pricing、blog、docs
│   │   │   ├── (auth)/      # login / register / forgot-password
│   │   │   └── (app)/       # 已登录——settings、admin、dashboard
│   │   ├── api/             # route handler（auth、webhooks、ping）
│   │   ├── layout.tsx       # 根 html、字体、主题
│   │   └── globals.css      # Tailwind v4 @theme + tokens
│   ├── components/          # blocks、layout、ui（shadcn）、features
│   ├── config/site.ts       # 中心配置，< 250 行
│   ├── db/                  # 拆分 schema：auth / app / affiliate / ai / license
│   ├── payment/             # facade + 4 个 provider + webhook handlers
│   ├── ai/                  # facade + 5 个 provider + cost / pricing
│   ├── credits/             # 4 类账目（仅服务端）
│   ├── mail/                # facade + Resend + React Email 模板
│   ├── newsletter/          # facade + Resend / Beehiiv
│   ├── customer-service/    # widget loader（Crisp / Tawk / Intercom / Chatwoot）
│   ├── affiliate/           # script loader + 内部追踪
│   ├── analytics/           # GA / PostHog / Plausible / Umami 扇出
│   ├── i18n/                # routing.ts + request.ts + 导航助手
│   ├── lib/                 # auth、safe-action、server、utils
│   ├── env.ts               # zod 校验过的 env 变量
│   └── middleware.ts        # i18n 路由 + 认证守卫
├── wrangler.toml.example    # Cloudflare Workers 配置模板
└── package.json

app/（在 src/ 里）是路由表面。src/ 里 app/ 之外的模块是页面和 route handler 调用的业务逻辑。 app/[locale]/ 段是 i18n 路由发生的地方；(marketing)、(auth)、(app) 这些 route group 是为了 layout 分组和认证守门，不影响 URL 形状。

关键决定

Provider facade 模式

每个对接外部服务的模块都导出一个对象（facade），背后是可互换的 provider。 facade 在启动时从 siteConfig.<module>.provider 选实现。消费者只见 facade。

// src/payment/index.ts
const providers: Record<PaymentProviderName, PaymentProvider> = {
  stripe: stripeProvider,
  creem: creemProvider,
  nowpayments: nowpaymentsProvider,
};

export function getPaymentManager(name?: PaymentProviderName): PaymentProvider {
  const requested = name ?? siteConfig.payment.defaultProvider;
  if (!siteConfig.payment.enabled.includes(requested)) {
    throw new Error(`Payment provider "${requested}" is not enabled.`);
  }
  return providers[requested];
}

src/ai/、src/mail/、src/newsletter/、src/customer-service/、src/affiliate/ 都是同一套。给 mail 加 Postmark 就是 src/mail/provider/postmark.ts 一个新文件加一条 switch 分支——消费者代码一行不改。

server-only 强制

碰 DB 或读 secret 的文件在顶部 import 'server-only'。这种模块要是被 client component 引用， Next.js build 会失败。已保护：src/db/index.ts、src/lib/auth.ts、src/lib/server.ts、 src/lib/safe-action.ts、所有 src/payment/provider/*、src/mail/index.ts、 src/credits/index.ts、src/credits/server.ts。新建仅服务端模块时记得加这一行—— 半秒钟敲完，省掉一次意外泄密。

三档 server actions

所有写操作走 next-safe-action，三种 client 在 src/lib/safe-action.ts：

actionClient —— 公共，不需要认证。
userActionClient —— 需要登录；提供 ctx.user。
adminActionClient —— 需要登录；要求 user.role === 'admin'。

每个 action 用 Zod 声明输入 schema。输出端到端类型化。守门集中——不必在每个 action 散落 if (!user) throw 样板。

幂等 webhook

支付 webhook 在任何非 2xx 响应时都会重试。如果你在重试时重复发积分，就等于一笔付款付了两次。脚手架在 src/payment/handlers/ 里靠两条保证解决：

payment.invoiceId 有 unique index——重复 insert 会让事务失败。
每个 handler 在 insert 前先做 payment.sessionId 查询，命中就早退。

发积分和 insert payment 行在同一个事务里——要么一起落，要么一起不落。加新事件类型（订阅续费、退款）时照这个形状写——绝不要把发积分单独再调一次。

拆分的 DB schema

src/db/ 按职责拆开：auth.schema.ts（Better Auth）、app.schema.ts（payment + credits + transactions）、affiliate.schema.ts、ai.schema.ts。schema.ts 统一 re-export 给 Drizzle Kit 和 Better Auth adapter。id 用 text（nanoid 前缀或 snowflake）—— 不用 serial，因为 text id 让你换 provider 时不破坏外键，也不会通过枚举泄露用户数。所有外键在用户删除时级联（开箱即合 GDPR）。

双语 MDX

每篇文档两个平行文件：path/to/doc.mdx 和 path/to/doc.zh.mdx。Fumadocs 配置成先找带 locale 后缀的文件，找不到回落默认。同一套机制用于 blog 文章和 changelog。两种 locale 都存在才算上线。

Locale 路由——`as-needed` 前缀

src/i18n/routing.ts 把 next-intl 配成英文留在根（/about）、中文加前缀（/zh/about）。全程用 @/i18n/navigation 里的 Link / useRouter——它们自动保留 locale 前缀。直接 import next/link 或 next/navigation 会在客户端导航时悄悄丢掉 locale。

钱用 micro-cent

AI 推理和积分账务都涉及小于一分钱的数。用 float 存钱招舍入 bug；用整数 cent 存又丢亚分精度（百万 token 的 Claude 调用每 token 价 $0.000003）。脚手架统一存整数 micro-cent（百万分之一 USD），到边缘再换显示单位。算法见 src/ai/pricing.ts。

Edge runtime —— 只给 OG 图

src/app/opengraph-image.tsx 跑在 Edge runtime，因为这是唯一一处 cold start 直接影响用户可见性能的路径（社交平台抓图器超时很快）。其他全部——包括所有访问 Postgres 的 API 路由——用 Node runtime，因为 pg 驱动和不少 auth 依赖需要完整 Node API。除非你清楚在让出什么，否则别把路由搬到 Edge。

数据流——结账

一个穿透大半个架构的典型流程：

用户点击「$49 立即获取 Vibestrap」
  → /register?plan=vibestrap-promo
  → 注册后 → /settings/billing
  → createCheckoutAction({plan})    [userActionClient]
    → paymentManager.createCheckout()   [facade → 当前 provider]
    → 返回 session.url
  → window.location = session.url
  → 用户在 provider 托管页支付
  → POST /api/webhooks/<provider>   [Node runtime]
    → verifyWebhook() —— 用 node:crypto 校签名
    → handler → 用 payment.sessionId 做幂等检查
    → DB 事务：
        INSERT payment 行
        addCredits()  // 同事务里发对应数量
  → 用户跳回 /settings/billing?status=success

另见

配置 —— siteConfig 旋钮。
自定义 —— 常见 recipes。
Vercel 部署 —— 把架构上线。
Env 参考 —— 选 provider 用的每个 key。

入门

认证

支付

AI 原语

增长

内容与国际化

运维

部署

参考

架构

技术栈

目录结构

关键决定

Provider facade 模式

server-only 强制

三档 server actions

幂等 webhook

拆分的 DB schema

双语 MDX

Locale 路由——`as-needed` 前缀

钱用 micro-cent

Edge runtime —— 只给 OG 图

数据流——结账

另见

​技术栈

​目录结构

​关键决定

​Provider facade 模式

​server-only 强制

​三档 server actions

​幂等 webhook

​拆分的 DB schema

​双语 MDX

​Locale 路由——as-needed 前缀

​钱用 micro-cent

​Edge runtime —— 只给 OG 图

​数据流——结账

​另见

技术栈

目录结构

关键决定

Provider facade 模式

server-only 强制

三档 server actions

幂等 webhook

拆分的 DB schema

双语 MDX

Locale 路由——`as-needed` 前缀

钱用 micro-cent

Edge runtime —— 只给 OG 图

数据流——结账

另见