# 执行计划 - 元素定位功能优化

> **文档类型**: 计划执行文档
> **关联 PRD**: `_PRD_元素定位功能优化.md`
> **版本**: v1.0
> **作者**: czj
> **日期**: 2026-08-03
> **预计工期**: 2 天

---

## 一、执行概览

### 1.1 目标

优化元素定位功能，提升复杂页面（特别是微前端页面）的定位成功率。

### 1.2 范围

- 后端 API 参数增强
- 页面加载等待策略优化
- 微前端元素提取增强
- 前端配置面板开发
- 重试机制实现

### 1.3 排除

- 前端截图标注功能（可选，暂不实现）
- 性能监控大盘

---

## 二、技术方案

### 2.1 架构设计

```
前端（Vue 3）
  ├── Cases.vue - 用例详情页
  │   ├── 预览页面按钮
  │   └── 获取定位配置面板
  │
  └── api/elementLocate.ts - API 调用

后端（FastAPI）
  └── routers/element_locator.py
      ├── locate_batch() - 批量定位 API（增强参数）
      ├── _do_locate_with_executor() - 页面加载等待策略
      └── extract_interactive_elements() - 元素提取（增强）
```

### 2.2 数据流

```
用户点击"获取定位"
  → 弹出配置面板（可选）
  → 调用 POST /api/element/locate-batch
    → Playwright 导航到页面
    → 等待页面加载（可配置时间）
    → 等待特定元素（可选）
    → 检测 micro-app，等待子应用
    → 提取元素（增强）
    → 元素为空则重试
    → Claude CLI 匹配
  → 返回结果（含元素数量、耗时、重试次数）
  → 前端显示结果
```

---

## 三、分阶段实施

### Phase 1: 后端 API 增强（Day 1 上午）

**目标**: 增强批量定位 API，支持配置参数和重试机制

**任务清单**:

| # | 任务 | 文件 | 预计耗时 |
|---|------|------|----------|
| 1.1 | 更新 BatchLocateRequest schema，新增参数 | `backend/app/routers/element_locator.py` | 15min |
| 1.2 | 更新 BatchLocateResponse schema，新增响应字段 | `backend/app/routers/element_locator.py` | 10min |
| 1.3 | 实现 _do_locate_with_executor 增强等待策略 | `backend/app/routers/element_locator.py` | 30min |
| 1.4 | 实现元素提取重试机制 | `backend/app/routers/element_locator.py` | 20min |
| 1.5 | 记录页面加载耗时、元素数量到日志 | `backend/app/routers/element_locator.py` | 15min |

**关键代码**:

```python
# Schema 更新
class BatchLocateRequest(BaseModel):
    case_id: str
    page_url: str = "https://192.168.5.44"
    auto_login: bool = True
    page_load_timeout: int = 10000  # 新增
    extra_wait_time: int = 5000    # 新增
    wait_for_selector: str = ""    # 新增
    retry_on_empty: bool = True    # 新增
    max_retries: int = 2           # 新增

class BatchLocateResponse(BaseModel):
    success: bool
    case_id: str
    total_steps: int
    located_steps: int
    results: List[StepLocateResult]
    message: str
    elements_extracted: int = 0    # 新增
    retries: int = 0               # 新增
    page_load_time: float = 0.0    # 新增
```

**验证方式**:
- 调用 API 测试新参数是否生效
- 检查日志是否记录耗时和元素数量

---

### Phase 2: 微前端元素提取增强（Day 1 下午）

**目标**: 增强元素提取逻辑，提高微前端页面提取率

**任务清单**:

| # | 任务 | 文件 | 预计耗时 |
|---|------|------|----------|
| 2.1 | 优化 extract_interactive_elements 函数 | `backend/app/routers/element_locator.py` | 45min |
| 2.2 | 增加元素去重逻辑 | `backend/app/routers/element_locator.py` | 15min |
| 2.3 | 支持 Element UI 组件提取 | `backend/app/routers/element_locator.py` | 20min |
| 2.4 | 单元测试：元素提取函数 | `backend/tests/test_element_extractor.py` | 30min |

**关键代码**:

```javascript
// 增强的元素提取 JS
function extractInteractiveElements() {
    const elements = [];
    const seen = new Set();

    // 1. 主文档元素
    // 2. micro-app 微前端（shadow DOM + 普通 DOM）
    // 3. iframe 内容
    // 4. Element UI 组件（.el-input__inner 等）
    // 5. 去重逻辑

    return elements;
}
```

**验证方式**:
- 访问会议列表页面，验证元素提取数量
- 对比优化前后的提取结果

---

### Phase 3: 前端配置面板（Day 2 上午）

**目标**: 前端增加获取定位配置面板和预览功能

**任务清单**:

| # | 任务 | 文件 | 预计耗时 |
|---|------|------|----------|
| 3.1 | Cases.vue 增加配置面板组件 | `frontend/src/views/Cases.vue` | 40min |
| 3.2 | 实现配置参数传递到 API | `frontend/src/views/Cases.vue` | 20min |
| 3.3 | 增加"预览页面"按钮 | `frontend/src/views/Cases.vue` | 20min |
| 3.4 | 优化定位结果显示（元素数量、耗时） | `frontend/src/views/Cases.vue` | 30min |
| 3.5 | 样式优化 | `frontend/src/views/Cases.vue` | 15min |

**UI 设计**:

