# PRD - 元素定位功能优化

> **文档类型**: 产品需求文档
> **模块名称**: UI自动化测试 - 元素定位
> **版本**: v1.1
> **作者**: czj
> **日期**: 2026-08-03
> **状态**: 待评审

---

## 一、背景与目标

### 1.1 背景

当前元素定位功能已完成基础实现：
- ✅ 支持 Claude CLI 进行智能元素匹配
- ✅ 支持单个/批量获取定位
- ✅ 支持自动登录后获取定位

但在实际使用中发现以下问题：
1. **微前端页面加载慢**：会议列表等业务页面需要更长时间加载子应用
2. **元素提取时机不对**：当前只等待 3+3 秒，对于复杂页面元素提取不完整
3. **无页面预加载功能**：用户无法先确认页面元素是否存在

### 1.2 目标

优化元素定位功能，提升复杂页面的定位成功率：
- 微前端页面定位成功率提升至 80%+
- 支持用户自定义等待时间
- 支持等待特定元素出现后再提取
- 前端增加页面预览确认功能

---

## 二、用户故事

### US-1 页面加载等待配置

**作为** 自动化测试工程师
**我想要** 配置元素定位的页面加载等待时间
**以便于** 适配不同加载速度的页面

**验收标准**：
- 批量定位 API 支持传入 `page_load_timeout` 参数（默认 10000ms）
- 支持传入 `extra_wait_time` 参数（额外等待时间，默认 5000ms）
- 前端"获取定位"按钮支持展开配置面板设置等待时间

### US-2 等待特定元素出现

**作为** 自动化测试工程师
**我想要** 指定一个等待元素的选择器
**以便于** 确保页面关键内容加载完成后再提取元素

**验收标准**：
- API 支持 `wait_for_selector` 参数，传入 CSS 选择器
- 提取元素前先等待该选择器对应的元素出现
- 超时后继续执行，不阻塞流程
- 日志中记录等待结果

### US-3 页面预览确认

**作为** 自动化测试工程师
**我想要** 在获取定位前预览页面并确认元素存在
**以便于** 验证步骤描述与实际页面匹配

**验收标准**：
- 前端用例详情页增加"预览页面"按钮
- 点击后在新窗口打开目标页面（已登录状态）
- 用户可在预览窗口中确认元素是否存在
- 预览窗口支持截图标注功能（可选）

### US-4 元素提取重试机制

**作为** 系统
**我想要** 当元素提取为空时自动重试
**以便于** 应对页面加载慢的情况

**验收标准**：
- 当提取到 0 个元素时，等待 5 秒后重试
- 最多重试 2 次
- 日志中记录重试次数和结果
- 最终结果包含提取到的元素数量

---

## 三、功能需求

### 3.1 API 增强

#### 3.1.1 POST /api/element/locate-batch

**新增请求参数**：

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| page_load_timeout | int | 10000 | 页面加载超时时间（毫秒） |
| extra_wait_time | int | 5000 | 页面加载后额外等待时间（毫秒） |
| wait_for_selector | string | "" | 等待特定元素出现（CSS选择器） |
| retry_on_empty | bool | true | 元素为空时是否重试 |
| max_retries | int | 2 | 最大重试次数 |

**响应增加字段**：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| elements_extracted | int | 提取到的元素总数 |
| retries | int | 实际重试次数 |
| page_load_time | float | 页面加载耗时（秒） |

### 3.2 后端逻辑优化

#### 3.2.1 页面加载等待策略

```
1. 导航到目标页面（wait_until="domcontentloaded"）
2. 等待 page_load_timeout 毫秒
3. 如果有 wait_for_selector，等待该元素出现（最多 extra_wait_time 毫秒）
4. 检测 micro-app 容器，如果存在等待子应用加载
5. 提取元素
6. 如果元素为空且 retry_on_empty=true：
   a. 等待 5000 毫秒
   b. 重新提取
   c. 重复最多 max_retries 次
```

#### 3.2.2 微前端元素提取增强

- 支持 micro-app 的 shadow DOM 和普通 DOM 两种模式
- 支持 Element UI 等 UI 框架组件提取
- 增加元素去重逻辑（避免重复提取）

### 3.3 前端功能增强

#### 3.3.1 用例详情页增强

- 新增"预览页面"按钮
- 新增"获取定位"高级配置面板：
  - 页面加载超时时间
  - 额外等待时间
  - 等待特定元素选择器

#### 3.3.2 定位结果显示增强

- 显示提取到的元素总数
- 显示页面加载耗时
- 显示重试次数（如有）

---

## 四、非功能需求

### 4.1 性能要求

- 单个步骤定位耗时控制在 30 秒以内
- 批量定位 10 个步骤控制在 5 分钟以内

### 4.2 兼容性要求

- 支持 micro-app 微前端架构
- 支持 Element UI 等 Vue 组件库
- 支持 shadow DOM

### 4.3 日志要求

- 记录页面加载耗时
- 记录元素提取数量
- 记录重试次数和原因
- 记录 Claude CLI 匹配结果

---

## 五、验收标准

### 5.1 功能验收

| 场景 | 预期结果 |
|------|----------|
| 登录页面获取定位 | 8/8 步骤成功定位 |
| 会议列表页面获取定位 | 5/7 步骤成功定位（≥70%） |
| 配置等待时间 20 秒 | 页面加载等待 20 秒后再提取 |
| 配置等待特定元素 | 元素出现后再提取 |
| 元素为空时重试 | 自动重试最多 2 次 |

### 5.2 性能验收

| 指标 | 目标值 |
|------|--------|
| 简单页面定位耗时 | ≤30 秒/步骤 |
| 复杂页面定位耗时 | ≤45 秒/步骤 |
| 批量定位成功率 | ≥80% |

---

## 六、风险与依赖

### 6.1 风险

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 微前端子应用加载慢 | 元素提取不完整 | 增加重试机制和等待配置 |
| Claude CLI 响应慢 | 定位耗时增加 | 优化 prompt 减少 token 消耗 |

### 6.2 依赖

- 宿主机 Claude CLI 正常运行
- 目标页面可正常访问
- Playwright 浏览器环境正常

---

## 七、附录

### 7.1 相关文档

- `HANDOFF_UI自动化.md` - UI 自动化交接文档
- `backend/app/routers/element_locator.py` - 元素定位路由实现

### 7.2 术语表

| 术语 | 说明 |
|------|------|
| micro-app | 微前端框架，支持子应用嵌入 |
| shadow DOM | Web Components 技术，隔离 DOM 树 |
| Claude CLI | Claude Code 命令行工具 |

---

*本文档由 Claude Code 生成，遵循项目 PRD 文档规范*