# D8D Starter 开发环境配置指南

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 1.0 | 2025-09-15 | 初始开发指南 | Sarah (PO) |

## 1. 环境要求

### 系统要求
- **操作系统**: macOS 10.15+, Windows 10+, Linux Ubuntu 18.04+
- **Node.js**: 20.18.3 或更高版本
- **npm**: 10.8.2 或更高版本
- **Docker**: 24.0+ (用于本地开发环境)
- **Docker Compose**: 2.20+

### 推荐开发工具
- **代码编辑器**: VS Code (推荐) 或 WebStorm
- **浏览器**: Chrome 120+, Firefox 115+, Safari 16+
- **终端**: iTerm2 (macOS), Windows Terminal, GNOME Terminal

## 2. 快速开始

### 2.1 克隆项目
```bash
git clone <repository-url>
cd d8d-starter
```

### 2.2 安装依赖
```bash
# 安装根目录依赖
npm install

# 安装客户端依赖
cd src/client
npm install

# 安装服务器依赖
cd ../server
npm install

# 返回根目录
cd ../..
```

### 2.3 环境变量配置

创建环境配置文件：
```bash
# 复制示例文件
cp .env.example .env
```

编辑 `.env` 文件：
```env
# 数据库配置 (PostgreSQL)
DATABASE_URL=postgresql://postgres:password@localhost:5432/d8dai
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=d8dai
DB_USERNAME=postgres
DB_PASSWORD=password

# 应用配置
NODE_ENV=development
PORT=3000
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=7d

# 前端配置
VITE_API_BASE_URL=http://localhost:3000
VITE_APP_NAME=D8D Starter

# 文件存储 (MinIO)
OSS_BASE_URL=https://oss.d8d.fun
OSS_ACCESS_KEY=your-access-key
OSS_SECRET_KEY=your-secret-key
OSS_BUCKET_NAME=d8dai

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
```

### 2.4 启动开发环境

#### 选项A: 使用 Docker Compose (推荐)
```bash
# 启动所有服务 (数据库 + Redis + 应用)
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

#### 选项B: 手动启动
```bash
# 启动后端服务器 (端口3000)
npm run dev:server

# 启动前端开发服务器 (端口5173)
npm run dev:client

# 或者同时启动前后端
npm run dev
```

## 3. 数据库设置

### 3.1 使用 Docker 数据库
```bash
# 启动 PostgreSQL 和 Redis
docker-compose up postgres redis -d

# 运行数据库迁移
npm run db:migrate

# 运行数据种子
npm run db:seed
```

### 3.2 手动数据库配置
1. 安装 PostgreSQL 15+ 和 Redis 7+
2. 创建数据库: `CREATE DATABASE d8dai;`
3. 配置连接信息在 `.env` 文件中

## 4. 开发工作流

### 4.1 代码结构
```
src/
├── client/          # React前端代码
│   ├── admin/       # 管理后台
│   ├── home/        # 用户前台
│   ├── components/  # 共享组件
│   └── lib/         # 工具库
├── server/          # Node.js后端
│   ├── api/         # API路由
│   ├── modules/     # 业务模块
│   └── utils/       # 工具函数
└── shared/          # 前后端共享代码
```

### 4.2 常用开发命令
```bash
# 开发命令
npm run dev          # 启动完整开发环境
npm run dev:client   # 仅启动前端
npm run dev:server   # 仅启动后端

# 构建命令
npm run build        # 生产构建
npm run build:client # 仅构建前端
npm run build:server # 仅构建后端

# 数据库命令
npm run db:migrate   # 运行数据库迁移
npm run db:seed      # 填充种子数据
npm run db:reset     # 重置数据库

# 代码质量
npm run lint         # 代码检查
npm run lint:fix     # 自动修复
npm run typecheck    # 类型检查
```

### 4.3 热重载和调试
- 前端: Vite 热重载，修改后自动刷新
- 后端: Nodemon 自动重启，支持调试
- VS Code 调试配置已包含在 `.vscode/launch.json`

## 5. 测试环境配置

### 5.1 测试数据库设置
```bash
# 创建测试数据库 (PostgreSQL)
createdb d8dai_test

# 或者使用Docker测试数据库
docker-compose -f docker-compose.test.yml up -d
```

### 5.2 测试环境变量
创建 `.env.test` 文件：
```env
NODE_ENV=test
DATABASE_URL=postgresql://postgres:password@localhost:5432/d8dai_test
JWT_SECRET=test-jwt-secret
```

## 6. 故障排除

### 常见问题

**端口冲突**:
```bash
# 查找占用端口的进程
lsof -i :3000  # 后端端口
lsof -i :5173  # 前端端口
lsof -i :3306  # 数据库端口

# 终止进程
kill -9 <PID>
```

**依赖安装失败**:
```bash
# 清除缓存并重新安装
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
```

**数据库连接问题**:
- 确保 PostgreSQL 服务正在运行
- 检查 `.env` 文件中的数据库配置
- 验证网络连接和防火墙设置

### 获取帮助
- 查看详细日志: `docker-compose logs [service]`
- 检查服务状态: `docker-compose ps`
- 查阅架构文档: `docs/architecture.md`

## 7. 下一步

1. ✅ 完成环境设置
2. 🚀 运行 `npm run dev` 启动开发服务器
3. 📖 阅读 `docs/prd.md` 了解产品需求
4. 🏗️ 查看 `docs/architecture.md` 了解系统架构
5. 🧪 运行 `npm test` 执行测试

---

**最后更新**: 2025-09-15
**维护者**: 开发团队
**文档状态**: 正式版