novalon/gym-manage
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
gym-manage/docs/superpowers/specs/2026-04-15-local-dev-testing-design.md
T

260 lines
9.9 KiB
Markdown
Raw Permalink Blame History

# 本地开发环境集成测试方案设计
**日期**: 2026-04-15
**作者**: 张翔 (全栈质量保障与效能工程师)
**版本**: 1.0
## 1. 任务概述
### 1.1 目标
启动前后端系统（包含网关服务），确保前后端联通，在开发环境中使用已有的测试框架进行用户旅程测试。数据库部署在Docker中，应用直接在开发环境中运行。
### 1.2 成功标准
1. ✅ 数据库在Docker中成功启动并初始化
2. ✅ 后端网关和应用服务在本地成功启动
3. ✅ 前端应用在本地成功启动并连接到后端
4. ✅ 用户旅程测试（E2E测试）成功执行
5. ✅ 所有服务健康状态正常
## 2. 技术架构
### 2.1 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ 本地开发环境 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Vue 3 │ │ Spring Cloud│ │ Spring Boot │ │
│ │ 前端应用 │◄──►│ Gateway │◄──►│ 应用服务 │ │
│ │ (端口:3000)│ │ (端口:8080)│ │ (端口:8084) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ▲ ▲ ▲ │
│ │ │ │ │
│ └─────────────────────────┴───────────────┘ │
│ HTTP/REST API 通信 │
├─────────────────────────────────────────────────────────────┤
│ Docker容器环境 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────┐ │
│ │ PostgreSQL 15数据库 │ │
│ │ (端口:55432) │ │
│ │ Flyway自动迁移 │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 技术栈
- **后端**: Java 21 + Spring Boot 3.5.13 + Spring Cloud Gateway
- **前端**: Vue 3 + TypeScript + Vite + Element Plus
- **数据库**: PostgreSQL 15 (Docker容器)
- **测试框架**: Playwright (E2E测试)
- **构建工具**: Maven (后端) + pnpm/npm (前端)
## 3. 配置方案
### 3.1 数据库配置
- **容器服务**: PostgreSQL 15 (postgres:15-alpine)
- **端口映射**: 55432:5432 (避免与本地PostgreSQL冲突)
- **数据库名称**: manage_system
- **认证信息**: novalon/novalon123
- **数据卷**: postgres_data (持久化存储)
- **健康检查**: pg_isready命令验证
### 3.2 后端服务配置
- **网关服务**:
- 端口: 8080
- 路由配置: /api/** → localhost:8084
- 过滤器: JWT认证、RBAC授权、重试机制
- **应用服务**:
- 端口: 8084
- 数据库连接: r2dbc:postgresql://localhost:55432/manage_system
- 健康检查: /actuator/health端点
- **启动方式**: Maven多模块同时启动
### 3.3 前端服务配置
- **开发服务器**: Vite (端口:3000)
- **API代理**: 配置代理到网关服务 (localhost:8080)
- **环境变量**: 使用开发环境配置
- **构建工具**: pnpm (推荐) 或 npm
### 3.4 测试配置
- **测试框架**: Playwright
- **测试范围**: 冒烟测试 (login-logout.spec.ts)
- **测试数据**:
- 管理员账号: admin/Test@123
- 普通用户账号: user/Test@123
- **测试环境**: 连接到本地运行的服务
## 4. 实施步骤
### 4.1 阶段一：数据库容器启动
```bash
# 1. 启动PostgreSQL容器
docker-compose up -d postgres
# 2. 等待数据库就绪 (10秒)
sleep 10
# 3. 验证数据库连接
docker-compose exec postgres pg_isready -U novalon -d manage_system
```
### 4.2 阶段二：后端服务启动
```bash
# 1. 进入后端项目目录
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-api
# 2. 使用Maven同时启动网关和应用
mvn spring-boot:run -pl manage-gateway,manage-app -am
```
### 4.3 阶段三：前端服务启动
```bash
# 1. 进入前端项目目录
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-web
# 2. 安装依赖 (如果未安装)
pnpm install # 或 npm install
# 3. 启动开发服务器
pnpm run dev # 或 npm run dev
```
### 4.4 阶段四：执行E2E测试
```bash
# 1. 在另一个终端执行冒烟测试
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-web
pnpm run test:e2e:smoke # 或 npm run test:e2e:smoke
```
## 5. 验证检查点
### 5.1 数据库验证
- [ ] PostgreSQL容器运行状态正常 (`docker-compose ps`)
- [ ] 数据库端口55432可访问 (`telnet localhost 55432`)
- [ ] Flyway迁移脚本执行成功 (查看应用日志)
### 5.2 后端验证
- [ ] 网关服务在8080端口响应 (`curl http://localhost:8080/actuator/health`)
- [ ] 应用服务在8084端口响应 (`curl http://localhost:8084/actuator/health`)
- [ ] 健康检查端点返回UP状态
- [ ] 网关能正确路由到应用服务
### 5.3 前端验证
- [ ] 开发服务器在3000端口运行 (`curl http://localhost:3000`)
- [ ] 页面能正常加载 (浏览器访问 http://localhost:3000)
- [ ] API请求能正确代理到后端
### 5.4 测试验证
- [ ] 冒烟测试执行通过
- [ ] 登录登出流程正常
- [ ] 测试报告生成成功
## 6. 故障排除预案
### 6.1 常见问题及解决方案
#### 问题1：端口冲突
- **症状**: 服务启动失败，提示端口被占用
- **解决方案**:
1. 检查8080、8084、55432端口是否被占用: `lsof -i :8080`
2. 停止占用端口的进程或修改配置使用其他端口
3. 修改application.yml中的端口配置
#### 问题2：数据库连接失败
- **症状**: 应用启动时报数据库连接错误
- **解决方案**:
1. 验证Docker容器状态: `docker-compose ps`
2. 检查数据库日志: `docker-compose logs postgres`
3. 验证网络连接: `telnet localhost 55432`
4. 检查数据库认证信息配置
#### 问题3：服务启动失败
- **症状**: Maven启动时报依赖或配置错误
- **解决方案**:
1. 清理Maven缓存: `mvn clean`
2. 重新下载依赖: `mvn dependency:resolve`
3. 检查Spring配置文件和环境变量
4. 查看详细错误日志
#### 问题4：测试失败
- **症状**: Playwright测试执行失败
- **解决方案**:
1. 验证测试环境服务是否正常运行
2. 检查测试数据是否正确
3. 查看测试失败截图和日志
4. 运行调试模式: `pnpm run test:e2e:debug`
### 6.2 回滚方案
1. **停止所有服务**:
```bash
# 停止Docker容器
docker-compose down
# 停止Maven进程 (Ctrl+C)
# 停止npm进程 (Ctrl+C)
```
2. **清理临时文件**:
```bash
# 清理Maven构建目录
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-api
mvn clean
# 清理前端缓存
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-web
rm -rf node_modules/.vite
```
3. **重新执行**:
按照4.1-4.4步骤重新执行
## 7. 监控与日志
### 7.1 服务监控
- **数据库**: `docker-compose logs -f postgres`
- **后端应用**: Maven控制台输出 + 应用日志
- **前端**: Vite开发服务器控制台输出
- **测试**: Playwright测试报告和控制台输出
### 7.2 关键指标
- 服务启动时间
- API响应时间
- 数据库连接状态
- 测试执行成功率
- 资源使用情况 (CPU/内存)
## 8. 后续优化建议
### 8.1 短期优化
1. **自动化脚本**: 创建一键启动脚本，简化操作流程
2. **环境配置**: 完善本地开发环境配置文件
3. **测试数据**: 优化测试数据管理，支持数据重置
### 8.2 中期优化
1. **容器化开发环境**: 考虑使用DevContainer统一开发环境
2. **测试覆盖率**: 增加更多E2E测试场景
3. **性能监控**: 集成APM工具监控应用性能
### 8.3 长期优化
1. **CI/CD集成**: 将本地测试流程集成到CI/CD流水线
2. **多环境支持**: 支持开发、测试、预发、生产多环境
3. **安全加固**: 加强安全测试和漏洞扫描
## 9. 附录
### 9.1 配置文件位置
- 数据库配置: `docker-compose.yml`
- 后端配置: `novalon-manage-api/manage-*/src/main/resources/application*.yml`
- 前端配置: `novalon-manage-web/.env*`, `vite.config.ts`
- 测试配置: `novalon-manage-web/playwright.config.ts`
### 9.2 相关文档
- 项目README: `/Users/zhangxiang/Codes/Novalon/novalon-manage-system/README.md`
- E2E测试说明: `novalon-manage-web/e2e/README.md`
- API文档: `http://localhost:8084/swagger-ui.html` (启动后访问)
### 9.3 联系方式
- **负责人**: 张翔
- **角色**: 全栈质量保障与效能工程师
- **原则**: 质量是设计出来的，并通过自动化流水线保障
Reference in New Issue View Git Blame Copy Permalink