1f8e713ea0
- 更新P4功能测试报告 - 添加开发、测试、部署完整指南 - 记录v0.5.0-alpha版本变更 Co-Authored-By: Claude <noreply@anthropic.com>
451 lines
8.0 KiB
Markdown
451 lines
8.0 KiB
Markdown
# 开发指南
|
||
|
||
本文档说明如何进行本地开发、测试和部署。
|
||
|
||
## 目录
|
||
|
||
- [环境要求](#环境要求)
|
||
- [本地开发](#本地开发)
|
||
- [测试](#测试)
|
||
- [部署](#部署)
|
||
- [配置说明](#配置说明)
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
### 必需软件
|
||
|
||
| 软件 | 版本 | 说明 |
|
||
|-----|------|------|
|
||
| Node.js | >= 18 | 前端和后端运行环境 |
|
||
| npm | >= 9 | 包管理器 |
|
||
| Git | 任意版本 | 版本控制 |
|
||
| SQLite | 3.x | 本地数据库（开发环境） |
|
||
|
||
### 可选软件
|
||
|
||
| 软件 | 版本 | 说明 |
|
||
|-----|------|------|
|
||
| PostgreSQL | 14+ | 生产环境数据库 |
|
||
| Playwright | 最新版 | 浏览器自动化测试 |
|
||
|
||
---
|
||
|
||
## 本地开发
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone https://your-repo-url/qia.git
|
||
cd qia
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
#### 主项目
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
#### 前端（client子模块）
|
||
```bash
|
||
cd client
|
||
npm install
|
||
```
|
||
|
||
#### 后端（server子模块）
|
||
```bash
|
||
cd server
|
||
npm install
|
||
```
|
||
|
||
### 3. 数据库配置
|
||
|
||
#### 开发环境（SQLite）
|
||
无需额外配置，SQLite文件会自动创建。
|
||
|
||
```bash
|
||
# server/.env
|
||
DATABASE_URL="file:./dev.db"
|
||
```
|
||
|
||
#### 生产环境（PostgreSQL）
|
||
```bash
|
||
# server/.env
|
||
DATABASE_URL="postgresql://user:password@host:5432/qia"
|
||
```
|
||
|
||
### 4. 启动开发服务器
|
||
|
||
#### 方式一：同时启动前后端
|
||
|
||
在主目录执行：
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
这会同时启动：
|
||
- 前端：`http://localhost:5173`
|
||
- 后端：`http://localhost:3000`
|
||
|
||
#### 方式二：分别启动
|
||
|
||
**终端1 - 启动后端**
|
||
```bash
|
||
cd server
|
||
npm run dev
|
||
```
|
||
|
||
**终端2 - 启动前端**
|
||
```bash
|
||
cd client
|
||
npm run dev
|
||
```
|
||
|
||
### 5. 初始化数据库
|
||
|
||
首次启动时，Prisma会自动创建数据库并运行迁移：
|
||
|
||
```bash
|
||
cd server
|
||
npx prisma migrate dev --name init
|
||
```
|
||
|
||
如需重置数据库：
|
||
```bash
|
||
npx prisma migrate reset
|
||
```
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
### 单元测试
|
||
|
||
```bash
|
||
# 运行所有单元测试
|
||
npm test
|
||
|
||
# 运行特定模块测试
|
||
npm run test:unit
|
||
|
||
# 监听模式运行测试
|
||
npm run test:watch
|
||
```
|
||
|
||
### 端到端测试（Playwright）
|
||
|
||
#### 安装Playwright
|
||
|
||
```bash
|
||
# 在主目录安装
|
||
npm install -D @playwright/test
|
||
|
||
# 安装浏览器
|
||
npx playwright install chromium
|
||
```
|
||
|
||
#### 运行E2E测试
|
||
|
||
```bash
|
||
# 运行所有E2E测试
|
||
npm run test:e2e
|
||
|
||
# 运行特定测试文件
|
||
npx playwright test tests/reminder.spec.ts
|
||
|
||
# 以UI模式运行（可交互）
|
||
npx playwright test --ui
|
||
```
|
||
|
||
#### 使用Playwright MCP（推荐）
|
||
|
||
如果配置了Playwright MCP服务器，可以直接使用 MCP 工具进行测试：
|
||
|
||
```bash
|
||
# 启动开发服务器后，使用以下工具：
|
||
# - browser_navigate: 导航到页面
|
||
# - browser_snapshot: 获取页面快照
|
||
# - browser_click: 点击元素
|
||
# - browser_type: 输入文本
|
||
# - browser_take_screenshot: 截图
|
||
```
|
||
|
||
### 测试用例
|
||
|
||
测试用例文档位于 `docs/test-cases.md`，测试报告位于 `docs/test-report.md`。
|
||
|
||
### 测试数据库
|
||
|
||
使用独立的测试数据库避免污染开发数据：
|
||
|
||
```bash
|
||
# server/.env.test
|
||
DATABASE_URL="file:./test.db"
|
||
|
||
# 运行测试
|
||
npm run test:e2e
|
||
```
|
||
|
||
---
|
||
|
||
## 部署
|
||
|
||
### 1. 构建生产版本
|
||
|
||
#### 前端构建
|
||
```bash
|
||
cd client
|
||
npm run build
|
||
```
|
||
构建产物位于 `client/dist/`
|
||
|
||
#### 后端构建
|
||
```bash
|
||
cd server
|
||
npm run build
|
||
```
|
||
构建产物位于 `server/dist/`
|
||
|
||
### 2. 环境配置
|
||
|
||
#### 生产环境变量（server/.env）
|
||
|
||
```env
|
||
# Server
|
||
NODE_ENV=production
|
||
PORT=3000
|
||
|
||
# JWT
|
||
JWT_SECRET=your-super-secret-jwt-key-change-in-production
|
||
JWT_EXPIRES_IN=7d
|
||
JWT_REFRESH_EXPIRES_IN=30d
|
||
|
||
# Database (PostgreSQL - 腾讯云)
|
||
DB_HOST=postgres.ap-shanghai.myqcloud.com
|
||
DB_PORT=5432
|
||
DB_NAME=qia
|
||
DB_USER=qia_admin
|
||
DB_PASSWORD=your-database-password
|
||
|
||
# DeepSeek AI
|
||
DEEPSEEK_API_KEY=sk-xxx
|
||
DEEPSEEK_API_URL=https://api.deepseek.com/chat/completions
|
||
|
||
# CORS
|
||
CORS_ORIGIN=https://your-domain.com
|
||
```
|
||
|
||
#### 前端环境变量（client/.env）
|
||
|
||
```env
|
||
VITE_API_URL=https://your-domain.com/api
|
||
```
|
||
|
||
### 3. 部署方式
|
||
|
||
#### 方式一：腾讯云轻量应用服务器
|
||
|
||
1. **上传代码**
|
||
```bash
|
||
scp -r . user@your-server:/app/qia
|
||
```
|
||
|
||
2. **安装依赖并构建**
|
||
```bash
|
||
cd /app/qia
|
||
npm install
|
||
cd client && npm install && npm run build
|
||
cd ../server && npm install && npm run build
|
||
```
|
||
|
||
3. **配置PM2进程管理**
|
||
```bash
|
||
npm install -g pm2
|
||
pm2 start server/dist/index.js --name qia-server
|
||
pm2 startup
|
||
pm2 save
|
||
```
|
||
|
||
4. **配置Nginx反向代理**
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
|
||
# 前端静态文件
|
||
location / {
|
||
root /app/qia/client/dist;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# API代理
|
||
location /api {
|
||
proxy_pass http://localhost:3000;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection 'upgrade';
|
||
proxy_set_header Host $host;
|
||
proxy_cache_bypass $http_upgrade;
|
||
}
|
||
}
|
||
```
|
||
|
||
5. **配置HTTPS（Let's Encrypt）**
|
||
```bash
|
||
certbot --nginx -d your-domain.com
|
||
```
|
||
|
||
#### 方式二：Docker部署
|
||
|
||
创建 `Dockerfile`:
|
||
|
||
```dockerfile
|
||
# 构建前端
|
||
FROM node:18-alpine AS frontend
|
||
WORKDIR /app
|
||
COPY client/ ./client/
|
||
RUN cd client && npm install && npm run build
|
||
|
||
# 构建后端
|
||
FROM node:18-alpine AS backend
|
||
WORKDIR /app
|
||
COPY server/ ./server/
|
||
RUN cd server && npm install && npm run build
|
||
|
||
# 运行
|
||
FROM node:18-alpine
|
||
WORKDIR /app
|
||
COPY --from=backend /app/server/dist ./dist
|
||
COPY --from=frontend /app/client/dist ./public
|
||
EXPOSE 3000
|
||
CMD ["node", "dist/index.js"]
|
||
```
|
||
|
||
部署：
|
||
```bash
|
||
docker build -t qia-app .
|
||
docker run -d -p 3000:3000 --env-file server/.env qia-app
|
||
```
|
||
|
||
### 4. 数据库迁移（生产环境）
|
||
|
||
```bash
|
||
cd server
|
||
npx prisma migrate deploy
|
||
```
|
||
|
||
### 5. 验证部署
|
||
|
||
```bash
|
||
# 检查API健康
|
||
curl https://your-domain.com/api/health
|
||
|
||
# 检查前端
|
||
curl https://your-domain.com
|
||
```
|
||
|
||
---
|
||
|
||
## 配置说明
|
||
|
||
### 环境变量清单
|
||
|
||
| 变量名 | 必需 | 说明 |
|
||
|-------|------|------|
|
||
| `NODE_ENV` | 是 | production/development |
|
||
| `PORT` | 是 | 服务端口 |
|
||
| `DATABASE_URL` | 是 | 数据库连接字符串 |
|
||
| `JWT_SECRET` | 是 | JWT签名密钥（生产环境必须复杂） |
|
||
| `JWT_EXPIRES_IN` | 否 | JWT过期时间（默认7d） |
|
||
| `CORS_ORIGIN` | 是 | 允许的跨域来源 |
|
||
| `DEEPSEEK_API_KEY` | 否 | AI功能才需要 |
|
||
| `DEEPSEEK_API_URL` | 否 | AI功能才需要 |
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
qia/
|
||
├── client/ # 前端React应用
|
||
│ ├── src/
|
||
│ │ ├── components/ # 组件
|
||
│ │ ├── pages/ # 页面
|
||
│ │ ├── hooks/ # 自定义Hook
|
||
│ │ ├── stores/ # 状态管理
|
||
│ │ ├── types/ # 类型定义
|
||
│ │ └── utils/ # 工具函数
|
||
│ ├── public/ # 静态资源
|
||
│ └── dist/ # 构建产物
|
||
├── server/ # 后端Express应用
|
||
│ ├── src/
|
||
│ │ ├── routes/ # 路由
|
||
│ │ ├── middleware/ # 中间件
|
||
│ │ └── services/ # 服务层
|
||
│ ├── prisma/ # 数据库
|
||
│ │ └── schema.prisma
|
||
│ └── dist/ # 构建产物
|
||
├── docs/ # 文档
|
||
├── ui/ # Pencil设计文件
|
||
└── .github/workflows/ # CI/CD配置
|
||
```
|
||
|
||
### 常见问题
|
||
|
||
#### Q: 数据库连接失败
|
||
A: 检查 `DATABASE_URL` 格式是否正确，开发环境使用SQLite，生产环境使用PostgreSQL。
|
||
|
||
#### Q: 前端请求API报CORS错误
|
||
A: 在 `server/.env` 中正确配置 `CORS_ORIGIN` 为前端域名。
|
||
|
||
#### Q: JWT Token过期
|
||
A: 前端会自动使用Refresh Token刷新，如需手动刷新调用 `POST /api/auth/refresh`。
|
||
|
||
#### Q: 登录后页面不跳转
|
||
A: 检查 `localStorage` 中是否正确保存了Token，清理浏览器缓存后重试。
|
||
|
||
---
|
||
|
||
## 快速参考
|
||
|
||
### 开发启动
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
### 构建生产版本
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
### 运行测试
|
||
```bash
|
||
npm run test
|
||
```
|
||
|
||
### 数据库操作
|
||
```bash
|
||
# 开发迁移
|
||
npx prisma migrate dev
|
||
|
||
# 生产迁移
|
||
npx prisma migrate deploy
|
||
|
||
# 查看数据
|
||
npx prisma studio
|
||
```
|
||
|
||
### 版本发布
|
||
```bash
|
||
# 1. 更新CHANGELOG
|
||
# 2. 提交代码
|
||
git add .
|
||
git commit -m "release: v0.x.x"
|
||
git tag -a v0.x.x -m "v0.x.x: description"
|
||
|
||
# 3. 推送到远程
|
||
git push
|
||
git push origin v0.x.x
|
||
```
|