create-nextdevtpl 2.6.0

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

@@ -0,0 +1,113 @@
+---
+title: Quick Start
+description: Run NextDevTpl locally with the minimum required services.
+---
+
+# Quick Start
+
+This guide starts the app locally with the smallest useful configuration.
+
+## Requirements
+
+| Tool | Version | Notes |
+| --- | --- | --- |
+| Node.js | 20+ | Required by Next.js and Inngest dependencies in this project |
+| pnpm | 10+ recommended | The lockfile is maintained with pnpm |
+| PostgreSQL | 14+ recommended | Local PostgreSQL, Neon, Supabase, or another compatible host |
+
+## Install dependencies
+
+```bash
+git clone git@github.com:evepupil/NextDevTpl.git
+cd NextDevTpl
+pnpm install
+```
+
+## Create environment file
+
+```bash
+cp .env.example .env.local
+```
+
+On Windows PowerShell:
+
+```powershell
+Copy-Item .env.example .env.local
+```
+
+## Minimal environment variables
+
+Only these variables are required for a basic local boot:
+
+```bash
+DATABASE_URL="postgresql://postgres:password@localhost:5432/nextdevtpl"
+BETTER_AUTH_SECRET="replace-with-a-random-secret"
+BETTER_AUTH_URL="http://localhost:3000"
+```
+
+Generate a strong local secret with:
+
+```bash
+openssl rand -base64 32
+```
+
+OAuth, email, payments, storage, Redis, logging, monitoring, AI, and background jobs can be enabled later.
+
+## Initialize the database
+
+For a new local database, push the current Drizzle schema:
+
+```bash
+pnpm db:push
+```
+
+Use migrations for shared or production databases:
+
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
+
+## Start the dev server
+
+```bash
+pnpm dev
+```
+
+Open:
+
+```txt
+http://localhost:3000
+```
+
+The middleware will route you to the active locale, for example `/en` or `/zh`.
+
+## Verify the app
+
+After startup, verify these flows:
+
+| Check | Expected result |
+| --- | --- |
+| Home page | Marketing page renders without missing translation errors |
+| Sign up | Email/password account can be created |
+| Sign in | Authenticated user reaches `/dashboard` |
+| Dashboard | Sidebar, settings, credits, and support links render |
+| Admin | User with `role = "admin"` can access `/admin` |
+| Docs | `/en/docs` and `/zh/docs` show language-specific content |
+
+## Common commands
+
+```bash
+pnpm dev            # Start Next.js dev server
+pnpm build          # Create a production build
+pnpm start          # Start production server
+pnpm typecheck      # Run TypeScript type checking
+pnpm lint           # Run Biome lint
+pnpm check          # Run Biome check with fixes
+pnpm db:push        # Push Drizzle schema in development
+pnpm db:generate    # Generate migration files
+pnpm db:migrate     # Run migrations
+pnpm db:studio      # Open Drizzle Studio
+pnpm test:run       # Run tests once
+```
+

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

@@ -0,0 +1,51 @@
+---
+title: Storage
+description: Configure S3 or Cloudflare R2 compatible storage and presigned uploads.
+---
+
+# Storage
+
+The storage layer is compatible with S3-style providers such as AWS S3, Cloudflare R2, and MinIO.
+
+## Main files
+
+| Path | Purpose |
+| --- | --- |
+| `src/features/storage/providers/s3.ts` | S3-compatible provider |
+| `src/features/storage/actions.ts` | Storage Server Actions |
+| `src/features/storage/utils.ts` | Utility helpers |
+| `src/features/storage/types.ts` | Storage types |
+| `src/app/api/upload/presigned/route.ts` | Presigned upload endpoint |
+| `src/app/image-proxy/[...path]/route.ts` | Image proxy route |
+| `src/test/storage/security.test.ts` | Storage security tests |
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `STORAGE_ENDPOINT` | Provider endpoint, for example R2 endpoint |
+| `STORAGE_REGION` | S3 region or provider-compatible value |
+| `STORAGE_BUCKET` | Bucket name |
+| `STORAGE_ACCESS_KEY_ID` | Access key |
+| `STORAGE_SECRET_ACCESS_KEY` | Secret key |
+
+## Upload model
+
+1. Client requests a presigned upload URL.
+2. Server validates the request and returns upload metadata.
+3. Client uploads directly to the storage provider.
+4. App stores or uses the returned object key.
+5. Public display can go through the image proxy when needed.
+
+## Security checklist
+
+- Validate file type and size before creating presigned URLs.
+- Keep object keys scoped and hard to guess.
+- Do not expose secret keys to the browser.
+- Prefer private buckets plus signed reads or proxy routes.
+- Run storage security tests after changing upload rules.
+
+```bash
+pnpm test:run src/test/storage
+```
+

