快速开始
从零到部署 - 10 分钟内运行 ProductReady
快速开始
欢迎使用 ProductReady！🚀 本指南将帮助你在10 分钟内从零开始运行一个可用的应用。
ProductReady 新手？ 先试试演示模式 - 无需设置数据库！
你将看到的效果
设置完成后，ProductReady 提供了几个开箱即用的页面。以下是你可以探索的内容：
| 页面 | 路由 | 描述 | 截图 |
|---|---|---|---|
| 落地页 | / | 营销主页，包含英雄区、功能特性和行动号召 | 即将添加 |
| 仪表盘 | /dashboard | 主应用界面，包含任务管理和分析功能 | 即将添加 |
| 智能体任务 | /agent | AI 智能体任务创建和监控界面 | 即将添加 |
| 系统管理 | /systemadmin | 系统管理面板（需要管理员权限） | 即将添加 |
在线演示可用！ 在任何路由后添加 ?demo=1 参数（例如 /dashboard?demo=1）即可无需认证即可探索所有功能。
快速访问链接：
- 🏠 落地页：
http://localhost:3000/ - 📊 仪表盘：
http://localhost:3000/dashboard（或/dashboard?demo=1） - 🤖 智能体任务：
http://localhost:3000/agent（或/agent?demo=1） - ⚙️ 系统管理：
http://localhost:3000/systemadmin（或/systemadmin?demo=1）
注意：截图将在下次文档更新时添加。目前请启动开发服务器并亲自探索这些路由！
使用 ProductReady 的两种方式
ProductReady 可以在两种场景下帮助你：
🆕 新项目从 ProductReady 模板开始 你正在构建新产品，希望：
耗时：5 分钟 + AI 设置 | 🔄 现有项目采用 ProductReady 模式 你有现有应用，希望：
耗时：30-60 分钟 + AI 迁移 |
只是想看看？ 先试试演示模式 - 无需设置，2 分钟看到所有功能！
先决条件
开始之前，确保你已安装：
- Node.js 24.18.0 LTS - 在这里下载
- pnpm - 安装命令：
npm install -g pnpm - Git - 在这里下载
- 数据库（仅手动设置需要） - PostgreSQL（Neon / Supabase / 本地）
使用 Windows？ 我们建议使用 WSL2 以获得最佳体验。
从 ProductReady 创建新项目
如果你从零开始，使用此方法。
AI 辅助初始化（推荐）
克隆 ProductReady
git clone https://github.com/mr-kelly/productready.git my-new-project
cd my-new-project/apps/productready
pnpm install使用这个 AI 提示词
复制并粘贴给 GitHub Copilot、Claude 或 Cursor：
apps/productready 目录包含 ProductReady 模板代码。请帮我初始化它用于我的新项目：
阶段 1 - 清理：
1. 阅读 README.md 并理解项目结构
2. 完整删除 changelog/ 目录（我们将重新开始）
3. 清理 content/docs/：
- 在 content/docs/en/ 中只保留 index.mdx，内容改为简单的 "# Welcome" 占位符
- 在 content/docs/zh-CN/ 中只保留 index.mdx，内容改为 "# 欢迎" 占位符
- 删除两个语言文件夹中的所有其他 .mdx 文件
4. 更新 src/db/seed.ts：
- 保留演示用户种子数据（demo@productready.dev）
- 删除所有示例文章种子数据
- 如果不需要，删除代理任务种子数据
5. 清理 spec/ 目录：
- 保留目录结构
- 清空 product-design.md、icp-guide.md、marketing-guide.md 的内容
- 接下来我们会填充这些文件
阶段 2 - 初始化我的项目：
项目名称：[你的项目名称]
描述：[你在构建什么]
核心功能：
- [功能_1]
- [功能_2]
- [功能_3]
目标用户：[这是为谁设计的]
阶段 3 - 规划：
清理完成后，创建详细的实施计划，包括：
1. 需要的数据库架构更改（修改 src/db/schema/）
2. 需要创建/修改的 tRPC 路由（在 src/server/routers/）
3. 需要的 UI 页面和组件
4. 身份验证/授权需求
5. 需要的 API 集成
请先执行阶段 1 清理，然后询问我项目详情以进行阶段 2。步骤 3：与 AI 迭代开发
AI 完成清理后：
- 定义你的产品：AI 询问时填写你的项目详情
- 审查计划：AI 会创建待办事项列表 - 审查并调整
- 开始构建：在 AI 协助下完成待办事项
- 频繁测试：使用
pnpm dev在本地测试更改
示例对话流程
你：[粘贴上面的 AI 提示词]
AI：✅ 完成阶段 1 清理。现在，请告诉我关于你的项目：
- 它解决什么问题？
- 谁是你的目标用户？
- 核心功能是什么？
你：我在构建一个面向 SaaS 公司的客户反馈工具。
目标用户：产品经理和创始人
功能：调查创建、响应收集、情感分析
AI：很好！我现在将更新：
- spec/product-design.md 填写你的 PRD
- 数据库架构用于调查、响应、情感数据
- tRPC 路由用于 CRUD 操作
- UI 组件用于调查构建器
这是实施计划：[详细待办事项]
我应该继续进行数据库架构更改吗？
你：是的，但给调查添加一个"标签"字段用于分类
AI：✅ 已更新架构添加标签。这是更改...迭代开发
AI 设置的优势：
- ⚡ 快 10 倍 比手动清理
- 🎯 智能规划 - AI 创建结构化待办事项
- 📝 文档化 - AI 在你构建时更新规范
- 🔄 迭代式 - 边做边完善需求
- 🧠 学习 - AI 解释它在做什么
迁移现有项目
如果你有现有的 Next.js/Node.js 应用，想采用 ProductReady 的模式。
为什么迁移到 ProductReady 模式？
- ✅ 类型安全的 API - tRPC 消除 API 错误
- ✅ 现代认证 - Better Auth 支持 OAuth
- ✅ 更好的 DX - Drizzle ORM 提供类型安全的数据库查询
- ✅ 清晰结构 - 可扩展的代码组织
何时重构 vs 重新开始
✅ 重构现有项目，如果：
| ✅ 从 ProductReady 重新开始，如果：
|
AI 迁移提示词
使用此提示词让 AI 帮你迁移现有项目：
我在 [你的项目路径] 有一个现有项目。我想重构它以遵循 ProductReady 模板架构。
请阅读 apps/productready 的 ProductReady 代码理解其模式，然后帮我迁移我的项目：
阶段 1 - 分析：
1. 分析我当前的项目结构和技术栈
2. 与 ProductReady 的架构对比（tRPC、Drizzle、Better Auth、VO/DTO）
3. 识别差距和痛点
4. 创建优先级迁移路线图
阶段 2 - 架构采用：
帮我迁移到：
- ✅ tRPC v11（替换我的 REST API 或从 tRPC v10 升级）
- ✅ Better Auth（替换 NextAuth/Auth.js/自定义认证）
- ✅ Drizzle ORM（从 Prisma/TypeORM/Sequelize 迁移）
- ✅ VO/DTO/PO 模式（在 API 边界添加类型安全）
- ✅ Fumadocs（设置文档系统）
- ✅ 演示模式支持（添加 ?demo=1 用于演示）
- ✅ CSS 变量设计系统（替换硬编码颜色）
阶段 3 - 代码重组：
重构我的代码以匹配 ProductReady 的布局：
- src/app/ - Next.js App Router 带路由组
- src/server/routers/ - 带 VO 验证的 tRPC 路由
- src/db/schema/ - 带关系的 Drizzle schemas
- src/lib/ - 共享工具和配置
- spec/ - 产品规范和文档
阶段 4 - 渐进式迁移：
创建逐功能迁移计划：
1. 新旧系统并行运行
2. 使用功能开关切换实现
3. 一次迁移一个 API 端点/页面
4. 保持生产环境正常运行
5. 验证后才删除旧代码
我的当前技术栈：
- 框架：[例如，Next.js 14 App Router]
- 数据库：[例如，Prisma + PostgreSQL]
- 认证：[例如，NextAuth.js]
- API：[例如，REST 端点或 tRPC v10]
- 样式：[例如，Tailwind CSS + shadcn/ui]
- 状态管理：[例如，Zustand、Redux]
需要解决的痛点：
[描述你的问题 - 例如，"前后端之间没有类型安全"、"会话处理的认证错误"、"数据库查询慢"]
请从阶段 1 分析开始，创建详细的迁移计划，包括：
- 需要注意的破坏性变更
- 数据迁移策略
- 每个阶段的回滚计划
- 每个步骤的预估工作量示例迁移场景
场景 1：Prisma → Drizzle
AI 将：
- 将 Prisma schema 转换为 Drizzle
- 生成等效的迁移
- 更新查询为 Drizzle 语法
- 从 Prisma schema 添加 Zod 验证
- 测试数据完整性
场景 2：NextAuth → Better Auth
AI 将：
- 迁移 session/user 表
- 转换认证提供商配置
- 更新登录/注册流程
- 保留现有用户数据
- 端到端测试认证
场景 3：REST → tRPC
AI 将：
- 将 REST 端点转换为 tRPC 路由
- 添加输入/输出 Zod 验证
- 实现 VO/DTO 模式
- 更新前端为 tRPC 客户端
- 添加端到端类型安全
迁移检查清单
AI 完成迁移阶段后：
- 所有测试通过 - 现有功能无回归
- 数据库已迁移 - 数据完整性已验证
- 认证可用 - 用户可以用现有账户登录
- API 功能正常 - 所有端点正确响应
- 类型安全 - 没有
any类型，完整的 IntelliSense - 文档已更新 - README 和规范反映新架构
- 性能正常 - 迁移未导致性能下降
- 部署已测试 - 预发布环境正常工作
渐进式迁移的优势
- ✅ 低风险 - 一次迁移一层
- ✅ 保持运行 - 迁移期间功能保持可用
- ✅ 逐步学习 - 在采用新模式时理解它们
- ✅ 易于回滚 - 每个阶段都可以在需要时回滚
- ✅ 团队协调 - 每个人一起学习新架构
重要提示：在进入下一阶段之前，始终彻底测试每个迁移阶段。在过渡期间使用功能开关在新旧实现之间切换。
演示模式
想在无需任何设置的情况下探索 ProductReady？先试试演示模式！
克隆仓库
git clone https://github.com/mr-kelly/productready.git
cd kapps/apps/productready打开演示模式
访问：http://localhost:3000/dashboard?demo=1
你将看到一个可用的仪表板，包含：
- 模拟 AI 代理任务
- 示例数据
- 所有功能都可用（无需数据库！）
适用于：探索功能、测试 UI、演示展示
手动设置
准备以传统方式设置 ProductReady？按照以下步骤操作。
克隆并安装
# 克隆仓库
git clone https://github.com/mr-kelly/productready.git
cd kapps/apps/productready
# 安装依赖
pnpm install创建环境文件
# 复制示例环境文件
cp .env.example .env现在在编辑器中打开 .env 并填入必需的值：
# 数据库（必需）
PG_DATABASE_URL="postgresql://user:password@localhost:5432/productready"
# 认证（必需）
BETTER_AUTH_SECRET="your-secret-key-min-32-chars"
BETTER_AUTH_URL="http://localhost:3000"
# OAuth（可选 - 稍后添加）
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""生成密钥：运行 openssl rand -base64 32 为 BETTER_AUTH_SECRET 生成随机密钥
设置数据库
选项 1：使用 Neon（推荐新手）
- 访问 neon.tech 并创建免费账户
- 创建新项目
- 复制连接字符串（类似：
postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb） - 将其粘贴到
.env中作为PG_DATABASE_URL
选项 2：使用 Supabase
- 访问 supabase.com 并创建项目
- 进入项目设置 → 数据库
- 复制"连接字符串"（启用连接池）
- 将其粘贴到
.env中作为PG_DATABASE_URL
选项 3：使用 Docker Compose（推荐本地开发）
ProductReady 项目包含了 docker-compose.yml 配置文件，可以一键启动本地开发所需的数据库服务（PostgreSQL、Redis、Typesense）。
# 在项目根目录（kapps/）运行
make db这将启动以下服务：
- PostgreSQL:
localhost:5432(用户名:bika, 密码:bikabika, 数据库:bikadev) - Redis:
localhost:6379 - Redis Insight:
http://localhost:8001(管理界面) - Typesense:
http://localhost:8108(API Key:bikabika)
你的 .env 配置应为：
PG_DATABASE_URL="postgresql://bika:bikabika@localhost:5432/bikadev"提示：使用 make db-stop 停止服务，make db-logs 查看日志。更多命令请参考部署指南。
运行数据库迁移
# 生成迁移文件（如需要）
pnpm db:generate
# 运行迁移以创建表
pnpm db:migrate你应该看到类似输出：
✓ 迁移成功
✓ 已创建表：users、sessions、tasks、posts填充数据库（可选）
想要一些示例数据来测试？
pnpm db:seed这将创建：
- 演示用户：
demo@productready.dev（密码：demo123456） - 管理员用户：
admin@productready.dev（密码显示在 seed 输出中，或通过SITE_ADMIN_PASSWORD设置） - 示例任务和文章
- 所有功能的测试数据
快速入门教程
让我们通过实际示例探索 ProductReady 的关键功能。
登录仪表板
- 访问 http://localhost:3000/dashboard
- 使用以下账号登录：
demo@productready.dev/demo123456（如果你运行了db:seed） - 或创建新账户
创建你的第一篇文章
仪表板演示了完整的 CRUD 功能（文章）：
- 点击仪表板中的 "新建文章" 按钮
- 填写：
- 标题："我的第一篇 ProductReady 文章"
- 内容："这是一篇测试文章，用于理解 tRPC、Drizzle 和 VO/DTO 模式"
- 点击 "创建"
你的文章立即出现！这演示了：
- ✅ tRPC mutation - 类型安全的 API 调用
- ✅ Drizzle ORM - 带类型安全的数据库插入
- ✅ VO/DTO 模式 - 使用 Zod 的输入验证
- ✅ React Query - 乐观更新和缓存失效
提示：打开开发者工具的网络标签查看 tRPC 调用。查看 src/server/routers/posts.ts 了解后端实现。
尝试 AI 代理界面（即将推出）
ProductReady 包含用于自主任务执行的 AI 代理界面：
- 访问 http://localhost:3000/agent
- 代理页面展示工作流程：
- 任务队列管理
- 执行状态跟踪
- 结果显示
注意：/agent 页面是一个展示代理工作流程的 UI 原型。完整的代理执行功能正在开发中。将其作为构建自己的 AI 代理功能的参考。
你可以学到的内容：
- 代理任务生命周期（待处理 → 运行中 → 已完成）
- 实时状态更新模式
- 如何构建代理-人类交互 UI
恭喜！ 你现在拥有：
- 一个可用的 TypeScript Next.js 应用
- 使用 Drizzle ORM 的数据库
- 使用 Better Auth 的身份认证
- 使用 tRPC 的类型安全 API
- AI 就绪的任务管理系统
下一步
现在 ProductReady 已经运行，探索这些指南：
面向产品经理和设计师
面向开发者
- 项目结构 - 了解代码库
- tRPC API 指南 - 构建类型安全 API
- 数据库架构 - 添加表和关系
- 身份认证 - OAuth、会话和权限
部署到生产环境
- 部署到 Vercel - 一键部署
- Docker 部署 - 自托管选项
故障排除
"数据库连接失败"
检查 .env 中的 PG_DATABASE_URL：
- 格式是否正确？
postgresql://user:pass@host:port/db - 能用
psql连接吗？测试：psql $PG_DATABASE_URL - 数据库是否在运行？检查：
brew services list（macOS）
"端口 3000 已被占用"
终止进程或使用不同端口：
# 终止端口 3000 上的进程
lsof -ti:3000 | xargs kill -9
# 或使用不同端口
pnpm dev -- --port 3001"找不到模块"错误
清除缓存并重新安装：
rm -rf node_modules .next
pnpm install
pnpm dev仍然卡住？
- 查看常见问题
- 搜索 GitHub Issues
- 在讨论区提问
接下来做什么？
一切就绪！以下是一些想法：
- 自定义落地页 - 编辑
src/app/(home)/page.tsx - 添加新数据库表 - 查看数据库指南
- 构建新 API 端点 - 遵循 tRPC 指南
- 设计你的应用 - 使用设计系统
- 部署到生产环境 - 遵循 部署指南
准备好发布了吗？让我们开始吧！🚀