# 需求文档：批量执行后自动跳转任务监控页

> 生成时间：2026-08-21
> 关联文档：`HANDOFF_性能测试.md`、`_PRD_性能测试项目管理与批量执行.md`

---

## 1. 背景与动机

当前性能测试模块的批量执行流程存在以下问题：

1. **API 阻塞**：`POST /tasks/batch-run` 和 `POST /projects/{id}/run-all` 均为同步阻塞式 API，所有任务串行执行完毕后才返回响应，导致前端长时间无响应（可能数十秒甚至数分钟），用户体验极差。
2. **无监控跳转**：执行全部完成后，用户只能看到一个成功提示，无法直接跳转到监控页面查看每个任务的实时运行情况。
3. **批量进度仅靠进度条**：`ProjectDetail.vue` 的批量执行进度条只展示简单的计数信息，无法看到单个任务的 TPS、响应时间等详细指标。

**用户诉求**：点击「执行全部」后，能立即跳转到监控页面，实时查看每个任务的性能测试运行情况（TPS、响应时间、状态码、并发数等图表）。

---

## 2. 现状分析

### 2.1 当前批量执行调用链

```
ProjectDetail.vue:handleRunAll()
    ↓
runProjectAll(projectId)
    ↓
POST /api/performance/projects/{projectId}/run-all
    ↓
run_project_all() → batch_run_tasks() [同步阻塞，等待所有任务完成]
    ↓
返回 BatchRunResponse { message, batch_id, task_count, report_id }
    ↓
前端显示 ElMessage.success(res.message)
```

### 2.2 当前监控页（MonitorPanel.vue）

- 支持单任务实时监控（通过路由参数 `?taskId=xxx`）
- WebSocket 连接 `/api/performance/ws/{taskId}` 接收 `perf_snapshot` 数据
- ECharts 展示 TPS 趋势、响应时间、状态码分布、延迟与并发
- 不支持批量任务监控

### 2.3 当前批量进度 WebSocket（`/ws/batch-progress`）

- 已有 `perf_batch_progress` 消息类型，包含：`batch_id`、`project_id`、`current_index`、`total_count`、`current_task_id`、`current_task_name`、`current_status`、`success_count`、`fail_count`
- 但前端 ProjectDetail.vue 仅用此进度更新简单的进度条数字

---

## 3. 功能需求

### FR-1: 批量执行 API 改为非阻塞

| 属性 | 说明 |
|------|------|
| 优先级 | P0 |
| 描述 | `batch-run` 和 `run-all` API 收到请求后立即返回 `batch_id` 和 `task_ids`，在后台异步执行任务，不再阻塞等待 |

**接口变更**：

**Request**：无变化

**Response**：`BatchRunResponse` 新增 `task_ids` 字段

```json
{
  "message": "批量执行已启动",
  "batch_id": "batch_xxx",
  "task_count": 5,
  "task_ids": ["task_001", "task_002", "task_003", "task_004", "task_005"],
  "report_id": null
}
```

### FR-2: 新增批量执行详情 API

| 属性 | 说明 |
|------|------|
| 优先级 | P0 |
| 描述 | 新增 `GET /batch-details/{batch_id}` 接口，返回批量执行记录详情，含各任务的当前状态 |

**接口定义**：

```
GET /api/performance/batch-details/{batch_id}
```

**Response**：

```json
{
  "batch_id": "batch_xxx",
  "project_id": "proj_xxx",
  "status": "running",
  "total_count": 5,
  "success_count": 2,
  "fail_count": 0,
  "started_at": "2026-08-21T08:00:00",
  "tasks": [
    {
      "id": "task_001",
      "name": "会议预约接口1",
      "status": "completed",
      "actual_tps": 120.5,
      "avg_response_time": 85.3,
      "error_rate": 0.02,
      "actual_concurrency": 10,
      "duration_actual": 60.0
    },
    {
      "id": "task_002",
      "name": "会议预约接口2",
      "status": "running",
      "actual_tps": null,
      "avg_response_time": null,
      "error_rate": null,
      "actual_concurrency": null,
      "duration_actual": null
    },
    {
      "id": "task_003",
      "name": "会议预约接口3",
      "status": "pending",
      ...
    }
  ]
}
```

### FR-3: 新增批量监控页面

| 属性 | 说明 |
|------|------|
| 优先级 | P0 |
| 描述 | 新建 `BatchMonitor.vue` 页面，批量执行启动后自动跳转，展示所有任务的实时状态和当前任务的性能指标 |

**路由**：`/performance/batch-monitor?batchId=xxx&projectId=xxx`

**页面布局**：