package/template/src/content/docs/zh/admin-and-support.mdx

@@ -0,0 +1,65 @@
+---
+title: 管理后台和工单
+description: 管理用户、角色、工单和客户支持流程。
+---
+
+# 管理后台和工单
+
+模板内置了一个简单但可用的管理后台和工单系统。
+
+## 管理后台
+
+Admin 路由在：
+
+```txt
+src/app/[locale]/(admin)/admin
+```
+
+主要组件：
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/features/admin/components/admin-sidebar.tsx` | Admin 导航 |
+| `src/app/[locale]/(admin)/admin/page.tsx` | Admin 概览 |
+| `src/app/[locale]/(admin)/admin/users/page.tsx` | 用户管理 |
+| `src/app/[locale]/(admin)/admin/tickets/page.tsx` | 工单队列 |
+| `src/app/[locale]/(admin)/admin/tickets/[id]/page.tsx` | 工单详情 |
+
+## 工单系统
+
+用户工单路由在：
+
+```txt
+src/app/[locale]/(dashboard)/dashboard/support
+```
+
+功能文件：
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/features/support/actions/ticket.ts` | 工单 actions |
+| `src/features/support/actions/admin-users.ts` | Admin 用户 helpers |
+| `src/features/support/components` | 工单表单、回复、状态控件 |
+| `src/features/support/schemas` | 校验 schemas |
+| `src/test/support` | 工单和 admin user 测试 |
+
+## 工单状态流
+
+推荐状态流：
+
+```txt
+open -> in_progress -> resolved
+```
+
+回复用户时不要暴露内部日志、密钥或供应商错误详情。
+
+## 管理员权限
+
+Admin 权限依赖当前用户的 role。本地测试时，创建用户后在数据库里设置 `role = 'admin'`。
+
+## 测试
+
+```bash
+pnpm test:run src/test/support
+```
+

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

@@ -0,0 +1,71 @@
+---
+title: 认证
+description: 了解 Better Auth 集成、认证路由、角色和受保护页面。
+---
+
+# 认证
+
+认证基于 Better Auth，并接入了 App Router、middleware、Dashboard 和 Admin 权限控制。
+
+## 主要文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/lib/auth/api.ts` | Better Auth API 配置 |
+| `src/lib/auth/client.ts` | 客户端认证 helpers |
+| `src/lib/auth/server.ts` | 服务端 session helpers |
+| `src/lib/auth/edge.ts` | middleware 可用的认证检查和公开路由配置 |
+| `src/lib/auth/admin.ts` | 管理员相关 helpers |
+| `src/app/api/auth/[...all]/route.ts` | Better Auth route handler |
+| `src/features/auth/components` | 登录、注册、找回密码 UI |
+
+## 支持的流程
+
+| 流程 | 说明 |
+| --- | --- |
+| 邮箱密码 | 最基础的本地认证流程 |
+| GitHub OAuth | 需要 GitHub OAuth app 凭证 |
+| Google OAuth | 需要 Google Cloud OAuth 凭证 |
+| 重置密码 | 需要邮件服务发送重置邮件 |
+| 角色权限 | 使用 `user` 和 `admin` 区分普通用户和管理员 |
+
+## 公开和受保护路由
+
+middleware 和 edge auth helpers 会判断哪些路由公开，哪些路由需要 session。公开路由包括营销页、认证页、博客、法律页面、文档和部分 API。
+
+用户登录后的页面在：
+
+```txt
+src/app/[locale]/(dashboard)/dashboard
+```
+
+管理员页面在：
+
+```txt
+src/app/[locale]/(admin)/admin
+```
+
+## 给自己设置管理员
+
+本地创建用户后，在数据库里把用户角色改成 `admin`：
+
+```sql
+update "user"
+set role = 'admin'
+where email = 'you@example.com';
+```
+
+然后访问：
+
+```txt
+/zh/admin
+```
+
+## 新增 OAuth Provider
+
+1. 在供应商控制台创建 OAuth 凭证。
+2. 把 client id 和 secret 写入 `.env.local`。
+3. 配置和 `BETTER_AUTH_URL` 匹配的 callback URL。
+4. 如果要展示按钮，更新认证 UI。
+5. 本地测试通过后再上生产。
+

