create-nextdevtpl 2.6.0

package/template/src/content/docs/zh/deployment.mdx

@@ -0,0 +1,61 @@
+---
+title: 部署
+description: 使用现有脚本或托管 Next.js 平台部署 NextDevTpl。
+---
+
+# 部署
+
+仓库内置了自托管部署流程，也可以部署到托管 Next.js 平台。
+
+## 自托管流程
+
+现有脚本：
+
+| 文件 | 运行位置 | 作用 |
+| --- | --- | --- |
+| `deploy-build.bat` | Windows 本地机器 | 构建、打包、上传产物 |
+| `start-prod.sh` | Linux 服务器 | 安装生产依赖并启动/重启应用 |
+
+典型流程：
+
+1. 在 `deploy-build.bat` 顶部配置 SSH host、部署目录和 key path。
+2. 确认服务器上已经有生产 `.env`。
+3. 本地运行：
+
+```bat
+deploy-build.bat
+```
+
+4. 脚本会本地构建、打包、上传，然后在服务器启动应用。
+
+## 生产环境变量
+
+最少需要：
+
+```bash
+DATABASE_URL="postgresql://..."
+BETTER_AUTH_SECRET="strong-production-secret"
+BETTER_AUTH_URL="https://your-domain.com"
+```
+
+再按实际启用的功能补 Creem、Resend、Storage、Redis、Sentry、Axiom、Inngest 和 AI provider 凭证。
+
+## Vercel
+
+部署到 Vercel：
+
+1. 导入 GitHub 仓库。
+2. 设置生产环境变量。
+3. 确认数据库能从 Vercel 访问。
+4. 使用 Vercel 生产域名配置 webhook URL。
+5. 发布前或发布时执行数据库迁移。
+
+## 发布 checklist
+
+- `pnpm typecheck` 通过。
+- `pnpm build` 通过。
+- 数据库迁移已准备。
+- `BETTER_AUTH_URL` 使用生产域名。
+- OAuth callback URL 使用生产域名。
+- Creem webhook 指向 `/api/webhooks/creem`。
+- Sentry/Axiom 不接收原始密钥。

package/template/src/content/docs/zh/email.mdx

@@ -0,0 +1,47 @@
+---
+title: 邮件
+description: 使用 Resend 和 React Email 模板发送产品邮件。
+---
+
+# 邮件
+
+邮件发送使用 Resend，模板使用 React Email 组件。
+
+## 主要文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/features/mail/client.ts` | Resend client 配置 |
+| `src/features/mail/actions.ts` | 发信 actions |
+| `src/features/mail/utils.ts` | 邮件工具函数 |
+| `src/features/mail/templates` | React Email 模板 |
+| `src/test/mail/newsletter.test.ts` | 邮件相关测试 |
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `RESEND_API_KEY` | Resend API 凭证 |
+| `EMAIL_FROM` | 用户看到的发件人 |
+
+示例：
+
+```bash
+RESEND_API_KEY="re_xxxxxxxxx"
+EMAIL_FROM="NextDevTpl <noreply@example.com>"
+```
+
+## 模板
+
+邮件模板是 React 组件：
+
+| 模板 | 作用 |
+| --- | --- |
+| `welcome-email.tsx` | 欢迎/引导邮件 |
+| `primary-action-email.tsx` | 带按钮的通用操作邮件 |
+
+改邮件模板时，文案尽量短，不要依赖复杂 CSS。邮件客户端的 CSS 支持很有限。
+
+## 本地行为
+
+没有配置 Resend 时，依赖邮件投递的功能应该视为不可用。先测试基础邮箱密码流程，再启用 Resend 测试验证邮件和重置密码。

package/template/src/content/docs/zh/index.mdx

