mini-starter/docs/development.md

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 克隆项目

git clone <repository-url>
cd d8d-starter

2.2 安装依赖

# 安装根目录依赖
npm install

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

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

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

2.3 环境变量配置

创建环境配置文件：

# 复制示例文件
cp .env.example .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 (推荐)

# 启动所有服务 (数据库 + Redis + 应用)
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

选项B: 手动启动

# 启动后端服务器 (端口3000)
npm run dev:server

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

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

3. 数据库设置

3.1 使用 Docker 数据库

# 启动 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 常用开发命令

# 开发命令
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 测试数据库设置

# 创建测试数据库 (PostgreSQL)
createdb d8dai_test

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

5.2 测试环境变量

创建 .env.test 文件：

NODE_ENV=test
DATABASE_URL=postgresql://postgres:password@localhost:5432/d8dai_test
JWT_SECRET=test-jwt-secret

6. 故障排除

常见问题

端口冲突:

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

# 终止进程
kill -9 <PID>

依赖安装失败:

# 清除缓存并重新安装
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 维护者: 开发团队 文档状态: 正式版