package/template/src/content/docs/zh/background-jobs.mdx

@@ -0,0 +1,53 @@
+---
+title: 后台任务
+description: 使用 Inngest 运行异步产品流程。
+---
+
+# 后台任务
+
+后台任务使用 Inngest。适合处理不应该阻塞请求的流程，例如积分过期、投递重试、邮件批处理、异步产品任务等。
+
+## 主要文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/inngest/client.ts` | Inngest client |
+| `src/inngest/functions.ts` | function 定义 |
+| `src/inngest/index.ts` | exports |
+| `src/app/api/inngest/route.ts` | Inngest route handler |
+| `src/app/api/jobs/credits/expire/route.ts` | 积分过期 job endpoint |
+| `src/test/jobs/cron-expire.test.ts` | job 测试 |
+
+## 本地开发
+
+先启动应用：
+
+```bash
+pnpm dev
+```
+
+如果需要本地检查或触发 function，再使用 Inngest dev server。
+
+## 生产环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `INNGEST_EVENT_KEY` | 向 Inngest 发送事件 |
+| `INNGEST_SIGNING_KEY` | 校验 Inngest 请求 |
+
+## Job 设计规则
+
+- job 必须尽量幂等。
+- 保存足够状态，方便 retry 后恢复。
+- 不要因为重复 webhook 或重复事件重复发积分。
+- 优先拆成小的可组合函数。
+- 日志里记录 job id 和外部事件 id。
+
+## 测试
+
+修改过期逻辑后运行：
+
+```bash
+pnpm test:run src/test/jobs
+```
+

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

@@ -0,0 +1,70 @@
+---
+title: 配置说明
+description: 配置 NextDevTpl 需要的必填和可选服务。
+---
+
+# 配置说明
+
+项目通过环境变量配置。建议先填必填项，让项目跑起来，再按业务需要逐步打开外部服务。
+
+## 最小必填项
+
+| 变量 | 作用 |
+| --- | --- |
+| `DATABASE_URL` | Drizzle 和 Better Auth 使用的 PostgreSQL 连接串 |
+| `BETTER_AUTH_SECRET` | 用于签名认证/session 数据 |
+| `BETTER_AUTH_URL` | Better Auth callback 和 cookie 使用的站点地址 |
+
+示例：
+
+```bash
+DATABASE_URL="postgresql://postgres:password@localhost:5432/nextdevtpl"
+BETTER_AUTH_SECRET="replace-with-a-random-secret"
+BETTER_AUTH_URL="http://localhost:3000"
+```
+
+## 开发阶段推荐配置
+
+| 服务 | 变量 | 说明 |
+| --- | --- | --- |
+| GitHub OAuth | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | 回调地址：`/api/auth/callback/github` |
+| Google OAuth | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | 回调地址：`/api/auth/callback/google` |
+| Resend | `RESEND_API_KEY`, `EMAIL_FROM` | 开启真实邮件验证和重置密码邮件 |
+
+如果没有配置邮件，先测试不依赖邮件投递的认证流程。
+
+## 可选产品服务
+
+| 服务 | 变量 | 用途 |
+| --- | --- | --- |
+| Creem | `CREEM_API_KEY`, `CREEM_WEBHOOK_SECRET` | 订阅 checkout、积分购买、webhook |
+| S3/R2 | `STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET`, `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY` | 文件上传和代理访问 |
+| Upstash Redis | `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN` | API 和匿名访问限流 |
+| Axiom | `AXIOM_TOKEN`, `AXIOM_DATASET` | 云端结构化日志 |
+| Sentry | `NEXT_PUBLIC_SENTRY_DSN`, `SENTRY_AUTH_TOKEN` | 错误监控和 release 上传 |
+| AI Provider | `OPENAI_API_KEY` 以及供应商相关配置 | `src/lib/ai` 抽象层 |
+| Inngest | `INNGEST_EVENT_KEY`, `INNGEST_SIGNING_KEY` | 生产后台任务 |
+
+## 降级策略
+
+可选服务不应该阻断基础启动。预期行为如下：
+
+| 缺少服务 | 预期行为 |
+| --- | --- |
+| Redis | 限流降级，不让应用启动失败 |
+| Axiom | 日志输出到本地 |
+| Sentry | 监控 no-op 或 console-only |
+| Storage | 上传功能不可用，但应用外壳可运行 |
+| Creem | 支付流程不可用，非支付页面可运行 |
+| Inngest keys | 本地开发不强依赖生产签名密钥 |
+
+## 常改配置入口
+
+| 路径 | 修改内容 |
+| --- | --- |
+| `src/config/site.ts` | 站点名、URL、metadata、社交链接 |
+| `src/config/nav.ts` | Header、Footer、Dashboard、Admin 导航 |
+| `src/config/payment.ts` | 支付产品和 checkout 配置 |
+| `src/config/subscription-plan.ts` | 套餐限制和价格展示 |
+| `messages/*.json` | UI 文案 |
+| `.env.local` | 本地密钥和服务凭证 |

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