@@ -0,0 +1,48 @@
+---
+title: 介绍
+description: 了解 NextDevTpl 内置能力，以及如何把它作为生产级 SaaS 起点。
+---
+
+# NextDevTpl 文档
+
+NextDevTpl 是一个偏生产落地的 SaaS 启动模板，基于 Next.js、React、TypeScript、PostgreSQL、Drizzle ORM、Better Auth、next-intl、Creem 支付、积分系统、管理后台、工单、邮件、对象存储、可观测性和后台任务构建。
+
+它不是只展示一个首页的 UI 模板，而是提供一套可以继续二开的产品骨架。
+
+## 内置能力
+
+| 模块 | 说明 |
+| --- | --- |
+| 应用骨架 | 多语言营销页、博客、文档、Dashboard、Admin、法律页面 |
+| 认证 | Better Auth 邮箱密码、OAuth、session、角色权限 |
+| 数据库 | PostgreSQL schema、Drizzle ORM、迁移和集成测试 |
+| 支付 | Creem checkout、订阅、webhook、一次性积分购买 |
+| 积分 | 账本式积分记录、FIFO 批次过期、余额读取 |
+| 运营 | 用户管理、工单、日志、监控、限流、后台任务 |
+| 内容 | Fumadocs 文档、MDX 博客、next-intl UI 翻译 |
+
+## 推荐阅读顺序
+
+如果你想先跑起来，建议看：
+
+- [快速开始](/zh/docs/quick-start)
+- [项目结构](/zh/docs/project-structure)
+- [配置说明](/zh/docs/configuration)
+
+如果你要接入业务功能，建议看：
+
+- [认证](/zh/docs/authentication)
+- [支付](/zh/docs/payments)
+- [积分系统](/zh/docs/credits)
+- [国际化](/zh/docs/internationalization)
+
+如果你准备上线，建议看：
+
+- [部署](/zh/docs/deployment)
+- [可观测性](/zh/docs/observability)
+- [后台任务](/zh/docs/background-jobs)
+
+## 核心原则
+
+本地开发时，大多数外部服务都应该是可选的。项目先用数据库和基础认证跑起来，再按产品需要逐步启用 OAuth、邮件、支付、对象存储、Redis、Sentry、Axiom 和 Inngest。
+

package/template/src/content/docs/zh/internationalization.mdx

@@ -0,0 +1,78 @@
+---
+title: 国际化
+description: 使用 next-intl 路由、UI 文案和多语言文档。
+---
+
+# 国际化
+
+NextDevTpl 使用 `next-intl` 处理 UI 翻译和带语言前缀的路由。文档内容通过 Fumadocs 的语言目录管理。
+
+## 当前语言
+
+语言配置在：
+
+```txt
+src/i18n/routing.ts
+```
+
+当前值：
+
+```ts
+locales: ["en", "zh"]
+defaultLocale: "en"
+```
+
+## UI 文案
+
+| 文件 | 作用 |
+| --- | --- |
+| `messages/en.json` | 英文 UI 文案 |
+| `messages/zh.json` | 中文 UI 文案 |
+| `src/i18n/request.ts` | 加载当前语言 messages |
+| `src/features/shared/components/language-switcher.tsx` | Header 语言切换器 |
+
+Client Component 使用 `useTranslations()`。Server Component 使用 next-intl 的服务端 helpers。
+
+## 路由结构
+
+大多数页面都在：
+
+```txt
+src/app/[locale]
+```
+
+示例：
+
+```txt
+/en
+/zh
+/en/dashboard
+/zh/dashboard
+/en/docs
+/zh/docs
+```
+
+## 文档国际化
+
+文档按语言存放：
+
+```txt
+src/content/docs/en
+src/content/docs/zh
+```
+
+`src/lib/source.ts` 中的 loader 使用 Fumadocs i18n，并采用 `dir` parser。docs route 会根据 `params.locale` 取页面，所以 `/en/docs` 和 `/zh/docs` 是两棵独立文档树。
+
+## 新增语言
+
+1. 在 `src/i18n/routing.ts` 添加 locale。
+2. 新增 `messages/<locale>.json`。
+3. 新增 `src/content/docs/<locale>`。
+4. 如果博客和法律页面也支持该语言，也要补对应内容。
+5. 必要时更新 sitemap metadata。
+6. 测试导航和语言切换。
+
+## 翻译原则
+
+不要机械翻译技术名词。Next.js、Drizzle、Better Auth、Creem、Inngest、Sentry、Axiom、Fumadocs、next-intl 这些框架或服务名保持英文。
+

package/template/src/content/docs/zh/meta.json

@@ -0,0 +1,22 @@
+{
+  "title": "NextDevTpl",
+  "root": true,
+  "pages": [
+    "index",
+    "quick-start",
+    "project-structure",
+    "configuration",
+    "authentication",
+    "database",
+    "credits",
+    "payments",
+    "email",
+    "storage",
+    "internationalization",
+    "background-jobs",
+    "admin-and-support",
+    "observability",
+    "deployment",
+    "customization"
+  ]
+}

