# 本地开发环境集成测试方案设计

**日期**: 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 联系方式
- **负责人**: 张翔
- **角色**: 全栈质量保障与效能工程师
- **原则**: 质量是设计出来的，并通过自动化流水线保障