@@ -0,0 +1,69 @@
+---
+title: 积分系统
+description: 了解内置积分系统、账本记录和过期模型。
+---
+
+# 积分系统
+
+积分模块是 NextDevTpl 的核心产品能力之一，适合 AI 工具、按量计费 SaaS、付费导出等场景。
+
+## 主要文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/features/credits/core.ts` | 余额和交易核心逻辑 |
+| `src/features/credits/actions.ts` | 积分相关 Server Actions |
+| `src/features/credits/config.ts` | 积分套餐和展示配置 |
+| `src/features/credits/components` | 余额、用量、购买、历史记录 UI |
+| `src/app/[locale]/(dashboard)/dashboard/credits/buy` | 积分购买页 |
+| `src/test/credits` | 积分完整性和购买测试 |
+
+## 核心概念
+
+| 概念 | 说明 |
+| --- | --- |
+| Balance | 用户当前可用积分 |
+| Transaction | 一次积分变动记录 |
+| Batch | 一批同来源、同过期规则的积分 |
+| FIFO 过期 | 老批次积分优先消耗 |
+| Purchase package | 一次性购买的积分套餐 |
+
+## 典型流程
+
+### 购买积分
+
+1. 用户进入 `/dashboard/credits/buy`。
+2. 选择积分套餐。
+3. 支付层创建 checkout。
+4. webhook 确认付款成功。
+5. 给用户发放积分。
+6. 交易历史记录这次购买。
+
+### 消耗积分
+
+业务功能不要直接改一个余额数字，应该调用 credits core。这样才能保留审计记录和过期规则。
+
+### 过期积分
+
+过期依赖批次 metadata 和后台任务。后台任务说明见 [后台任务](/zh/docs/background-jobs)。
+
+## 修改积分套餐
+
+编辑：
+
+```txt
+src/features/credits/config.ts
+```
+
+套餐 ID 一旦进入支付或审计记录，就不要随意改名。
+
+## 测试
+
+修改积分逻辑后运行：
+
+```bash
+pnpm test:run src/test/credits
+```
+
+积分 bug 本质上是财务/账务 bug，不只是 UI bug。
+

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

