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

9.9 KiB
Raw 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 阶段一：数据库容器启动

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

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