package/template/src/content/docs/zh/observability.mdx

@@ -0,0 +1,68 @@
+---
+title: 可观测性
+description: 配置日志、监控、限流和请求诊断。
+---
+
+# 可观测性
+
+NextDevTpl 包含结构化日志、可选云端日志、Sentry 监控、限流和 API 请求日志工具。
+
+## 日志
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/lib/logger/index.ts` | Pino logger wrapper |
+| `src/lib/api-logger.ts` | API logging helpers |
+
+配置 Axiom 后，日志可以发送到 Axiom。未配置时，日志应仍然能在本地看到。
+
+常见变量：
+
+```bash
+AXIOM_TOKEN="xaat-..."
+AXIOM_DATASET="nextdevtpl"
+```
+
+## 错误监控
+
+Sentry 配置文件：
+
+| 路径 | 作用 |
+| --- | --- |
+| `sentry.client.config.ts` | 浏览器 Sentry 配置 |
+| `sentry.server.config.ts` | 服务端 Sentry 配置 |
+| `sentry.edge.config.ts` | Edge Sentry 配置 |
+| `src/instrumentation.ts` | Next.js instrumentation hook |
+| `src/lib/monitoring/index.ts` | Monitoring helpers |
+
+常见变量：
+
+```bash
+NEXT_PUBLIC_SENTRY_DSN="https://..."
+SENTRY_AUTH_TOKEN="sntrys_..."
+```
+
+## 限流
+
+限流代码在：
+
+```txt
+src/lib/rate-limit
+```
+
+Upstash 变量：
+
+```bash
+UPSTASH_REDIS_REST_URL="https://..."
+UPSTASH_REDIS_REST_TOKEN="..."
+```
+
+没有 Redis 时，开发环境不应该因为限流配置缺失而启动失败。
+
+## 生产 checklist
+
+- 用户可见错误接入 Sentry。
+- webhook 和支付流程开启结构化日志。
+- 支付和 job retry 日志记录外部事件 id。
+- 不记录原始密钥、token、authorization headers。
+- 检查公开 mutation endpoint 的限流。

package/template/src/content/docs/zh/payments.mdx

@@ -0,0 +1,64 @@
+---
+title: 支付
+description: 配置 Creem 支付、订阅、一次性购买和 webhooks。
+---
+
+# 支付
+
+支付层基于 Creem。模板包含订阅、一次性积分购买、webhook 处理和用户套餐查询。
+
+## 主要文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/features/payment/creem.ts` | Creem client 和 API 集成 |
+| `src/features/payment/actions.ts` | Checkout 和支付 Server Actions |
+| `src/features/payment/types.ts` | 支付相关类型 |
+| `src/config/payment.ts` | 产品和支付配置 |
+| `src/config/subscription-plan.ts` | 套餐定义 |
+| `src/app/api/webhooks/creem/route.ts` | Creem webhook endpoint |
+| `src/features/subscription` | 用户套餐查询和订阅 UI |
+| `src/test/payment` | 支付和订阅测试 |
+
+## 必要环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `CREEM_API_KEY` | 调用 Creem API |
+| `CREEM_WEBHOOK_SECRET` | 校验 webhook 签名 |
+
+生产环境的 callback 和 webhook URL 应该使用正式域名。
+
+## 订阅流程
+
+1. 套餐定义在 `src/config/subscription-plan.ts`。
+2. 定价 UI 展示套餐。
+3. checkout action 创建 Creem checkout session。
+4. Creem 发送 webhook 事件。
+5. webhook 更新订阅状态。
+6. Dashboard 读取当前用户套餐。
+
+## 积分购买流程
+
+一次性积分购买复用支付层，在付款成功后发放积分套餐。账本行为见 [积分系统](/zh/docs/credits)。
+
+## Webhook 上线 checklist
+
+上线前确认：
+
+1. 配置 Creem webhook URL：
+
+```txt
+https://your-domain.com/api/webhooks/creem
+```
+
+2. 设置 `CREEM_WEBHOOK_SECRET`。
+3. 如果 Creem 支持 sandbox，先跑 sandbox checkout。
+4. 确认订阅状态会更新。
+5. 确认重复 webhook 不会重复发积分。
+6. 跑支付测试。
+
+```bash
+pnpm test:run src/test/payment
+```
+

