docs(ui-cases): 更新UI自动化交接文档 + 新增元素定位优化PRD和计划

- 更新 HANDOFF_UI自动化.md，记录本次会话完成的所有工作
- 新增元素定位功能优化 PRD 文档（4个用户故事）
- 新增元素定位功能优化计划执行文档（4个阶段）
- 记录登录用例 8/8 成功、会议用例 2/7 的测试结果
- 记录所有踩坑和解决方案
Co-Authored-By: Claude <noreply@anthropic.com>

Docs/PRD/需求文档/用例管理/_PRD_元素定位功能优化.md

+# 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 文档规范*
\ No newline at end of file

Docs/PRD/需求文档/用例管理/_执行计划_元素定位功能优化.md

+# 执行计划 - 元素定位功能优化
+
+> **文档类型**: 计划执行文档
+> **关联 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 执行记录
+
+**开始时间**: 
+**结束时间**: 
+**执行人**: 
+**完成情况**: 
+
+### 8.2 Phase 2 执行记录
+
+**开始时间**: 
+**结束时间**: 
+**执行人**: 
+**完成情况**: 
+
+### 8.3 Phase 3 执行记录
+
+**开始时间**: 
+**结束时间**: 
+**执行人**: 
+**完成情况**: 
+
+### 8.4 Phase 4 执行记录
+
+**开始时间**: 
+**结束时间**: 
+**执行人**: 
+**完成情况**: 
+
+---
+
+*本文档由 Claude Code 生成，遵循项目计划执行文档规范*
\ No newline at end of file