0.0.8.5

LOCAL_DEV_GUIDE.md

@@ -0,0 +1,166 @@
+# 本地开发指南
+
+## 快速启动
+
+### 1. 安装依赖
+
+```bash
+pnpm install
+```
+
+### 2. 配置环境变量
+
+复制 `.env.example` 到 `.env` 并配置：
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env` 文件，配置数据库连接：
+
+```env
+DATABASE_URL="postgresql://user:password@localhost:5432/chinese_family_tree"
+NEXTAUTH_URL="http://localhost:3000"
+NEXTAUTH_SECRET="your-secret-key"
+```
+
+### 3. 初始化数据库
+
+```bash
+# 生成 Prisma Client
+npx prisma generate
+
+# 同步数据库结构
+npx prisma db push
+```
+
+### 4. 启动开发服务器
+
+```bash
+pnpm dev
+```
+
+访问 http://localhost:3000
+
+## 常见问题
+
+### Prisma Client 错误
+
+**错误信息**:
+```
+Error: Failed to load external module @prisma/client
+```
+
+**解决方案**:
+```bash
+# 重新生成 Prisma Client
+npx prisma generate
+
+# 同步数据库
+npx prisma db push
+```
+
+### 数据库连接错误
+
+**确保 PostgreSQL 已启动**:
+```bash
+# macOS
+brew services start postgresql
+
+# 或检查状态
+brew services list
+```
+
+**创建数据库**:
+```bash
+# 连接到 PostgreSQL
+psql postgres
+
+# 创建数据库
+CREATE DATABASE chinese_family_tree;
+
+# 退出
+\q
+```
+
+### 多 lockfile 警告
+
+**警告信息**:
+```
+Warning: Next.js inferred your workspace root, but it may not be correct.
+```
+
+**说明**: 这是因为在父目录检测到其他 lockfile，已在 `next.config.mjs` 中配置 `turbo.root` 来消除此警告。
+
+### Session 错误
+
+**错误信息**:
+```
+[next-auth][error][CLIENT_FETCH_ERROR]
+```
+
+**解决方案**:
+1. 确保数据库已初始化：`npx prisma db push`
+2. 确保 `.env` 中的 `NEXTAUTH_URL` 正确
+3. 重启开发服务器
+
+## 开发工具
+
+### Prisma Studio
+
+可视化数据库管理工具：
+
+```bash
+npx prisma studio
+```
+
+访问 http://localhost:5555
+
+### 数据库迁移
+
+```bash
+# 创建迁移
+npx prisma migrate dev --name migration_name
+
+# 应用迁移
+npx prisma migrate deploy
+```
+
+### 查看日志
+
+开发服务器会自动显示日志。如需查看详细日志，可以在代码中添加 `console.log()`。
+
+## 项目结构
+
+```
+├── app/                    # Next.js App Router
+│   ├── api/               # API 路由
+│   ├── auth/              # 认证页面
+│   └── ...
+├── components/            # React 组件
+├── lib/                   # 工具函数
+├── prisma/               # 数据库 Schema
+│   └── schema.prisma
+├── .env                  # 环境变量（不提交到 Git）
+└── next.config.mjs       # Next.js 配置
+```
+
+## 代码规范
+
+- 使用 TypeScript
+- 遵循 ESLint 规则
+- 使用 Prettier 格式化代码
+
+## 提交代码
+
+```bash
+# 格式化代码
+pnpm format
+
+# 检查类型
+pnpm type-check
+
+# 提交
+git add .
+git commit -m "feat: your message"
+```