# 开发指南

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

## 目录

- [环境要求](#环境要求)
- [本地开发](#本地开发)
- [测试](#测试)
- [部署](#部署)
- [配置说明](#配置说明)

---

## 环境要求

### 必需软件

| 软件 | 版本 | 说明 |
|-----|------|------|
| 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
```