qia/docs/development-guide.md

开发指南

本文档说明如何进行本地开发、测试和部署。

目录

• 环境要求
• 本地开发
• 测试
• 部署
• 配置说明

---

环境要求

必需软件

软件	版本	说明
Node.js	>= 18	前端和后端运行环境
npm	>= 9	包管理器
Git	任意版本	版本控制
SQLite	3.x	本地数据库（开发环境）

可选软件

软件	版本	说明
PostgreSQL	14+	生产环境数据库
Playwright	最新版	浏览器自动化测试

---

本地开发

1. 克隆项目

git clone https://your-repo-url/qia.git
cd qia

2. 安装依赖

主项目

npm install

前端（client子模块）

cd client
npm install

后端（server子模块）

cd server
npm install

3. 数据库配置

开发环境（SQLite）

无需额外配置，SQLite文件会自动创建。

# server/.env
DATABASE_URL="file:./dev.db"

生产环境（PostgreSQL）

# server/.env
DATABASE_URL="postgresql://user:password@host:5432/qia"

4. 启动开发服务器

方式一：同时启动前后端

在主目录执行：

npm run dev

这会同时启动：

• 前端：http://localhost:5173
• 后端：http://localhost:3000

方式二：分别启动

终端1 - 启动后端

cd server
npm run dev

终端2 - 启动前端

cd client
npm run dev

5. 初始化数据库

首次启动时，Prisma会自动创建数据库并运行迁移：

cd server
npx prisma migrate dev --name init

如需重置数据库：

npx prisma migrate reset

---

测试

单元测试

# 运行所有单元测试
npm test

# 运行特定模块测试
npm run test:unit

# 监听模式运行测试
npm run test:watch

端到端测试（Playwright）

安装Playwright

# 在主目录安装
npm install -D @playwright/test

# 安装浏览器
npx playwright install chromium

运行E2E测试

# 运行所有E2E测试
npm run test:e2e

# 运行特定测试文件
npx playwright test tests/reminder.spec.ts

# 以UI模式运行（可交互）
npx playwright test --ui

使用Playwright MCP（推荐）

如果配置了Playwright MCP服务器，可以直接使用 MCP 工具进行测试：

# 启动开发服务器后，使用以下工具：
# - browser_navigate: 导航到页面
# - browser_snapshot: 获取页面快照
# - browser_click: 点击元素
# - browser_type: 输入文本
# - browser_take_screenshot: 截图

测试用例

测试用例文档位于 docs/test-cases.md，测试报告位于 docs/test-report.md。

测试数据库

使用独立的测试数据库避免污染开发数据：

# server/.env.test
DATABASE_URL="file:./test.db"

# 运行测试
npm run test:e2e

---

部署

1. 构建生产版本

前端构建

cd client
npm run build

构建产物位于 client/dist/

后端构建

cd server
npm run build

构建产物位于 server/dist/

2. 环境配置

生产环境变量（server/.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）

VITE_API_URL=https://your-domain.com/api

3. 部署方式

方式一：腾讯云轻量应用服务器

1. 上传代码

scp -r . user@your-server:/app/qia

2. 安装依赖并构建

cd /app/qia
npm install
cd client && npm install && npm run build
cd ../server && npm install && npm run build

3. 配置PM2进程管理

npm install -g pm2
pm2 start server/dist/index.js --name qia-server
pm2 startup
pm2 save

4. 配置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）

certbot --nginx -d your-domain.com

方式二：Docker部署

创建 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"]

部署：

docker build -t qia-app .
docker run -d -p 3000:3000 --env-file server/.env qia-app

4. 数据库迁移（生产环境）

cd server
npx prisma migrate deploy

5. 验证部署

# 检查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，清理浏览器缓存后重试。

---

快速参考

开发启动

npm run dev

构建生产版本

npm run build

运行测试

npm run test

数据库操作

# 开发迁移
npx prisma migrate dev

# 生产迁移
npx prisma migrate deploy

# 查看数据
npx prisma studio

版本发布

# 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