```
┌─────────────────────────────────────────┐
│ 批量获取定位                              │
├─────────────────────────────────────────┤
│ ⚙️ 高级配置                              │
│ ┌─────────────────────────────────────┐ │
│ │ 页面加载超时: [10000] ms             │ │
│ │ 额外等待时间: [5000] ms              │ │
│ │ 等待特定元素: [________________]     │ │
│ │ (可选，CSS 选择器)                   │ │
│ └─────────────────────────────────────┘ │
│                                          │
│ [预览页面]  [开始获取]  [取消]            │
└─────────────────────────────────────────┘
```

**验证方式**:
- 前端配置面板正常显示
- 参数正确传递到后端
- 预览页面正常打开

---

### Phase 4: 集成测试与部署（Day 2 下午）

**目标**: 验证完整流程，部署到服务器

**任务清单**:

| # | 任务 | 预计耗时 |
|---|------|----------|
| 4.1 | 本地测试：登录页面定位 | 15min |
| 4.2 | 本地测试：会议列表页面定位 | 15min |
| 4.3 | 本地测试：配置参数生效验证 | 15min |
| 4.4 | 前端构建 | 10min |
| 4.5 | 部署到 192.168.5.60 | 20min |
| 4.6 | 服务器验证 | 20min |
| 4.7 | 更新交接文档 | 15min |

**验证清单**:

| 场景 | 预期结果 | 实际结果 |
|------|----------|----------|
| 登录页面获取定位 | 8/8 成功 | 待验证 |
| 会议列表获取定位 | ≥5/7 成功 | 待验证 |
| 配置等待时间 20s | 等待时间生效 | 待验证 |
| 元素为空重试 | 重试 1-2 次 | 待验证 |

---

## 四、文件清单

### 4.1 新增文件

| 文件 | 说明 |
|------|------|
| `backend/tests/test_element_extractor.py` | 元素提取单元测试 |

### 4.2 修改文件

| 文件 | 修改内容 |
|------|----------|
| `backend/app/routers/element_locator.py` | API 增强、等待策略、元素提取优化 |
| `frontend/src/views/Cases.vue` | 配置面板、预览功能 |
| `frontend/src/api/elementLocate.ts` | API 参数更新 |
| `HANDOFF_UI自动化.md` | 更新交接文档 |

---

## 五、风险评估

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| 微前端页面仍无法提取足够元素 | 中 | 高 | 增加手动输入选择器功能 |
| Claude CLI 响应超时 | 低 | 中 | 增加超时配置和降级策略 |
| 前端配置面板开发超时 | 低 | 低 | 简化 UI，核心功能优先 |

---

## 六、交付物

### 6.1 代码交付

- [ ] `backend/app/routers/element_locator.py` - API 增强
- [ ] `frontend/src/views/Cases.vue` - 前端配置面板
- [ ] `frontend/src/api/elementLocate.ts` - API 参数更新
- [ ] `backend/tests/test_element_extractor.py` - 单元测试

### 6.2 文档交付

- [ ] `Docs/PRD/需求文档/用例管理/_PRD_元素定位功能优化.md` - 需求文档
- [ ] `Docs/PRD/需求文档/用例管理/_执行计划_元素定位功能优化.md` - 本文档
- [ ] `HANDOFF_UI自动化.md` - 更新交接文档

### 6.3 部署交付

- [ ] 192.168.5.60 服务器已部署最新代码
- [ ] 功能验证通过

---

## 七、验收标准

### 7.1 功能验收

- [ ] API 支持新参数
- [ ] 配置面板正常工作
- [ ] 预览页面功能正常
- [ ] 元素提取重试机制生效
- [ ] 日志记录完整

### 7.2 性能验收

- [ ] 登录页面定位成功率 100% (8/8)
- [ ] 会议列表定位成功率 ≥70% (5/7)
- [ ] 单步骤定位耗时 ≤45 秒

### 7.3 代码质量

- [ ] 代码符合项目规范
- [ ] 关键函数有注释
- [ ] 无 lint 错误

---

## 八、执行记录

> 以下内容在执行过程中填写

### 8.1 Phase 1 执行记录

**开始时间**: 2026-08-03
**结束时间**: 2026-08-03
**执行人**: Claude Code
**完成情况**: ✅ 已完成
- 更新 BatchLocateRequest/BatchLocateResponse schema
- 增强 _do_locate_with_executor 支持配置参数和重试机制
- 记录元素数量、重试次数、页面加载耗时

### 8.2 Phase 2 执行记录

**开始时间**: 2026-08-03
**结束时间**: 2026-08-03
**执行人**: Claude Code
**完成情况**: ✅ 已完成
- 优化 extract_interactive_elements 函数
- 增强元素去重逻辑（多重属性组合 key）
- 扩展 Element UI/Vuetify/Ant Design 组件支持
- 提取更多元素属性（data-*, title, alt, role 等）

### 8.3 Phase 3 执行记录

**开始时间**: 2026-08-03
**结束时间**: 2026-08-03
**执行人**: Claude Code
**完成情况**: ✅ 已完成
- 新增获取定位配置弹窗
- 支持配置页面加载超时、额外等待时间、等待特定元素
- 新增预览页面按钮
- 优化定位结果显示（元素数量、耗时、重试次数）
- 前端构建验证通过

### 8.4 Phase 4 执行记录

**开始时间**: 2026-08-03
**结束时间**: 2026-08-03
**执行人**: Claude Code
**完成情况**: ✅ 已完成
- 代码已提交并推送到远程仓库（commit `46a566f2`）
- 后端 element_locator.py 已上传到服务器
- 前端构建产物已上传（Cases-D5GbBfN-.js、Cases-CVUl85Qc.css）
- Docker 容器已重启
- API 验证通过（新字段 elements_extracted/retries/page_load_time 已返回） 

---

*本文档由 Claude Code 生成，遵循项目计划执行文档规范*