开发指南

前置要求

工具	版本	用途
Node.js	20+	运行时
pnpm	9+	包管理器
PostgreSQL	18	数据库
Redis	7+	队列和缓存

本地设置

1. 安装依赖

pnpm install

2. 配置环境变量

cp env.example .env

填入必需变量。本地开发至少需要：

• DATABASE_URL — PostgreSQL 连接字符串
• BETTER_AUTH_SECRET — 使用 openssl rand -base64 32 生成
• BETTER_AUTH_URL — http://localhost:3000
• GOOGLE_APPLICATION_CREDENTIALS — Vertex AI 服务账号密钥文件路径
• GOOGLE_VERTEX_PROJECT — GCP 项目 ID
• GOOGLE_VERTEX_LOCATION — global

3. 数据库

# 应用 Schema
npx prisma db push

# 生成客户端
npx prisma generate

# 初始化数据
npx prisma db seed

如需初始化管理员账号，请在 .env 中设置 ADMIN_EMAIL 和 ADMIN_PASSWORD。

4. 启动开发服务

# 终端 1：Web 服务（http://localhost:3000）
pnpm dev

# 终端 2：解读 Worker（解读功能必需）
pnpm worker

# 终端 3：洞察 Worker（指引/旅程功能必需）
pnpm insights-worker

# 终端 4：Telegram 机器人（可选）
pnpm telegram-bot

或在同一终端运行两个 Worker：

pnpm workers

编码规范

TypeScript

• 禁用 any — 全程严格类型
• 类型优先于接口 — 使用 type TName（不用 interface）
• 内联 Props — 组件 Props 内联定义，不抽取
• if 语句必须用大括号
• 条件渲染用三元运算符 — 使用 condition ? <A /> : null，不用 condition && <A />

样式

• Tailwind CSS v4 配合 cn() 工具函数合并类名
• text-foreground/80 用于用户端文本区域
• flex-none 用于图标防止 flex 收缩
• size-* 类 用于图标尺寸
• 组件专属 CSS 写在 ComponentName.css 文件中（不写入 globals.css）

组件

• components/ui/ 是只读的（shadcn/ui 基础组件）
• 全局自定义组件 放在 components/
• 超过 600 行要拆分 — 创建 Name/Name.tsx 目录结构
• 使用 Modal 后缀（如 UserModal 而非 UserDialog）
• 图标：首选 AppIcon（Iconify），其次 Lucide

状态管理

• Zustand 用于客户端状态（store 在 stores/ 目录）
• React Hook Form + Zod 用于表单验证
• Server Actions 用于数据变更（Next.js App Router）

国际化

• 用户端页面：使用 useTrans/getTrans 配合 12 种语言的内联字典
• 管理后台页面：仅英文，无需翻译
• 日期/时间：仅使用 Luxon（新代码不使用 date-fns）

错误处理

• 显示提示前始终先 console.error
• 通用错误必须附加："Please refresh the page and try again."
• 用户端提示：使用 @/lib/toast 帮助函数（showSuccessMessage 等）
• 管理后台提示：直接使用 sonner

AI 集成

• 使用 @ai-sdk/google-vertex 进行 AI 调用
• 始终使用 lib/ai-models.ts 中的 buildThinkingProviderOptions(modelId, desiredLevel) 来构建 providerOptions，不要手动内联 thinkingConfig
• 该 helper 会自动规范化 Prisma 大写的 ThinkingLevel 枚举，并针对不支持 'minimal' 的模型（如 gemini-3.1-pro-preview）自动将其提升为 'low'
• gemini-3.1-pro-preview 不支持 thinkingLevel: 'minimal'，需使用 'low' 或更高级别
• 廉价分类路由（intake plan/resolve、preflight、spreads/suggest）必须使用 gemini-3-flash-preview，Flash 支持所有 thinking level（含 'minimal'）

数据库工作流

Schema 变更

1. 编辑 prisma/schema.prisma
2. 运行 npx prisma db push 应用变更
3. 运行 npx prisma generate 更新客户端

重置数据库

npx prisma migrate reset && npx prisma generate && npx prisma db seed

单独初始化数据

pnpm seed:one

测试

Playwright

项目使用 Playwright 进行端到端测试：

npx playwright test

Devbox 测试面板

用于手动测试积分、订阅和用户流程，使用 Devbox 测试工具：

• Stripe 测试：/devbox/stripe-testing
• 用户切换：/devbox/user-testing

快捷预设：新用户、破产用户、Gold 订阅者、Diamond 大客户、限流用户。

关键文件参考

文件	用途
proxy.ts	中间件（路由保护、重定向、访客追踪）
lib/auth.tsx	Better Auth 配置
lib/prisma.ts	Prisma 客户端单例
lib/redis.ts	Redis 连接
lib/queue.ts	BullMQ 队列定义
lib/credits.ts	积分扣除逻辑
env.ts	环境变量验证（t3-env）
ecosystem.config.cjs	PM2 生产环境配置
config/consts.ts	应用常量

重要说明

• 中间件文件：命名为 proxy.ts，不是 middleware.ts
• 受保护路由：必须对 routing.locales 进行检查以处理 /en/me、/zh_CN/me 等
• 访客追踪：VISITOR_COOKIE 是 HTTP-only 的；使用 <PageViewTracker /> 组件（不要用客户端 JS 读取 Cookie）
• Schema 变更后：任务完成时始终运行 npx prisma generate