# 测试环境流程指南

> 测试必须按照以下环境顺序依次进行，每个环境通过后才能进入下一个环境。

## 测试环境流程

```
[1] 本机环境 ─── 通过 ──→ [2] 预发布环境 ─── 通过 ──→ [3] 生产环境
      │                        │                        │
      ↓ 失败                   ↓ 失败                   ↓ 失败
  修复并重测              回到步骤[1]              回到步骤[1]
```

## 项目环境配置表

| 项目 | 本机环境 | 预发布环境 | 生产环境 |
|------|---------|-----------|---------|
| ai-proj | localhost:3000/8080 | staging.ai.pipexerp.com | ai.pipexerp.com |
| coolbuy-paas | localhost | fnos 测试环境 | 39.106.88.83:8888 |
| coolbuy-platform | localhost | fnos 测试环境 | 生产服务器 |

## 第一阶段：本机测试环境

> ⚠️ **关键约束**：本机测试必须全部通过，才能部署到 staging 环境。

**测试内容**：
- 单元测试 - 测试单个函数/方法，Mock 外部依赖
- 集成测试 - 测试模块间交互，使用测试数据库
- 功能验证 - 验证功能逻辑正确性
- **前端截图验证** - 使用 chrome-dev MCP 截图确认 UI 显示正确

### 后端测试

```bash
# Go 后端单元测试
go test ./... -v

# 指定模块测试
go test ./backend/handlers/... -v
go test ./backend/services/... -v
```

### 前端截图验证（⚠️ 必须步骤）

> **重要**：前端改动必须通过截图验证，不能只测后端 API。这一步经常被忽略，导致功能未正确显示。

**验证流程**：

1. **确保本机服务运行**
   ```bash
   # 终端1：后端
   cd backend && go run main.go

   # 终端2：前端
   cd frontend && npm start
   ```

2. **使用 chrome-dev MCP 截图验证**
   ```python
   # 步骤1：导航到目标页面
   mcp__chrome-dev__navigate_page(url="http://localhost:3000/requirements/686")

   # 步骤2：等待页面加载完成（可选）
   mcp__chrome-dev__wait_for(selector=".requirement-detail")

   # 步骤3：截图
   mcp__chrome-dev__take_screenshot()

   # 步骤4：检查截图中功能是否正确显示
   # - 新增的列/字段是否显示
   # - 样式是否正确
   # - 数据是否正确渲染
   ```

3. **常见验证场景**
   | 改动类型 | 验证页面 | 检查项 |
   |---------|---------|--------|
   | 列表新增列 | 列表页面 | 新列是否显示、数据是否正确 |
   | 表单新增字段 | 表单页面 | 字段是否显示、能否正常输入 |
   | 样式调整 | 相关页面 | 样式是否生效、布局是否正确 |
   | 权限控制 | 相关页面 | 按钮/菜单是否正确显示/隐藏 |

4. **截图保存**
   - 截图应保存到测试任务文档中作为验证记录
   - 命名规范：`REQ-XXXXX-本机测试-功能名称.png`

### 前端截图验证示例

```
/req test REQ-20260125-0002

→ 检查代码评审... ✓ 已完成
→ 验证开发任务... ✓ 已完成

=== 本机测试阶段 ===

1. 后端单元测试
   → go test ./backend/handlers/requirement_handler_test.go -v
   → ✓ 3/3 测试通过

2. 前端截图验证
   → 启动 chrome-dev MCP...
   → 导航到: http://localhost:3000/requirements/687
   → 截图验证...
   → ✓ 任务ID列正确显示 (#5284 格式)
   → ✓ 列宽度和样式正确
   → 截图已保存

=== 本机测试通过 ===
→ 可以执行: /req deploy REQ-20260125-0002 --env staging
```

### 通过标准

- [ ] 所有后端单元测试通过
- [ ] **前端截图验证通过**（有前端改动时必须）
- [ ] 功能在本地环境正常运行
- [ ] 无控制台错误
- [ ] 截图已保存到测试文档

### 跳过前端验证

仅当改动不涉及前端时，可使用 `--backend-only` 参数：

```bash
/req test REQ-XXXXX --backend-only
```

## 第二阶段：预发布环境

**测试内容**：
- E2E 测试 - 测试完整用户流程
- 跨浏览器测试 - Chrome、Firefox、Safari
- 性能测试 - 页面加载时间、API 响应时间

**通过标准**：
- [ ] 功能在预发布环境正常运行
- [ ] 与生产环境配置一致
- [ ] 无跨环境兼容性问题

## 第三阶段：生产环境

**测试内容**：
- UAT 验收 - 用户验收测试
- 冒烟测试 - 核心功能快速验证
- 回归测试 - 确保未破坏现有功能

**通过标准**：
- [ ] 功能在生产环境正常运行
- [ ] 用户验收通过
- [ ] 无生产环境特有问题

## API 验证清单

```bash
# 1. 本机环境
curl -s "http://localhost:8080/api/v1/requirements?search=REQ-2026" \
  -H "Authorization: Bearer $TOKEN" | jq '.data | length'

# 2. 预发布环境
curl -s "https://staging.ai.pipexerp.com/api/v1/requirements?search=REQ-2026" \
  -H "X-API-Key: $SYNC_REMOTE_API_KEY" | jq '.data | length'

# 3. 生产环境
curl -s "https://ai.pipexerp.com/api/v1/requirements?search=REQ-2026" \
  -H "X-API-Key: $SYNC_REMOTE_API_KEY" | jq '.data | length'
```

## 测试失败处理

| 失败阶段 | 处理方式 |
|---------|---------|
| 本机测试 | 修复代码，重新运行本机测试 |
| 预发布测试 | 修复代码，重新从本机测试开始 |
| 生产环境测试 | 修复代码，重新从本机测试开始 |

> 任何阶段测试失败，修复后必须从本机测试环境重新开始。