# PRD - 事务处理时间（Transaction Time）功能

> **文档版本**: v1.0
> **创建日期**: 2026-08-21
> **模块类型**: 性能测试 - 事务处理时间
> **优先级**: P1
> **关联 PRD**: `_PRD_性能测试模块需求文档.md`

---

## 一、背景与目标

### 1.1 背景

当前性能测试模块仅支持**单接口压测**：每个任务配置一个目标 URL，重复发送同一请求并统计吞吐量、响应时间等指标。但实际业务场景中，用户操作往往涉及**多步骤事务**，例如：

- **登录 → 查询 → 下单**：模拟用户完整购物流程
- **查询列表 → 点击详情 → 提交审核**：模拟审批流程
- **Token 获取 → 业务操作 → 结果确认**：带认证链的业务流程

这些场景需要测量**事务整体耗时**和**每个步骤的耗时分布**，而不仅仅是单个接口的响应时间。

### 1.2 目标

1. **多步骤事务建模**：支持在单个任务中配置多个步骤（Step），每个步骤独立配置 URL、Method、Headers、Body
2. **步骤间数据传递**：支持将上一个步骤的响应字段（如 token、id）作为后续步骤的输入
3. **事务时间统计**：记录每个步骤的耗时和总事务时间（Transaction Time）
4. **可视化报告**：在报告中展示事务时间瀑布图、各步骤耗时分布
5. **复用现有能力**：复用现有签名机制、断言验证、响应捕获、模板解析

---

## 二、功能范围

### 2.1 核心功能

| 功能 | 描述 | 优先级 |
|------|------|--------|
| 多步骤事务配置 | 任务中可配置 1~N 个步骤，每个步骤独立 URL/Method/Headers/Body | P0 |
| 步骤间数据传递 | 支持从某步骤的响应中提取字段，作为后续步骤的请求参数 | P0 |
| 事务执行引擎 | 按步骤顺序执行，每个步骤独立统计指标 | P0 |
| 事务时间报告 | 瀑布图展示各步骤耗时，汇总事务总耗时 | P0 |
| 已有单步任务兼容 | 已有单接口任务自动作为单步骤事务，无需修改 | P0 |

### 2.2 非功能需求

- 步骤间数据传递最大深度：10 层（避免循环引用）
- 事务超时：单个事务 60 秒（超过则中断该事务）
- 每步骤断言：复用现有断言规则，断言失败计入该步骤错误统计
- 事务级别的错误率：任何一个步骤失败，该事务标记为失败

---

## 三、详细需求

### 3.1 数据模型

#### 3.1.1 TransactionStep（事务步骤）

```json
{
  "name": "登录步骤",              // 步骤名称（用于报告展示）
  "url": "https://192.168.5.44/api/auth/login",
  "method": "POST",
  "headers": {                     // 步骤级请求头（与任务级合并）
    "Content-Type": "application/json"
  },
  "body": {                        // 步骤级请求体
    "username": "admin@xty",
    "password": "Ubains@13579",
    "captcha": "csba"
  },
  "body_template": {},             // 请求体模板（支持变量替换）
  "assertions": [],                // 步骤级断言
  "capture_rules": [               // 响应捕获规则（用于后续步骤引用）
    {
      "key": "accessToken",
      "json_path": "$.data.token"
    }
  ],
  "timeout": 30                    // 该步骤超时（秒）
}
```

#### 3.1.2 PerformanceTask 扩展

在现有 `PerformanceTask` 模型基础上增加 `steps` 字段：

```python
steps: Optional[list]  # 事务步骤列表，为 None 时按单步骤处理（向后兼容）
```

- `steps` 为 `None` 或空列表 → 按现有单接口模式执行（兼容旧数据）
- `steps` 有值 → 按多步骤事务模式执行，覆盖 `target_url`/`method`/`headers`/`body`/`body_template`/`assertions`/`capture_rules` 等任务级配置

#### 3.1.3 TransactionStepResult（事务步骤结果）

```python
class TransactionStepResult:
    step_name: str          # 步骤名称
    step_index: int         # 步骤序号（从0开始）
    status: int             # HTTP 状态码（0=网络异常）
    success: bool           # 是否成功（断言通过）
    elapsed_ms: float       # 该步骤耗时（ms）
    latency_ms: float       # 首字节延迟（ms）
    connect_ms: float       # 连接时间（ms）
    sent_bytes: int         # 发送字节数
    received_bytes: int     # 接收字节数
    error_message: str      # 错误信息
    captured: dict          # 该步骤捕获的响应字段
```