```
┌─────────────────────────────────────────────────────────┐
│  批量执行监控 - 会议预约                                    │
│  进度：███░░░░░░░ 3/10  成功 2  失败 0  [返回项目]        │
├─────────────────────────────────────────────────────────┤
│  任务列表                                                │
│  ┌──┬────────────┬────────┬───────┬──────┬────────┐    │
│  │# │ 任务名称     │ 状态    │ TPS  │ 响应时间│ 操作    │    │
│  ├──┼────────────┼────────┼───────┼──────┼────────┤    │
│  │1 │ 会议预约-1  │ ✅完成  │120.5 │ 85ms │  查看报告│    │
│  │2 │ 会议预约-2  │ 🔄运行中│ 98.2 │102ms │  查看监控│    │
│  │3 │ 会议预约-3  │ ⏳等待中│  -   │  -   │     -  │    │
│  │4 │ 会议预约-4  │ ⏳等待中│  -   │  -   │     -  │    │
│  │5 │ 会议预约-5  │ ⏳等待中│  -   │  -   │     -  │    │
│  └──┴────────────┴────────┴───────┴──────┴────────┘    │
├─────────────────────────────────────────────────────────┤
│  当前任务实时指标（WebSocket）                              │
│  ┌──────┬──────┬──────┬──────┬──────┬──────┐           │
│  │TPS   │平均RT│请求数│错误率│峰值TPS│并发数│           │
│  │98.2  │102ms│ 2048 │ 0.1%│ 105.3│  10  │           │
│  └──────┴──────┴──────┴──────┴──────┴──────┘           │
│  ┌─────────────────────────────────────────┐           │
│  │        TPS 趋势图（ECharts）              │           │
│  └─────────────────────────────────────────┘           │
│  ┌─────────────────────────────────────────┐           │
│  │     响应时间趋势图（含 P95）               │           │
│  └─────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────┘
```

**核心功能**：

1. **顶部进度条**：复用 ProjectDetail.vue 的进度样式，展示总进度 / 成功 / 失败
2. **任务列表表格**：展示所有任务的当前状态，完成后显示 TPS / 响应时间等关键指标
3. **实时指标卡片**：复用 MonitorPanel.vue 的 6 个指标卡片（TPS / 平均RT / 总请求数 / 错误率 / 峰值TPS / 并发数）
4. **实时图表**：复用 MonitorPanel.vue 的 ECharts 图表（TPS 趋势 / 响应时间趋势 / 状态码分布 / 延迟图 / 并发数图）
5. **自动切换**：当前任务完成后自动切换 WebSocket 到下一个任务，无需用户手动操作
6. **自动跳转完成**：批量执行全部完成后，自动展示「查看合并报告」按钮

### FR-4: 前端执行全部按钮跳转

| 属性 | 说明 |
|------|------|
| 优先级 | P0 |
| 描述 | `ProjectDetail.vue` 和 `Projects.vue` 的「执行全部」按钮点击后，调用 API 获取 `batch_id` 和 `task_ids` 后立即跳转到批量监控页 |

**流程**：

```
用户点击「执行全部」
    ↓
前端调用 POST /api/performance/projects/{projectId}/run-all
    ↓
立即跳转 → /performance/batch-monitor?batchId={batch_id}&projectId={projectId}
    ↓
BatchMonitor 页面：
  1. 加载批量执行详情（GET /batch-details/{batch_id}）
  2. 连接批量进度 WebSocket（ws/batch-progress）获取全局进度
  3. 自动连接第一个 running 任务的监控 WebSocket（ws/{task_id}）
  4. 任务完成时自动切换到下一个任务的 WebSocket
  5. 全部完成后展示报告入口
```

### FR-5: 批量执行后台异步化

| 属性 | 说明 |
|------|------|
| 优先级 | P0 |
| 描述 | `batch_run_tasks()` 和 `run_project_all()` 改为 `asyncio.create_task()` 后台执行，API 立即返回 |

---

## 4. 非功能需求

| 类型 | 要求 |
|------|------|
| 性能 | 页面跳转延迟 < 500ms（API 响应 + 路由跳转） |
| 兼容性 | 支持 Chrome 90+ |
| 健壮性 | WebSocket 断开自动重连；后台任务异常不影响页面响应 |
| 回退兼容 | 旧版前端调用阻塞式 API 仍可正常等待结果（但新前端不再依赖此行为） |

---

## 5. 不在范围

- 批量执行中的任务取消/中断功能（后续迭代）
- 多个批量执行同时运行的管理（当前为串行，不支持并行批量）
- 移动端适配

---

## 6. 影响范围

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `backend/app/schemas/performance.py` | **MODIFY** | `BatchRunResponse` 新增 `task_ids` 字段 |
| `backend/app/routers/performance.py` | **MODIFY** | `batch_run_tasks`、`run_project_all` 改为后台异步；新增 `get_batch_details` 路由 |
| `backend/app/services/performance_service.py` | **MODIFY** | `batch_run_tasks` 改为后台执行模式 |
| `frontend/src/types/performance.ts` | **MODIFY** | `BatchRunResponse` 新增 `task_ids` 字段 |
| `frontend/src/api/performance.ts` | **MODIFY** | 新增 `getBatchDetails` API 函数 |
| `frontend/src/views/performance/BatchMonitor.vue` | **NEW** | 批量监控页面 |
| `frontend/src/views/performance/ProjectDetail.vue` | **MODIFY** | 「执行全部」和「批量执行」按钮跳转逻辑 |
| `frontend/src/views/performance/Projects.vue` | **MODIFY** | 「执行全部」按钮跳转逻辑 |
| `frontend/src/router/index.ts` | **MODIFY** | 新增 `batch-monitor` 路由 |

---

*本文档由 Claude Code 生成*