package/template/src/content/docs/zh/project-structure.mdx

@@ -0,0 +1,82 @@
+---
+title: 项目结构
+description: 了解应用目录、功能模块和基础设施代码如何组织。
+---
+
+# 项目结构
+
+NextDevTpl 使用按功能组织的结构。路由放在 `src/app`，可复用产品模块放在 `src/features`，底层工具和基础设施放在 `src/lib`。
+
+## 顶层文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `package.json` | 脚本和依赖版本 |
+| `next.config.mjs` | Next.js、MDX、构建配置 |
+| `source.config.ts` | Fumadocs 内容集合配置 |
+| `drizzle.config.ts` | Drizzle 迁移配置 |
+| `.env.example` | 环境变量参考 |
+| `deploy-build.bat` | Windows 本地构建和上传脚本 |
+| `start-prod.sh` | Linux 服务器生产启动脚本 |
+
+## 应用路由
+
+```txt
+src/app/
+├── [locale]/
+│   ├── (marketing)/     # 首页、博客、法律页面、PSEO 等公开页面
+│   ├── (auth)/          # 登录、注册、找回密码
+│   ├── (dashboard)/     # 登录后的用户工作台
+│   ├── (admin)/         # 管理员后台
+│   └── docs/            # Fumadocs 文档
+└── api/                 # Route handlers 和 webhooks
+```
+
+`[locale]` 由 `next-intl` 处理。当前语言配置在 `src/i18n/routing.ts`。
+
+## 功能模块
+
+| 模块 | 作用 |
+| --- | --- |
+| `src/features/auth` | 登录、注册等认证 UI 和 hooks |
+| `src/features/credits` | 积分账本、购买、余额工具 |
+| `src/features/payment` | Creem checkout 和支付 actions |
+| `src/features/subscription` | 用户套餐查询和订阅 UI |
+| `src/features/settings` | 资料、安全、账单、账户设置 |
+| `src/features/support` | 用户工单和管理员回复 |
+| `src/features/admin` | 管理后台 UI 组件 |
+| `src/features/marketing` | Header、Footer、Hero、Pricing、FAQ 等首页模块 |
+| `src/features/storage` | S3/R2 上传和存储 provider |
+| `src/features/mail` | React Email 模板和发信逻辑 |
+| `src/features/shared` | Providers、主题切换、语言切换、共享图标 |
+
+## 基础设施模块
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/db/schema.ts` | 数据库表定义 |
+| `src/lib/auth` | Better Auth server/client/edge/admin helpers |
+| `src/lib/rate-limit` | 基于 Upstash 的限流和降级逻辑 |
+| `src/lib/logger` | Pino logger 和 Axiom 集成 |
+| `src/lib/monitoring` | Sentry 监控 helpers |
+| `src/lib/source.ts` | Docs、Blog、Legal 内容加载器 |
+| `src/lib/safe-action.ts` | Server Action client 配置 |
+| `src/inngest` | Inngest client 和后台函数 |
+
+## 内容目录
+
+| 路径 | 内容 |
+| --- | --- |
+| `src/content/docs/en` | 英文文档 |
+| `src/content/docs/zh` | 中文文档 |
+| `src/content/blog/en` | 英文博客 |
+| `src/content/blog/zh` | 中文博客 |
+| `src/content/legal/en` | 英文法律页面 |
+| `src/content/legal/zh` | 中文法律页面 |
+| `messages/en.json` | 英文 UI 文案 |
+| `messages/zh.json` | 中文 UI 文案 |
+
+## 测试
+
+集成测试在 `src/test`。目前覆盖支付、积分、工单、存储安全、设置、后台任务和邮件等流程。
+

package/template/src/content/docs/zh/quick-start.mdx

@@ -0,0 +1,110 @@
+---
+title: 快速开始
+description: 使用最小配置在本地启动 NextDevTpl。
+---
+
+# 快速开始
+
+这篇文档用于用最小配置启动本地开发环境。
+
+## 前置要求
+
+| 工具 | 版本 | 说明 |
+| --- | --- | --- |
+| Node.js | 20+ | 当前依赖要求 Node 20 以上 |
+| pnpm | 推荐 10+ | lockfile 使用 pnpm 维护 |
+| PostgreSQL | 推荐 14+ | 可以用本地 PostgreSQL、Neon、Supabase 等兼容服务 |
+
+## 安装依赖
+
+```bash
+git clone git@github.com:evepupil/NextDevTpl.git
+cd NextDevTpl
+pnpm install
+```
+
+## 创建环境变量文件
+
+```bash
+cp .env.example .env.local
+```
+
+Windows PowerShell：
+
+```powershell
+Copy-Item .env.example .env.local
+```
+
+## 最小启动配置
+
+只要下面 3 个变量存在，项目就应该能完成基础启动：
+
+```bash
+DATABASE_URL="postgresql://postgres:password@localhost:5432/nextdevtpl"
+BETTER_AUTH_SECRET="replace-with-a-random-secret"
+BETTER_AUTH_URL="http://localhost:3000"
+```
+
+可以用下面命令生成随机密钥：
+
+```bash
+openssl rand -base64 32
+```
+
+OAuth、邮件、支付、对象存储、Redis、日志、监控、AI、后台任务都可以后续再接。
+
+## 初始化数据库
+
+新本地库建议直接推送当前 Drizzle schema：
+
+```bash
+pnpm db:push
+```
+
+共享环境或生产环境建议走迁移：
+
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
+
+## 启动开发服务
+
+```bash
+pnpm dev
+```
+
+打开：
+
+```txt
+http://localhost:3000
+```
+
+中间件会根据语言配置进入对应路径，例如 `/en` 或 `/zh`。
+
+## 启动后检查
+
+| 检查项 | 预期结果 |
+| --- | --- |
+| 首页 | 营销页正常渲染，没有缺失翻译报错 |
+| 注册 | 可以创建邮箱密码账号 |
+| 登录 | 登录后进入 `/dashboard` |
+| Dashboard | 侧边栏、设置、积分、工单入口正常 |
+| Admin | `role = "admin"` 的用户可以访问 `/admin` |
+| Docs | `/en/docs` 和 `/zh/docs` 显示各自语言的内容 |
+
+## 常用命令
+
+```bash
+pnpm dev            # 启动 Next.js 开发服务
+pnpm build          # 生产构建
+pnpm start          # 启动生产服务
+pnpm typecheck      # TypeScript 类型检查
+pnpm lint           # Biome lint
+pnpm check          # Biome check 并自动修复
+pnpm db:push        # 开发环境推送 Drizzle schema
+pnpm db:generate    # 生成迁移文件
+pnpm db:migrate     # 执行迁移
+pnpm db:studio      # 打开 Drizzle Studio
+pnpm test:run       # 单次运行测试
+```

package/template/src/content/docs/zh/storage.mdx

@@ -0,0 +1,51 @@
+---
+title: 对象存储
+description: 配置 S3 或 Cloudflare R2 兼容存储和 presigned upload。
+---
+
+# 对象存储
+
+存储层兼容 S3 风格服务，例如 AWS S3、Cloudflare R2 和 MinIO。
+
+## 主要文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/features/storage/providers/s3.ts` | S3-compatible provider |
+| `src/features/storage/actions.ts` | 存储 Server Actions |
+| `src/features/storage/utils.ts` | 工具函数 |
+| `src/features/storage/types.ts` | 存储类型 |
+| `src/app/api/upload/presigned/route.ts` | Presigned upload endpoint |
+| `src/app/image-proxy/[...path]/route.ts` | 图片代理路由 |
+| `src/test/storage/security.test.ts` | 存储安全测试 |
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `STORAGE_ENDPOINT` | Provider endpoint，例如 R2 endpoint |
+| `STORAGE_REGION` | S3 region 或兼容值 |
+| `STORAGE_BUCKET` | Bucket 名称 |
+| `STORAGE_ACCESS_KEY_ID` | Access key |
+| `STORAGE_SECRET_ACCESS_KEY` | Secret key |
+
+## 上传模型
+
+1. 客户端请求 presigned upload URL。
+2. 服务端校验请求并返回上传 metadata。
+3. 客户端直传到对象存储。
+4. 应用保存或使用 object key。
+5. 公开展示时可以走 image proxy。
+
+## 安全 checklist
+
+- 创建 presigned URL 前校验文件类型和大小。
+- object key 要有作用域，不要可预测。
+- 不要把 secret key 暴露给浏览器。
+- 优先使用私有 bucket，配合 signed read 或 proxy route。
+- 修改上传规则后运行存储安全测试。
+
+```bash
+pnpm test:run src/test/storage
+```
+