#### 3.1.4 事务快照扩展

现有 `PerformanceSnapshot` 模型增加字段：

```python
transaction_elapsed: float  # 当前事务已耗时（ms），用于事务级别监控
```

### 3.2 事务执行引擎

#### 3.2.1 架构设计

```
TransactionExecutor
├── 步骤协调器（StepCoordinator）
│   ├── 按顺序执行步骤
│   ├── 步骤间数据传递（captured 变量解析）
│   └── 事务超时控制
├── 每个步骤独立执行
│   ├── HttpClient（复用现有实现）
│   ├── 断言验证（复用现有 ResultValidator）
│   └── 响应捕获（复用现有 capture_rules）
└── MetricsCollector（扩展）
    ├── 每步骤指标采集
    ├── 事务级指标汇总
    └── 事务时间瀑布图数据
```

#### 3.2.2 执行流程

```
1. 判断 task.steps 是否有值
   └── 无 → 走现有单接口执行流程（兼容模式）
   └── 有 → 走事务执行流程

2. 事务执行流程：
   a. 初始化事务上下文（shared_context = {}）
   b. 循环执行每个步骤：
      i.   解析步骤 URL/Body：替换 {{captured.key}} 为 shared_context[key]
      ii.  发送 HTTP 请求
      iii. 记录该步骤耗时
      iv.  执行断言验证
      v.   执行响应捕获，将结果写入 shared_context
      vi.  若步骤失败，记录错误但继续执行（可选配置：失败即终止）
      vii. 进入下一个步骤
   c. 汇总事务指标：
      - 总事务时间 = 各步骤 elapsed_ms 之和
      - 各步骤耗时分布
      - 事务成功率（所有步骤成功 = 成功）
   d. 将事务时间指标写入快照数据

3. 多个并发事务：
   - 每个虚拟用户（协程）独立维护 shared_context
   - 事务间互不干扰
```

#### 3.2.3 变量解析规则

在步骤 URL 和 Body 中支持 `{{captured.key}}` 语法：

```json
// 步骤1 登录成功后捕获了 token
{
  "capture_rules": [
    { "key": "token", "json_path": "$.data.token" }
  ]
}

// 步骤2 使用步骤1的 token
{
  "url": "https://192.168.5.44/api/device/list?token={{captured.token}}",
  "body": {
    "device_id": "{{captured.deviceId}}"
  }
}
```

变量解析优先级：
1. `captured.{key}` — 上一个步骤捕获的响应字段
2. `__INDEX__` — 内建变量（请求序号）
3. `account.{field}` — 登录账号字段

#### 3.2.4 事务模式配置

在任务创建/编辑界面增加配置项：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| 事务模式 | 单接口 / 多步骤事务 | 单接口 |
| 步骤列表 | 事务步骤配置列表 | [] |
| 失败策略 | 失败即终止 / 继续执行后续步骤 | 失败即终止 |
| 事务超时 | 单个事务最大耗时（秒） | 60 |

### 3.3 报告展示

#### 3.3.1 事务时间瀑布图

在报告页面新增「事务时间 Transaction Time」区块：

- **瀑布图（Waterfall Chart）**：展示各步骤耗时，按顺序堆叠
  - X 轴：耗时（ms）
  - Y 轴：步骤名称
  - 每个步骤显示：耗时、状态码、成功/失败标识
- **汇总表格**：
  | 步骤 | 方法 | URL | 耗时 | 状态码 | 成功 | 错误信息 |
  |------|------|-----|------|--------|------|---------|
  | 登录步骤 | POST | /api/auth/login | 245ms | 200 | ✅ | - |
  | 查询设备 | GET | /api/device/list | 180ms | 200 | ✅ | - |
  | 提交订单 | POST | /api/order/create | 520ms | 500 | ❌ | 库存不足 |
  | **事务总计** | | | **945ms** | | ❌ | |

#### 3.3.2 事务时间趋势

在实时监控页增加「事务时间趋势」图表，展示随时间变化的事务耗时分布（P50/P90/P95）。

