diff --git a/docs/development-guide.md b/docs/development-guide.md new file mode 100644 index 0000000..642aa48 --- /dev/null +++ b/docs/development-guide.md @@ -0,0 +1,450 @@ +# 开发指南 + +本文档说明如何进行本地开发、测试和部署。 + +## 目录 + +- [环境要求](#环境要求) +- [本地开发](#本地开发) +- [测试](#测试) +- [部署](#部署) +- [配置说明](#配置说明) + +--- + +## 环境要求 + +### 必需软件 + +| 软件 | 版本 | 说明 | +|-----|------|------| +| 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 +``` diff --git a/docs/test-report.md b/docs/test-report.md index 6c34573..317fd69 100644 --- a/docs/test-report.md +++ b/docs/test-report.md @@ -1,4 +1,4 @@ -# P4提醒功能测试报告 +# 掐日子 (qia) 应用功能测试报告 ## 版本信息 - 测试版本：v0.5.0-alpha (P4阶段) @@ -6,8 +6,9 @@ - 测试环境： - 前端服务：http://localhost:5173 - 后端服务：http://localhost:3000 - - 测试用户：测试用户 - - 浏览器：自动化测试（Playwright MCP） + - 数据库：SQLite (dev.db) + - 测试用户：test2024@example.com + - 浏览器：Playwright MCP自动化测试 --- @@ -15,164 +16,212 @@ | 指标 | 数值 | |-----|------| -| 总用例数 | 8 | -| 通过 | 8 | +| 总用例数 | 17 | +| 通过 | 12 | | 失败 | 0 | -| 未执行 | 0 | -| 通过率 | 100% | -| 控制台错误 | 1 (已修复) | +| 未执行 | 3 | +| 阻塞 | 2 | +| 通过率 | 70.6% (已执行) | --- -## 详细测试用例 +## 一、用户认证流程测试 -### TC001: 提醒列表空状态显示 -| 项目 | 内容 | -|-----|------| -| 用例标题 | 验证提醒列表在无数据时正确显示空状态 | -| 前置条件 | 用户已登录，无提醒数据 | -| 测试步骤 | 1. 访问首页 http://localhost:5173
2. 查看提醒区域 | -| 预期结果 | 显示"暂无提醒"和"记得添加提醒事项哦"提示，以及"添加提醒"按钮 | -| 实际结果 | PASS - 空状态显示正确 | -| 测试人员 | QA | +### 1.1 注册功能 -### TC002: 添加提醒功能 -| 项目 | 内容 | -|-----|------| -| 用例标题 | 验证可以成功添加新提醒 | -| 前置条件 | 用户已登录 | -| 测试步骤 | 1. 点击"添加提醒"按钮
2. 填写标题"测试提醒"
3. 填写内容"测试提醒内容"
4. 选择日期
5. 点击"添加"按钮 | -| 预期结果 | 弹窗关闭，提醒列表显示新添加的提醒 | -| 实际结果 | PASS - 提醒成功添加并显示在"今天"分组中 | -| 测试人员 | QA | +| 用例ID | 用例标题 | 预期结果 | 实际结果 | 状态 | +|--------|---------|---------|---------|------| +| AUTH-001 | 邮箱注册 | 注册成功并跳转登录 | 注册成功，自动跳转登录页 | 通过 | +| AUTH-002 | 密码要求提示 | 显示密码复杂度要求 | 显示4项要求（8字符、大小写、数字） | 通过 | +| AUTH-003 | 重复邮箱注册 | 提示邮箱已注册 | 提示"注册失败" | 通过 | +| AUTH-004 | 无效邮箱格式 | 提示格式错误 | 未测试 | 未执行 | -### TC003: 提醒时间分组显示 -| 项目 | 内容 | -|-----|------| -| 用例标题 | 验证提醒按时间正确分组（今天/明天/本周/更久/已错过） | -| 前置条件 | 用户有多个不同时效的提醒 | -| 测试步骤 | 1. 添加不同日期的提醒
2. 查看分组显示 | -| 预期结果 | 提醒按今天、明天、本周、更久分组显示，各组显示数量徽章 | -| 实际结果 | PASS - 1月29日提醒显示在"今天"分组，带红色"今天"徽章 | -| 测试人员 | QA | +**发现问题**: +- 注册错误提示不明确，仅显示"注册失败"，应提示"邮箱已被注册" -### TC004: 提醒卡片显示内容 -| 项目 | 内容 | -|-----|------| -| 用例标题 | 验证提醒卡片正确显示标题、时间、内容预览 | -| 前置条件 | 已添加提醒 | -| 测试步骤 | 1. 查看提醒卡片 | -| 预期结果 | 显示：标题、日期时间图标+时间、内容预览（最多1行） | -| 实际结果 | PASS - 卡片显示完整：测试提醒、1月29日 08:00、测试提醒内容 | -| 测试人员 | QA | +### 1.2 登录功能 -### TC005: 提醒完成功能 -| 项目 | 内容 | -|-----|------| -| 用例标题 | 验证点击checkbox可以标记提醒为已完成 | -| 前置条件 | 有未完成的提醒 | -| 测试步骤 | 1. 点击提醒卡片上的checkbox | -| 预期结果 | 复选框选中，文字添加删除线，颜色变灰暗 | -| 实际结果 | PASS - checkbox点击后变为选中状态 | -| 测试人员 | QA | +| 用例ID | 用例标题 | 预期结果 | 实际结果 | 状态 | +|--------|---------|---------|---------|------| +| AUTH-005 | 正确账号密码登录 | 登录成功跳转首页 | 登录成功跳转到 /home | 通过 | +| AUTH-006 | 错误密码登录 | 提示密码错误 | 提示"登录失败" | 通过 | +| AUTH-007 | 未注册账号登录 | 提示账号不存在 | 提示"登录失败" | 通过 | -### TC006: 提醒卡片悬停交互 -| 项目 | 内容 | -|-----|------| -| 用例标题 | 验证鼠标悬停时显示快捷操作按钮 | -| 前置条件 | 有未完成的提醒 | -| 测试步骤 | 1. 鼠标悬停在提醒卡片上 | -| 预期结果 | 卡片上移2px，显示"完成"快速操作按钮和菜单按钮 | -| 实际结果 | PASS - 悬停时有上移效果和操作按钮 | -| 测试人员 | QA | +### 1.3 登录状态持久化 -### TC007: 提醒编辑/删除菜单 -| 项目 | 内容 | -|-----|------| -| 用例标题 | 验证点击菜单按钮可以编辑或删除提醒 | -| 前置条件 | 有提醒数据 | -| 测试步骤 | 1. 点击提醒卡片的菜单按钮
2. 查看菜单选项 | -| 预期结果 | 显示"编辑"和"删除"菜单项 | -| 实际结果 | PASS - 菜单显示"编辑"和"删除"选项 | -| 测试人员 | QA | +| 用例ID | 用例标题 | 预期结果 | 实际结果 | 状态 | +|--------|---------|---------|---------|------| +| AUTH-008 | 刷新页面保持登录 | 刷新后仍在首页 | API请求失败导致跳转登录页 | **阻塞** | -### TC008: 逾期提醒Alert提示 -| 项目 | 内容 | -|-----|------| -| 用例标题 | 验证已错过的提醒在红色Alert中显示 | -| 前置条件 | 有已过期的提醒 | -| 测试步骤 | 1. 添加一个过去日期的提醒
2. 查看列表显示 | -| 预期结果 | 在红色Alert中显示"已错过 X个"，列出逾期提醒 | -| 实际结果 | 未测试（时间关系）- 功能实现待验证 | -| 测试人员 | QA | +**问题描述**: +- 登录成功后，刷新页面时 API 请求失败（ERR_FAILED） +- 后端 API 直接测试正常（curl），说明服务正常 +- Playwright 浏览器环境中 CORS 或 fetch 凭证传递问题 + +### 1.4 退出功能 + +| 用例ID | 用例标题 | 预期结果 | 实际结果 | 状态 | +|--------|---------|---------|---------|------| +| AUTH-009 | 退出登录 | 清除token跳转登录页 | 未测试 | 未执行 | --- -## 发现的Bug及修复 +## 二、P4提醒功能测试 (已有测试报告) -### Bug001: DateInput日期处理错误 -| 项目 | 内容 | -|-----|------| -| 问题描述 | 添加事件时选择日期后提交，报错"TypeError: dateStr.toISOString is not a function" | -| 严重程度 | P1 | -| 发现场景 | 点击"添加提醒" → 选择日期 → 点击"添加" | -| 原因分析 | DateInput组件在某些情况下返回字符串而非Date对象 | -| 修复方案 | 在HomePage.tsx的handleSubmit中添加类型检查和转换 | -| 修复状态 | 已修复 | -| 修复文件 | client/src/pages/HomePage.tsx:87-95 | +根据之前的测试结果，P4提醒功能测试已全部通过： + +| 用例ID | 用例标题 | 状态 | +|--------|---------|------| +| TC001 | 提醒列表空状态显示 | 通过 | +| TC002 | 添加提醒功能 | 通过 | +| TC003 | 提醒时间分组显示 | 通过 | +| TC004 | 提醒卡片显示内容 | 通过 | +| TC005 | 提醒完成功能 | 通过 | +| TC006 | 提醒卡片悬停交互 | 通过 | +| TC007 | 提醒编辑/删除菜单 | 通过 | +| TC008 | 逾期提醒Alert提示 | 未测试 | + +--- + +## 三、依赖检查 + +| 用例ID | 检查项 | 预期结果 | 实际结果 | 状态 | +|--------|--------|---------|---------|------| +| DEP-001 | rehype-sanitize | 安装并正常工作 | 首次启动缺失，已安装修复 | 通过 | + +--- + +## 四、页面布局测试 + +| 用例ID | 用例标题 | 预期结果 | 实际结果 | 状态 | +|--------|---------|---------|---------|------| +| LAYOUT-001 | 三栏横向布局 | 左侧导航、中间主内容、右侧功能区 | 页面显示三栏结构 | 通过 | +| LAYOUT-002 | 独立滚动 | 各栏可独立滚动 | 预期功能，待验证 | 未执行 | +| LAYOUT-003 | 响应式适配 | 适配不同屏幕尺寸 | 未测试 | 未执行 | + +--- + +## 五、API 测试结果 + +使用 curl 对后端 API 进行了直接测试： + +| API 端点 | 方法 | 测试结果 | +|---------|------|---------| +| /health | GET | 正常 | +| /api/auth/login | POST | 正常 (返回用户信息和token) | +| /api/auth/register | POST | 正常 | + +--- + +## 六、发现的Bug及修复 + +### 已修复 + +| BugID | 问题描述 | 严重程度 | 修复状态 | +|-------|---------|---------|---------| +| BUG-001 | 缺少 rehype-sanitize 依赖 | P1 | 已修复 | +| BUG-002 | DateInput日期处理错误 | P1 | 已修复 | + +### 待修复 + +| BugID | 问题描述 | 严重程度 | 优先级 | +|-------|---------|---------|--------| +| BUG-003 | HTML标签嵌套错误 | 中 | P1 | +| BUG-004 | 登录后刷新页面API请求失败 | 高 | P0 | +| BUG-005 | 注册错误提示不明确 | 低 | P2 | + +### 控制台错误 -```typescript -// 修复代码 -const dateObj = formDate instanceof Date ? formDate : new Date(formDate as unknown as string); ``` +[ERROR] In HTML, %s cannot be a descendant of <%s> +[ERROR] <%s> cannot contain a nested <%s> +``` +此错误表示存在 HTML 标签嵌套不正确的问题。 --- -## 控制台错误检查 +## 七、功能模块待测试项 -| 级别 | 数量 | 说明 | -|-----|------|------| -| Error | 0 | 修复后无错误 | -| Warning | 2 | React DevTools提示，非问题 | +以下功能因登录状态持久化问题暂时无法完整测试： -### 遗留警告 -- React DevTools提示（不影响功能） +### 纪念日功能 +- [ ] 添加纪念日（农历日期支持） +- [ ] 编辑纪念日 +- [ ] 删除纪念日 +- [ ] 倒计时显示 + +### 便签功能 +- [ ] Markdown 编辑 +- [ ] 预览模式 +- [ ] 自动保存 +- [ ] 手动保存 + +### AI助手功能 +- [ ] 底部居中固定UI +- [ ] 发送消息 +- [ ] 错误反馈 --- -## 回归测试建议 +## 八、测试环境信息 -### 必测项（P0） -1. 提醒添加流程（纪念日/提醒） -2. 提醒完成checkbox功能 -3. 提醒分组显示（今天/明天/本周/更久/已错过） -4. 逾期提醒红色Alert显示 -5. 提醒编辑/删除功能 +### 软件版本 -### 建议测试场景 -1. 添加过去日期的提醒，验证"已错过"分组 -2. 添加明天/本周的提醒，验证分组正确 -3. 批量完成多个提醒 -4. 编辑已完成的提醒 +| 组件 | 版本 | +|------|------| +| Node.js | v22.18.0 | +| Vite | v7.3.1 | +| React | 19.2.0 | +| Express | 4.21.0 | +| Prisma | 5.22.0 | +| TypeScript | 5.9.3 | + +### 网络配置 + +- 前端开发服务器：localhost:5173 +- 后端API服务器：localhost:3000 +- CORS配置：允许 localhost:5173 --- -## 质量评估 +## 九、建议与下一步行动 -### 发布建议：可以发布 +### 立即行动 (P0) +1. 修复登录后刷新页面 API 请求失败问题 +2. 修复 HTML 标签嵌套错误 + +### 短期行动 (P1) +1. 完善用户注册错误提示 +2. 增加开发环境的速率限制白名单 +3. 完整测试纪念日、便签、AI助手功能 + +### 长期优化 +1. 增加自动化测试覆盖 +2. 配置 CI/CD 集成测试 +3. 建立性能基准测试 + +--- + +## 十、质量评估 + +### 发布建议：暂缓发布 ### 功能完整性 +- [x] 用户认证（登录/注册） - [x] 提醒CRUD功能 - [x] 时间分组显示 - [x] 逾期提醒处理 - [x] 完成标记功能 -- [x] 悬停交互效果 +- [ ] 纪念日功能（待完整测试） +- [ ] 便签功能（待完整测试） +- [ ] AI助手功能（待完整测试） -### 已知问题 -- 无P0/P1级别问题 +### 风险项 +- 登录持久化问题可能导致用户频繁掉线 +- HTML嵌套错误可能影响页面渲染 ### 测试结论 -P4提醒功能测试全部通过，核心功能正常运行，发现的DateInput类型问题已修复。建议发布v0.5.0-alpha版本。 +P4提醒功能测试已通过，但存在登录持久化和HTML嵌套两个需要修复的问题。建议修复后再发布新版本。 --- @@ -181,4 +230,9 @@ P4提醒功能测试全部通过，核心功能正常运行，发现的DateInput | 版本 | 日期 | 变更内容 | |-----|------|---------| | v0.4.0-alpha | 2026-01-29 | P3纪念日功能完成 | -| v0.5.0-alpha | 2026-01-29 | P4提醒功能完成 | +| v0.5.0-alpha | 2026-01-29 | P4提醒功能完成，修复DateInput类型错误 | + +--- + +*报告生成时间: 2026-01-29* +*测试执行人: QA Agent*