@@ -0,0 +1,95 @@
+---
+title: 二开指南
+description: 常见品牌、导航、定价、页面和模块定制入口。
+---
+
+# 二开指南
+
+这页列出把 NextDevTpl 改成自己 SaaS 时最常见的修改入口。
+
+## 品牌
+
+| 修改项 | 路径 |
+| --- | --- |
+| 站点名、URL、metadata | `src/config/site.ts` |
+| Logo | `public/logo.svg` 和 Header 组件 |
+| 全局样式 | `src/app/globals.css` |
+| Open Graph 图片模板 | `src/features/shared/components/og-image-template.tsx` |
+
+## 导航
+
+| 区域 | 路径 |
+| --- | --- |
+| Header 和 Footer | `src/config/nav.ts` |
+| Dashboard 侧边栏 | `src/config/nav.ts` 和 `src/features/dashboard/components/sidebar.tsx` |
+| Admin 侧边栏 | `src/config/nav.ts` 和 `src/features/admin/components/admin-sidebar.tsx` |
+
+## 首页
+
+营销页组件在：
+
+```txt
+src/features/marketing/components
+```
+
+首页路由在：
+
+```txt
+src/app/[locale]/(marketing)/page.tsx
+```
+
+大部分文案在：
+
+```txt
+messages/en.json
+messages/zh.json
+```
+
+## 定价和套餐
+
+| 修改项 | 路径 |
+| --- | --- |
+| 套餐名和限制 | `src/config/subscription-plan.ts` |
+| 支付产品映射 | `src/config/payment.ts` |
+| 定价区 UI | `src/features/marketing/components/pricing-section.tsx` |
+| 订阅 UI | `src/features/subscription` |
+
+## 新增产品模块
+
+新功能建议放在：
+
+```txt
+src/features/<your-feature>
+```
+
+推荐结构：
+
+```txt
+src/features/example/
+├── actions.ts
+├── components/
+├── schemas/
+├── types.ts
+└── index.ts
+```
+
+路由组合放在 `src/app`，可复用业务逻辑放在 feature module。
+
+## 内容
+
+| 内容 | 路径 |
+| --- | --- |
+| 文档 | `src/content/docs/<locale>` |
+| 博客 | `src/content/blog/<locale>` |
+| 法律页面 | `src/content/legal/<locale>` |
+| PSEO 数据 | `src/features/pseo/data/pseo-pages.json` |
+
+## 提交前检查
+
+```bash
+pnpm typecheck
+pnpm lint
+```
+
+如果改了认证、积分、支付、存储、工单或后台任务，要跑对应测试。
+

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

@@ -0,0 +1,66 @@
+---
+title: 数据库
+description: 在 NextDevTpl 中使用 PostgreSQL 和 Drizzle ORM。
+---
+
+# 数据库
+
+NextDevTpl 使用 PostgreSQL 和 Drizzle ORM。schema 是认证、积分、支付、工单和用户数据的事实来源。
+
+## 主要文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/db/schema.ts` | 表结构定义 |
+| `src/db/index.ts` | 数据库 client |
+| `drizzle.config.ts` | Drizzle 配置 |
+| `drizzle/` | 生成的迁移和 snapshot |
+| `src/test/utils/db.ts` | 测试数据库 helpers |
+
+## 开发流程
+
+新本地数据库：
+
+```bash
+pnpm db:push
+```
+
+需要评审和部署的 schema 变更：
+
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
+
+查看本地数据：
+
+```bash
+pnpm db:studio
+```
+
+## push 和 migration 的区别
+
+| 命令 | 使用场景 |
+| --- | --- |
+| `pnpm db:push` | 本地初始化或快速迭代 |
+| `pnpm db:generate` | 修改了 `src/db/schema.ts`，需要生成迁移文件 |
+| `pnpm db:migrate` | 执行已提交的迁移 |
+
+## schema 修改 checklist
+
+1. 修改 `src/db/schema.ts`。
+2. 更新读写该表的 feature service/action。
+3. 根据环境选择 push 或 migration。
+4. 在 `src/test` 补测试。
+5. 运行 `pnpm typecheck` 和相关测试。
+
+## 常见表区域
+
+| 区域 | 使用方 |
+| --- | --- |
+| 用户和 session | Better Auth |
+| 积分和交易 | Credits ledger 和购买流程 |
+| 订阅 | 支付和套餐查询 |
+| 工单 | 用户工单和后台处理 |
+| 存储记录 | 上传和安全测试 |
+