### 3.4 前端页面变更

#### 3.4.1 任务创建/编辑弹窗

在现有 `TaskList.vue` 的创建/编辑弹窗中增加：

- 模式切换：单接口 / 多步骤事务
- 步骤列表编辑器（可添加/删除/排序步骤）
- 每个步骤的配置：
  - 步骤名称输入框
  - URL 输入框
  - Method 下拉选择
  - Headers 编辑器（KV 输入）
  - Body 编辑器（JSON 输入）
  - 断言配置（复用现有断言组件）
  - 响应捕获配置（KV + JSONPath）
- 拖拽排序支持

#### 3.4.2 报告页面

在 `ReportPanel.vue` 中增加：

- 事务模式标识
- 事务时间瀑布图
- 各步骤耗时明细表
- 事务级 vs 请求级指标切换

#### 3.4.3 实时监控页面

在 `MonitorPanel.vue` 中增加：

- 事务时间趋势图（可选，默认隐藏）
- 当前事务步骤进度指示器

---

## 四、现有资产复用

| 现有资产 | 用途 | 复用方式 |
|---------|------|---------|
| `HttpClient` | 登录获取 Token、请求签名 | 直接复用，不修改 |
| `ResultValidator` | 断言验证 | 直接复用，步骤级使用 |
| `capture_rules` / `_captured` | 响应字段捕获 | 扩展为步骤间传递 |
| `TemplateResolver` | 模板变量解析 | 扩展支持 `{{captured.key}}` |
| `MetricsCollector` | 指标采集 | 扩展事务级统计 |
| `PerformanceSnapshot` | 快照存储 | 增加事务时间字段 |
| `ReportPanel.vue` | 报告展示 | 增加事务时间瀑布图 |

---

## 五、风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 步骤间依赖导致整体失败率上升 | 事务成功率降低 | 明确失败策略配置，区分步骤级错误和事务级错误 |
| 事务超时导致资源占用 | 并发数下降 | 严格的事务超时控制，超时自动释放资源 |
| 复杂事务配置困难 | 用户体验差 | 提供模板/预设，支持从已有单接口任务快速创建 |
| 向后兼容性 | 已有任务无法使用 | steps 为 None 时自动走单接口模式，无需迁移 |

---

## 六、与现有能力的对比

| 维度 | 现有（单接口） | 新增（事务时间） |
|------|---------------|----------------|
| 请求目标 | 1 个 URL | N 个步骤，每个独立 URL |
| 指标粒度 | 单请求响应时间 | 每步骤耗时 + 事务总耗时 |
| 数据传递 | 无 | 步骤间响应字段传递 |
| 报告展示 | TPS/响应时间趋势 | 瀑布图 + 步骤耗时明细 |
| 适用场景 | 单接口高并发压测 | 多步骤业务流程压测 |

---

## 七、附录

### 7.1 数据流图

```
创建多步骤任务
    ↓
任务列表展示（标记为「事务」类型）
    ↓
执行引擎判断 steps 有值
    ↓
事务执行循环：
  Step 1: 登录 → 捕获 token
  Step 2: 查询列表 → 使用 token → 捕获 deviceId
  Step 3: 提交订单 → 使用 token + deviceId
    ↓
指标汇总：每步骤耗时 + 事务总耗时
    ↓
报告展示：瀑布图 + 步骤明细表
```

### 7.2 后端 API 变更

| 接口 | 变更类型 | 说明 |
|------|---------|------|
| POST /api/performance/tasks | 扩展 | TaskCreate schema 增加 steps 字段 |
| PUT /api/performance/tasks/{id} | 扩展 | TaskUpdate schema 增加 steps 字段 |
| GET /api/performance/tasks/{id} | 无变更 | to_dict() 已包含 steps |
| GET /api/performance/report/{taskId} | 扩展 | 返回数据增加 transaction_time 字段 |

### 7.3 前端 API 变更

| 文件 | 变更说明 |
|------|---------|
| `frontend/src/types/performance.ts` | 增加 TransactionStep 类型定义 |
| `frontend/src/api/performance.ts` | 无变更（现有 CRUD 接口已支持 steps 字段） |

---

*本文档为事务处理时间功能的需求定义，后续将输出计划执行文档用于指导开发。*