novalon-manage-system/docs/superpowers/specs/2026-04-15-local-dev-testing-design.md

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

日期: 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 阶段一：数据库容器启动

# 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 阶段二：后端服务启动

# 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 阶段三：前端服务启动

# 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测试

# 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. 停止所有服务:

   # 停止Docker容器
   docker-compose down
   
   # 停止Maven进程 (Ctrl+C)
   # 停止npm进程 (Ctrl+C)
   

2. 清理临时文件:

   # 清理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 联系方式

• 负责人: 张翔
• 角色: 全栈质量保障与效能工程师
• 原则: 质量是设计出来的，并通过自动化流水线保障