Skip to content

U
ubains-module-test
提交 885b901c authored 作者: 陈泽健's avatar 陈泽健
浏览文件
操作

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

- 更新 HANDOFF_UI自动化.md，记录本次会话完成的所有工作
- 新增元素定位功能优化 PRD 文档（4个用户故事）
- 新增元素定位功能优化计划执行文档（4个阶段）
- 记录登录用例 8/8 成功、会议用例 2/7 的测试结果
- 记录所有踩坑和解决方案
Co-Authored-By: 's avatarClaude <noreply@anthropic.com>
上级 82c6f778
显示空白字符变更
内嵌 并排
正在显示 包含 778 行增加 和 419 行删除
Docs/PRD/需求文档/用例管理/_PRD_元素定位功能优化.md 0 → 100644
浏览文件 @ 885b901c
# 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 0 → 100644
浏览文件 @ 885b901c
# 执行计划 - 元素定位功能优化
> **文档类型**: 计划执行文档
> **关联 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
HANDOFF_UI自动化.md
浏览文件 @ 885b901c
# HANDOFF — UI自动化测试交接文档
> **生成时间**: 2026-07-27 09:50
> **生成时间**: 2026-08-03
> **当前分支**: `platform-auto-test`
> **最近提交**: `26d8d11e` fix(deploy): 添加国内镜像源加速构建（清华PyPI + npmmirror）
> **状态**: ✅ 容器化部署完成 + 已提交推送
> **最近提交**: `82c6f778` fix(element-locate): 修复批量定位数据库更新问题，延长超时时间
> **状态**: ✅ 元素定位功能完成 + 始终使用 Claude CLI + 前端步骤表格显示优化
>
> **本次会话完成**：
> - ✅ 编写 Linux 容器化部署方案文档
> - ✅ 创建 6 个部署文件（Dockerfile.backend / Dockerfile.frontend / Nginx / Compose / .env / deploy.sh）
> - ✅ 远程服务器 192.168.5.60 安装 Docker
> - ✅ 远程构建并启动服务（后端 Healthy + 前端 HTTP 200）
> - ✅ 已有服务（8088端口）不受影响
> - ✅ Git 提交并推送到远程仓库（commit: `68eccb4b` → `a3af3dba` → `2133790d` → `26d8d11e`）
> - ✅ 修复步骤表格不显示定位信息问题（新增"定位类型"和"定位值"列）
> - ✅ 去掉置信度判断，始终调用 Claude CLI 进行元素匹配
> - ✅ 修复批量定位数据库更新失败问题
> - ✅ 增加批量定位超时时间到 300 秒（5 分钟）
> - ✅ 优化微前端元素提取（支持 shadow DOM + Element UI 组件）
> - ✅ 优化 Claude CLI 调用（直接传递元素列表，不再让宿主机重新访问页面）
> - ✅ 创建测试用例验证闭环（登录成功 8/8，会议列表 2/7）
> - ✅ 生成优化需求文档和计划执行文档
> - ✅ 代码提交并推送到远程仓库
---
......@@ -23,38 +26,11 @@
- Playwright 执行互斥（不可同时执行用例）
- Git 提交协作
**当前多窗口状态**：本项目有两个窗口同时在开发：
- **本窗口**：UI 自动化测试模块（会议管理、数据分析、运维管理、管理看板）
- **另一窗口**：安全测试模块（API安全测试、华为红线检查、漏洞回归等）— 交接文档见 `HANDOFF_安全测试.md`
---
## ✅ 模块筛选器修复已完成（原卡点已解决）
**原问题**：用例管理页面"选择模块"筛选器显示安全测试模块（如"API1 - 对象级别授权失效"），与UI测试模块混在一起。
**修复方案**：后端API新增 `case_type` 参数，通过模块ID前缀 `sec_` 区分 UI测试和安全测试模块。
**已完成并验证生效**：
- ✅ 后端 `module_service.py` 的 `list()` 方法新增 `case_type` 参数（通过 `sec_` 前缀过滤）
- ✅ 后端 `routers/modules.py` 的 `list_modules` 新增 `case_type` 查询参数
- ✅ 前端 `api/modules.ts` 的 `list()` 新增 `case_type` 参数
- ✅ 前端 `Cases.vue` 的 `loadModules` 传递 `case_type='ui'`
- ✅ 前端 `Recorder.vue` 的 `loadModules` 传递 `case_type='ui'`
- ✅ **后端重启加载新代码**（杀掉旧Python进程，重新以 `--reload` 模式启动）
- ✅ **API验证通过**：`case_type=ui` 返回16个模块，`case_type=security` 返回12个模块
### 关键修复过程踩坑（重要）
1. **旧后端进程未真正关闭**：`netstat` 显示端口被占用，但 `Stop-Process -Id <PID>` 报"找不到进程"。实际是 `netstat` 显示的 PID 与 PowerShell 看到的不一致。
- **正确做法**：用 `powershell Get-Process -Name python` 找到所有 Python 进程，逐一杀掉
- 本次找到 PID 15676 和 31772，杀掉后端口才真正释放
2. **SQLAlchemy startswith 在 SQLite 中正常工作**：`Module.id.startswith("sec_")` 生成 `LIKE 'sec_' || '%'`，在 SQLite 中能正确过滤。验证通过：
- `case_type=ui`（非 sec_ 前缀）→ 16 个模块
- `case_type=security`（sec_ 前缀）→ 12 个模块
3. **Service 层逻辑正确，问题在旧进程**：直接调用 `ModuleService.list(case_type='ui')` 返回正确结果，但 API 仍返回 28 个，确认是旧后端进程在响应。
**当前多窗口状态**：本项目有多个窗口分工开发，交接文档分散在：
- `HANDOFF.md` — **平台自动化测试系统总交接**
- `HANDOFF_V2部署升级.md` — V2 部署详细交接
- `HANDOFF_UI自动化.md` — **UI 自动化测试模块（本文档）**
- `HANDOFF_安全测试.md` — 安全测试模块
---
......@@ -62,341 +38,218 @@
**平台自动化测试可视化系统 (platform-auto-test)** — Web 可视化自动化测试平台，核心创新是用例录制器。
- **技术栈**: FastAPI + SQLAlchemy(async) + SQLite + Playwright(同步API) + WebSocket / Vue 3 + Element Plus + Vite 5 + TypeScript + ECharts
- **被测系统**: 统一管理平台 (https://192.168.5.44)
- **技术栈**: FastAPI + SQLAlchemy(async) + MySQL 8.0（生产）/ SQLite（本地）+ Playwright(同步API) + WebSocket / Vue 3 + Element Plus + Vite 5 + TypeScript
- **被测系统**: 统一管理平台 (https://192.168.5.44) — 微前端 micro-app 架构
- **登录凭据**: admin@xty / Ubains@13579 · 验证码固定 `csba`
- **远程仓库**: http://git.ubainsyun.com/bing/ubains-module-test.git
- **当前分支**: `platform-auto-test`（主分支：`main`）
### 目录结构（关键路径）
```
platform-auto-test/
├── backend/app/
│ ├── main.py # FastAPI 入口（Windows ProactorEventLoop）
│ ├── executors/
│ │ └── playwright_executor.py # UI测试执行引擎（13种动作+11种断言，支持iframe）
│ ├── services/execution_service.py # 执行调度（含 run_all_cases_sync）
│ └── scripts/
│ ├── create_deep_cases_func_center_v3.py # 功能中心深层用例创建脚本（v3，73个用例）
│ ├── create_supplementary_cases.py # 🆕 补充用例较少页面脚本（8个用例）
│ ├── create_missing_ui_cases.py # 未覆盖页面补充用例
│ └── ...
├── frontend/src/
│ ├── views/Cases.vue # 用例管理
│ ├── views/Execution.vue # 执行中心
│ └── ...
├── Docs/PRD/需求文档/用例管理/
│ ├── _PRD_需求文档_功能中心深层交互用例补充.md # P2需求文档
│ ├── _执行计划_功能中心深层交互用例补充.md # P2计划执行文档
│ └── ...
└── HANDOFF_UI自动化.md # 本文档
```
- **当前分支**: `platform-auto-test`（主分支：`master`）
- **服务器**: 192.168.5.60（Docker 容器化部署）
---
## 二、本次会话任务（已完成）
## 二、本次会话完成的工作
### 2.1 P2: 功能中心深层交互用例补充 ✅
### 1. ✅ 修复步骤表格不显示定位信息
**问题背景**：59个"页面访问验证"用例仅验证页面可打开，缺少筛选器/表格/Tab等深层交互验证。37个页面完全没有深层交互用例。
**问题**：用例详情弹窗的步骤表格只显示"步骤名称"、"动作"、"参数"三列，定位信息被隐藏在 params 的 JSON 中。
**完成内容**：
**修改内容**：
- `frontend/src/views/Cases.vue` — 新增"定位类型"和"定位值"两列
- 兼容三种命名格式：`locatorType` / `locator_type` / `params.selector`
- `formatParams` 函数排除 `selector` 字段避免重复显示
- 新增 `.locator-code` 样式让定位值用代码字体显示
1. ✅ **编写PRD需求文档** — `Docs/PRD/需求文档/用例管理/_PRD_需求文档_功能中心深层交互用例补充.md`
2. ✅ **编写执行计划文档** — `Docs/PRD/需求文档/用例管理/_执行计划_功能中心深层交互用例补充.md`
3. ✅ **创建用例创建脚本** — `backend/scripts/create_deep_cases_func_center_v3.py`
- 7个步骤模板函数
- 9个模块用例构建函数
- 73个深层交互用例
4. ✅ **执行脚本创建用例** — 73/73全部创建成功
5. ✅ **P0验证** — 7个代表性用例全部通过（详见2.3）
**提交**: `b2854e30` fix(ui-cases): 修复步骤表格不显示定位信息问题
### 2.2 步骤模板函数（8个）
### 2. ✅ 始终调用 Claude CLI（去掉置信度判断）
| 模板函数 | 用途 | 适用范围 |
|---------|------|---------|
| `build_func_center_navigate_steps()` | 功能中心抽屉导航 | 会议运维/集控控制/资产管理等 |
| `build_home_menu_navigate_steps()` | 首页菜单导航 | 数据分析/管理看板/运维管理 |
| `build_table_wait_steps()` | 表格等待 | 所有表格页面 |
| `build_filter_select_steps()` | 筛选器下拉选择 | 所有筛选器页面 |
| `build_tab_switch_steps()` | Tab切换 | 所有Tab页面 |
| `build_canvas_wait_steps()` | 图表等待 | 所有图表页面 |
| `build_navigate_home_step()` | 回到首页（状态重置） | 所有用例 |
| `build_refresh_steps()` | 🆕 刷新按钮点击 | 设备列表/远程控制等 |
**问题**：之前只有关键词匹配置信度 < 0.6 时才调用 Claude CLI，导致很多步骤没有真正使用 Claude 能力。
### 2.3 P0验证结果 ✅
**修改内容**：
- `backend/app/routers/element_locator.py` — 去掉 `needs_claude = candidates[0]['confidence'] < 0.6` 判断
- 每次定位都调用 `call_claude_code_via_ssh` 函数
- Claude 返回结果与关键词重复时，提升置信度并标记为 Claude 确认
- 降低 Claude 结果采纳阈值为 0.3
**验证方式**：每个模块选1个代表性用例执行验证。
**提交**: `fbb895f8` fix(element-locate): 始终调用 Claude CLI 进行元素定位，不再依赖置信度判断
| 模块 | 验证用例 | 结果 |
|------|---------|------|
| 会议运维 | 告警列表-表格数据验证 | ✅ 通过 (162.9s) |
| 集控控制 | 文件推送-表格数据验证 | ✅ 通过 (15.3s) |
| 资产管理 | 资产信息-表格数据验证 | ✅ 通过 (16.4s) |
| 维护工单 | 工单列表-表格数据验证 | ✅ 修复后通过 (140.4s) |
| 会务管理 | 会务统筹-表格数据验证 | ✅ 通过 (16.0s) |
| 信息管理 | 下载列表-表格数据验证 | ✅ 通过 (16.1s) |
| 其他分类 | 会议审批-表格数据验证 | ✅ 修复后通过 (23.5s) |
### 3. ✅ 优化 Claude CLI 调用方式
**通过率**：7/7 = 100%（修复后）
**问题**：之前让宿主机重新访问页面提取元素，但宿主机没有登录状态，导致需要登录的页面元素提取为 0。
**修复内容**：
- 问题：`.el-table` 单一选择器超时（工单列表、会议审批页面非标准 el-table 结构）
- 修复：改为多选择器回退 `[.el-table, .el-card, .content, body]`
- 所有断言中的单一 `.el-table` selector 改为 `[.el-table, .el-card, body]` selectors 回退链
**修改内容**：
- 容器内已登录并提取元素，直接把元素列表传给宿主机的 Claude CLI 做匹配
- 使用 base64 编码 prompt 避免 SSH 命令行特殊字符问题
- 宿主机只负责调用 `claude -p` 进行智能匹配，不再访问页面
### 2.3b 补充用例P0验证结果 ✅
### 4. ✅ 修复批量定位数据库更新问题
**验证方式**：4个用例较少页面各选1个代表性用例执行验证。
**问题**：`'dict' object has no attribute 'module_id'`，因为 `case_service.update()` 期望接收 TestCaseUpdate schema 对象。
| 页面 | 验证用例 | 结果 |
|------|---------|------|
| 会议服务统计 | 筛选器验证 | ✅ 通过 |
| 消息通知 | 筛选器验证 | ✅ 修复后通过（.el-table超时→body选择器） |
| 设备列表 | 表格数据验证 | ✅ 通过 |
| 远程控制 | 表格数据验证 | ✅ 通过 |
**修改内容**：
- 使用 SQLAlchemy 的 `update()` 语句直接更新数据库
- 绕过 schema 校验，直接更新 `steps` 字段
- 确保 `locatorType` / `locatorValue` / `params.selector` 三个字段都正确保存
**通过率**：4/4 = 100%（修复后）
**提交**: `82c6f778` fix(element-locate): 修复批量定位数据库更新问题，延长超时时间
**修复内容**：
- 问题：消息通知页面等待 `.el-table, .el-card` 超时（页面非标准 el-table 结构）
- 修复：将 `build_func_center_navigate_steps` 的 wait_selector 从 `.el-table, .el-card` 改为 `body`，断言用 `element_exists` 回退链
### 5. ✅ 增加批量定位超时时间
### 2.4 新增用例分布
**问题**：8 个步骤需要 8 次 SSH + Claude CLI 调用（约 15-20 秒/步骤），总时间超过 90 秒超时。
| 模块 | 新增用例数 | 用例类型 |
|------|-----------|---------|
| 会议运维 | 12 | 表格验证(6) + 筛选器/树/分页验证(6) |
| 集控控制 | 22 | 表格验证(11) + 筛选器/Tab/元素验证(11) |
| 资产管理 | 6 | 表格验证(3) + 筛选器/按钮验证(3) |
| 维护工单 | 8 | 表格验证(4) + 筛选器/Tab验证(4) |
| 会务管理 | 4 | 表格验证(2) + 筛选器验证(2) |
| 信息管理 | 6 | 表格验证(3) + 筛选器/树验证(3) |
| 信息发布 | 1 | 表格验证(1) |
| 其他分类 | 8 | 表格验证(4) + Tab/按钮/筛选器验证(4) |
| 数据分析 | 6 | 页面元素(3) + 图表验证(3) |
| **合计** | **73** | |
**修改内容**：
- 超时时间从 90 秒增加到 300 秒（5 分钟）
- 登录用例 8 个步骤实际耗时约 138 秒
### 2.4b 补充用例较少页面分布
### 6. ✅ 优化微前端元素提取
| 页面 | 模块 | 新增用例 | 用例类型 |
|------|------|----------|----------|
| 会议服务统计 | 数据分析 | 2 | 筛选器验证 + 图表验证 |
| 消息通知 | 信息发布 | 2 | 筛选器验证 + 操作按钮验证 |
| 设备列表 | 集控控制 | 2 | 表格数据验证 + 刷新验证 |
| 远程控制 | 集控控制 | 2 | 表格数据验证 + 刷新验证 |
| **合计** | | **8** | |
**问题**：会议列表等微前端页面元素提取为 0，因为 `micro-app-body.shadowRoot` 不一定存在。
### 2.5 模块筛选器修复 ✅ 已完成
**修改内容**：
- 支持多种 micro-app 渲染模式：shadow DOM 和普通 DOM
- 支持 Element UI 组件提取（`.el-input__inner` 等）
- 增加元素去重逻辑（避免重复提取）
- 增加页面加载后重试机制（元素为空时等待 5 秒重试）
**问题背景**：用例管理页面"选择模块"筛选器显示安全测试模块（如"API1 - 对象级别授权失效"），与UI测试模块混在一起。
### 7. ✅ 功能验证测试
**问题处理文档**：`Docs/PRD/需求文档/用例管理/_PRD_问题处理_模块筛选器显示安全测试模块.md`
**计划执行文档**：`Docs/PRD/需求文档/用例管理/_执行计划_模块筛选器显示安全测试模块.md`
| 用例 | 步骤数 | 定位成功 | 结论 |
|------|--------|----------|------|
| 登录成功验证 | 8 | 8/8 ✅ | 完整闭环可用 |
| 新建会议-快速预约 | 7 | 2/7 ⚠️ | 微前端页面元素提取不完整 |
**修复方案**：后端API新增 `case_type` 参数，通过模块ID前缀 `sec_` 区分 UI测试和安全测试模块。
### 8. ✅ 生成需求文档和计划执行文档
**代码修改**：
| 文件 | 变更 |
| 文档 | 路径 |
|------|------|
| `backend/app/services/module_service.py` | `list()` 新增 `case_type` 参数，`ui` 过滤非 `sec_` 前缀，`security` 过滤 `sec_` 前缀 |
| `backend/app/routers/modules.py` | `list_modules` 新增 `case_type` 查询参数 |
| `frontend/src/api/modules.ts` | `list()` 新增 `case_type` 参数 |
| `frontend/src/views/Cases.vue` | `loadModules` 传递 `case_type='ui'` |
| `frontend/src/views/Recorder.vue` | `loadModules` 传递 `case_type='ui'` |
| 需求文档 | `Docs/PRD/需求文档/用例管理/_PRD_元素定位功能优化.md` |
| 计划执行文档 | `Docs/PRD/需求文档/用例管理/_执行计划_元素定位功能优化.md` |
**验证通过**：`case_type=ui` 返回16个模块，`case_type=security` 返回12个模块
**优化方向**：
- 支持自定义页面加载等待时间
- 支持等待特定元素出现后再提取
- 前端增加"预览页面"功能
- 元素为空时自动重试
---
## 三、用例统计
### 当前用例分布
| 模块 | 用例数 |
|------|--------|
| 会议管理 | 50 |
| 数据分析 | 40 |
| 集控控制 | 37 |
| 会议运维 | 18 |
| 运维管理 | 15 |
| 管理看板 | 15 |
| 维护工单 | 12 |
| 其他分类 | 12 |
| 资产管理 | 9 |
| 信息管理 | 9 |
| 会务管理 | 6 |
| 登录模块 | 5 |
| 功能中心 | 3 |
| 信息发布 | 2 |
| **UI测试小计** | **241** |
| 安全测试 | 42 |
| **总计** | **283** |
### 用例总数变化
| 阶段 | 用例数 | 变化 |
|------|--------|------|
| 会话开始 | 202 | - |
| 新增深层交互用例 | 275 | +73 |
| 补充用例较少页面 | 283 | +8 |
## 三、关键配置信息
| 项目 | 值 |
|------|-----|
| 服务器 IP | 192.168.5.60 |
| SSH 用户 | ubains |
| SSH 密码 | Ubains@123 |
| 部署目录 | `/data/third_party/plat-auto-test/` |
| 前端地址 | http://192.168.5.60 |
| API 文档 | http://192.168.5.60/docs |
| 健康检查 | http://192.168.5.60/health |
| MySQL 外部访问 | 192.168.5.60:3307 |
| MySQL 用户/密码 | platapp / PlatApp2026 |
| 被测系统 | https://192.168.5.44/（微前端） |
| 登录凭据 | admin@xty / Ubains@13579 · 验证码 `csba` |
| 宿主机 Python | `python3`（Playwright 在 `~/.local`） |
| 宿主机 Claude Code | ✅ 已认证（office.ubainsyun.com:8400 / glm-5.2） |
| 容器 paramiko | ✅ 已安装 |
---
## ✅ 容器化部署已完成（Linux Docker）
**目标服务器**：192.168.5.60 / Ubuntu 26.04 LTS / 用户 ubains
**已有服务**：`/opt/troubleshoot/` → 端口 8088（不受影响）
**部署方案**：`Docs/部署方案/Linux服务器部署方案.md`
**执行计划**：`Docs/部署方案/Linux容器化部署_执行计划.md`
### 完成内容
| 文件 | 说明 |
|------|------|
| `deploy/Dockerfile.backend` | 后端镜像（Python 3.10-slim + Playwright + 清华镜像源） |
| `deploy/Dockerfile.frontend` | 前端多阶段构建（node:20 → nginx:alpine + npmmirror） |
| `deploy/nginx/default.conf` | Nginx 反向代理（API + WebSocket 代理 + 静态缓存） |
| `deploy/docker-compose.yml` | 服务编排（健康检查依赖 + 启动顺序控制） |
| `deploy/.env.example` | 环境变量模板 |
| `deploy/deploy.sh` | 一键部署脚本（含健康检查） |
| `deploy/daemon.json` | Docker 镜像加速器配置（docker.1ms.run） |
### 服务状态
| 服务 | 端口 | 状态 |
|------|------|------|
| 前端 (Nginx) | 80 | ✅ HTTP 200 |
| 后端 (API) | 8001 | ✅ Healthy |
| 已有故障排查平台 | 8088 | ✅ 不受影响 |
## 四、元素定位 API 详细说明
### 修复的问题
### 4.1 单个定位 POST /api/element/locate
1. **`requests` 模块缺失** → `requirements.txt` 补充 `requests==2.31.0`
2. **健康检查 `curl` 缺失** → `Dockerfile.backend` 补充 `curl` 安装
3. **pip 下载超时（BrokenPipe）** → 改用清华 PyPI 镜像源 `pypi.tuna.tsinghua.edu.cn`
4. **npm 下载慢** → 改用 `npmmirror` 镜像源
5. **服务器 `git fetch` 只拉取 `develop` 分支** → 修改 `.git/config` 的 `fetch` 配置为 `+refs/heads/*:refs/remotes/origin/*`
6. **Docker hub 拉取超时** → 配置 `/etc/docker/daemon.json` 镜像加速器
### 部署命令
**请求体**：
```json
{
"step_description": "输入用户名",
"page_url": "https://192.168.5.44/",
"auto_login": true
}
```
```bash
# 服务器上部署
cd ~/ubains-module-test
git pull origin platform-auto-test
cd deploy
docker compose build
docker compose up -d
# 运维
docker compose logs -f # 查看日志
docker compose restart backend # 重启后端
docker compose down # 停止服务
**响应**：
```json
{
"success": true,
"candidates": [
{
"locator_type": "css",
"locator_value": "[placeholder*='手机号/用户名/邮箱']",
"confidence": 0.95,
"element_info": {
"tag": "INPUT",
"type": "text",
"placeholder": "手机号/用户名/邮箱",
"text": "",
"id": ""
}
}
],
"message": "找到 1 个候选定位器",
"screenshot": "base64..."
}
```
### 架构图
### 4.2 批量定位 POST /api/element/locate-batch
**请求体**：
```json
{
"case_id": "case_xxx",
"page_url": "https://192.168.5.44/",
"auto_login": true
}
```
用户浏览器 → http://192.168.5.60
│
▼
Nginx (:80) 容器内
├── / → 前端静态文件（SPA 路由回退 index.html）
├── /api/* → 反向代理 backend:8001
├── /api/executions/ws/* → WebSocket 代理（24h 超时）
└── *.js/.css → 7 天缓存
│
▼
Backend (uvicorn :8001, 单 worker)
│
▼
SQLite (/app/data/test_platform.db)
**响应**：
```json
{
"success": true,
"case_id": "case_xxx",
"total_steps": 6,
"located_steps": 5,
"results": [
{
"order": 1,
"description": "输入用户名",
"success": true,
"locator_type": "css",
"locator_value": "[placeholder*='手机号/用户名/邮箱']",
"confidence": 0.95,
"message": "置信度 95%"
}
],
"message": "成功定位 5/6 个步骤"
}
```
---
### 4.1 ⚠️ 批量执行验证需重新执行
**原执行ID**: `exec_ed72e45c44ad47d584f62089fe665bf8`（已因数据库锁被取消）
**用例数**: 241 个 UI 测试用例（含新增8个补充用例）
**当前状态**: 需重新执行
### 4.2 功能中心抽屉批量执行状态隔离 ⚠️ 已知限制
## 五、Git 提交记录
**现象**：批量执行时，功能中心抽屉可能残留，导致下一个用例打开抽屉时状态异常。
**当前方案**：每个用例末尾添加"回到首页"步骤（navigate），确保状态重置。
**远期方案**：每个用例创建独立 Playwright 执行器实例，彻底隔离状态。
| 提交哈希 | 提交信息 | 时间 |
|----------|----------|------|
| `82c6f778` | fix(element-locate): 修复批量定位数据库更新问题，延长超时时间 | 2026-08-03 |
| `fbb895f8` | fix(element-locate): 始终调用 Claude CLI 进行元素定位，不再依赖置信度判断 | 2026-08-03 |
| `b2854e30` | fix(ui-cases): 修复步骤表格不显示定位信息问题 | 2026-08-03 |
| `5848a57b` | feat: 本地元素定位功能 - 实际访问页面获取真实元素定位器 | 2026-08-03 |
---
## 五、下一步计划
## 六、下一步任务（优先级排序）
| 优先级 | 待办 | 说明 |
| 优先级 | 任务 | 说明 |
|--------|------|------|
| **P1** | 完整批量执行验证241个用例 | 重新执行，验证所有用例 |
| **P2** | 清理临时脚本和探索文件 | 根目录有大量临时探索脚本待清理 |
| **P3** | 批量执行状态隔离优化 | 解决功能中心抽屉批量执行时状态残留问题 |
### 晚上批量执行验证步骤
1. 确保后端运行：`cd backend && uvicorn app.main:app --reload --port 8001`
2. 查看上次执行结果：
```bash
curl http://localhost:8001/api/executions/exec_ed72e45c44ad47d584f62089fe665bf8
```
3. 如果需要重新执行，在前端用例管理页面全选执行，或用 API：
```bash
# 获取所有 UI 用例 ID
curl -s "http://localhost:8001/api/cases?limit=500" | python -c "
import sys,json
d=json.load(sys.stdin)
ids=[c['id'] for c in d['items'] if not c['moduleId'].startswith('sec_')]
print(f'UI用例: {len(ids)} 个')
"
```
| 🔴 **P0** | 元素定位功能优化 | 按已生成的 PRD 和计划执行文档实施优化 |
| 🟡 **P1** | 设备模拟模块联调 | MQTT 环境配置与联调待验证 |
| 🟢 **P2** | 清理临时脚本 | 根目录大量探索脚本和部署脚本待清理 |
| 🟢 **P2** | Phase 5 剩余 | Pinia 状态管理、单元测试 |
---
## 六、关键踩坑记录（绝对不要重复踩）
## 七、启动与运维指南
| # | 现象 | 根因 | 正确做法 |
|---|------|------|---------|
| 1 | `NotImplementedError` / Sync API inside asyncio | Windows 默认 SelectorEventLoop 不支持子进程 | 同步 API + ProactorEventLoop + 线程池 |
| 2 | 第二次执行 `start()` 失败 | 共享执行器 `_is_running` 状态 | 每用例新建 PlaywrightExecutor 实例 |
| 3 | 请求 `/api/api/cases` 404 | `baseURL:'/api'` 与路径叠加 | baseURL 留空，路径写完整 `/api/...` |
| 4 | `SQLite database is locked` | 同步执行并发写入 | check_same_thread=False + pool_pre_ping |
| 5 | bash 中 `start` 启动 CMD 失败 | MSYS 封装损坏 `&&` 引号 | `MSYS_NO_PATHCONV=1 cmd.exe /c start ...` |
| 6 | 前端页面空白 | `useRoute()` 在 computed 内调用 | 移到 setup 顶层 |
| 7 | `NOT NULL constraint failed: error_message` | 字段 nullable=False 但成功时为 None | 改为 nullable=True |
| 8 | **auto_login+重复登录** | 用例含登录步骤 | **auto_login=True时不要包含登录步骤** |
| 9 | **"点击展开功能中心"无效** | 登录后.block已可见 | **删除此步骤** |
| 10 | **Playwright asyncio检测错误** | run_in_executor中调用 | **`asyncio.set_event_loop(None)` 绕过检测** |
| 11 | **功能中心入口不是文字按钮** | `.home_nav_left`是图标按钮 | **用`.home_nav_left`选择器，不是text=功能中心** |
| 12 | **功能中心抽屉菜单点击后页面不跳转** | 需要等待抽屉关闭 | **添加 `wait body 3000ms`** |
| 13 | **工单列表等待.el-table超时** | 页面可能使用其他结构 | **用多选器或简化为 `body` 断言** |
| 14 | **批量执行抽屉状态残留** | 共享执行器实例 | **每个用例末尾添加"回到首页"步骤** |
| 15 | **el-select点击失败** | `.el-input`是包裹元素 | **用`.el-input__inner`/`.el-select`点击** |
| 16 | **菜单卡片被遮挡无法点击** | Playwright click检测actionability失败 | **4级回退：普通→force→iframe→JS点击** |
| 17 | **element_count_min的int('')崩溃** | min_count为空字符串时int()报错 | **增加健壮处理：空字符串/None回退为0** |
| 18 | **管理看板第3个select下拉不出现** | readonly input+force/JS点击不触发事件 | **简化用例：改用element_exists断言** |
| 19 | **后端非reload模式代码不生效** | uvicorn未加`--reload`参数 | **修改后端代码后需重启服务，或用`--reload`启动** |
| 20 | **API返回201而非200** | POST创建资源返回201 Created | **判断状态码用 `status_code in (200, 201)`** |
| 21 | **执行状态是completed非passed** | 执行记录status为completed，用例结果在case_results表 | **通过 passed/total_cases 判断，查 case_results 获取失败原因** |
| 22 | **单一.el-table选择器超时** | 部分页面非标准el-table结构 | **用多选择器回退 `[.el-table, .el-card, body]`** |
| 23 | **netstat显示PID但进程不存在** | Windows网络状态缓存，PID与实际进程不匹配 | **用 `Get-Process -Name python` 找实际进程** |
| 24 | **后端重启后API仍返回旧数据** | 旧进程未真正关闭，新进程绑定端口失败 | **确保旧进程完全关闭后再启动新进程** |
| 25 | **批量执行取消时database is locked** | 执行线程持有数据库锁，取消操作无法写入 | **等待执行自然完成，或重启后端** |
| 26 | **消息通知页面无.el-table** | 页面非标准el-table结构 | **用body选择器替代，断言用element_exists回退链** |
---
## 七、启动与验证
### 本地开发（Windows）
### 本地开发
```bash
# 后端（端口 8001）
......@@ -411,99 +264,49 @@ npm install
npm run dev
```
- 前端: http://localhost:3000
- API 文档: http://localhost:8001/docs
- 被测系统: https://192.168.5.44 (admin@xty / Ubains@13579 / csba)
### 生产部署（Linux Docker）
### 服务器更新
```bash
# 服务器 192.168.5.60
ssh ubains@192.168.5.60
cd ~/ubains-module-test
git pull origin platform-auto-test
cd deploy
docker compose build
docker compose up -d
```
# 更新后端（单个文件）
scp backend/app/routers/element_locator.py ubains@192.168.5.60:/data/third_party/plat-auto-test/backend/app/routers/
ssh ubains@192.168.5.60 'cd /data/third_party/plat-auto-test/deploy && docker compose restart app'
- 前端: http://192.168.5.60
- API 文档: http://192.168.5.60:8001/docs
- 已有故障排查平台: http://192.168.5.60:8088（不受影响）
# 更新前端
cd frontend && npm run build
# 上传 dist/ 到服务器 frontend/dist/
```
### 快速验证新增用例
### 验证元素定位
```bash
# 在前端执行中心，选择模块筛选"会议运维"等，批量执行深层交互用例
# 或使用API:
cd backend
PYTHONIOENCODING=utf-8 python scripts/create_deep_cases_func_center_v3.py # 创建/更新73个深层交互用例
PYTHONIOENCODING=utf-8 python scripts/create_supplementary_cases.py # 创建/更新8个补充用例
# 单个定位
curl -X POST http://192.168.5.60/api/element/locate \
-H "Content-Type: application/json" \
-d '{"step_description":"输入用户名","page_url":"https://192.168.5.44/","auto_login":false}'
# 批量定位
curl -X POST http://192.168.5.60/api/element/locate-batch \
-H "Content-Type: application/json" \
-d '{"case_id":"case_xxx","page_url":"https://192.168.5.44/","auto_login":false}'
```
---
## 八、提交记录
### 本次会话已提交
**本次部署相关提交**：
**commit `68eccb4b`** - feat(deploy): 添加容器化部署配置文件（Docker/Nginx/Compose/部署脚本）
- deploy/Dockerfile.backend: 后端镜像（Python 3.10-slim + Playwright）
- deploy/Dockerfile.frontend: 前端多阶段构建（node:20 → nginx:alpine）
- deploy/nginx/default.conf: Nginx 反向代理（API + WebSocket）
- deploy/docker-compose.yml: 服务编排（健康检查 + 启动顺序）
- deploy/.env.example: 环境变量模板
- deploy/deploy.sh: 一键部署脚本
**commit `a3af3dba`** - fix(deploy): 后端 requirements.txt 补充 requests 依赖
- 容器化部署时发现缺少 requests 库导致后端启动失败
**commit `2133790d`** - fix(deploy): Dockerfile 补充 curl 依赖（健康检查需要）
- 后端容器实际运行正常，但 healthcheck 因缺少 curl 而失败
**commit `26d8d11e`** - fix(deploy): 添加国内镜像源加速构建（清华PyPI + npmmirror）
- 后端 pip 使用清华镜像避免 BrokenPipe 超时
- 前端 npm 使用 npmmirror 加速依赖下载
- 增加 pip 重试次数和超时配置
### 历史提交
**commit `5669460a`** - feat(ui-test): 新增73个深层交互用例+模块筛选器case_type过滤
- 后端 `module_service.py` / `routers/modules.py` 新增 `case_type` 参数
- 前端 `api/modules.ts` / `Cases.vue` / `Recorder.vue` 传递 `case_type='ui'`
- 新增73个深层交互用例（202→275）
- 功能中心深层用例创建脚本 `create_deep_cases_func_center_v3.py`
- PRD和计划执行文档
**commit `6b4c6322`** - docs(ui-test): 更新UI自动化交接文档-模块筛选器修复完成+批量执行进度
- 更新交接文档状态
**commit `2b735bfb`** - feat(ui-test): 补充8个用例较少页面的深层交互用例(233→241)
- 会议服务统计：筛选器验证+图表验证
- 消息通知：筛选器验证+操作按钮验证（修复.el-table超时→body选择器）
- 设备列表：表格数据验证+刷新验证
- 远程控制：表格数据验证+刷新验证
- 补充用例创建脚本 `create_supplementary_cases.py`
- 新增8个补充用例（233→241）
### 历史未提交变更
| 文件 | 变更说明 |
|------|---------|
| `backend/app/models/module.py` | 新增 parent_id 字段 + 自引用关系 |
| `backend/app/schemas/module.py` | ModuleCreate/ModuleUpdate/ModuleResponse 增加 parent_id/children |
| `backend/app/database.py` | 增加 parent_id 列自动迁移 |
| `backend/app/routers/modules.py` | 响应构造增加 parent_id |
| `backend/app/services/module_service.py` | create/update 支持 parent_id |
| `backend/app/executors/playwright_executor.py` | 断言健壮性：element_count_min/count 空值处理 |
| `frontend/src/types/module.ts` | Module 接口增加 parentId/children |
| `frontend/src/api/modules.ts` | 新增 buildModuleTree() |
| `frontend/src/views/Cases.vue` | 2处 el-select → el-tree-select |
| `frontend/src/views/Recorder.vue` | 1处 el-select → el-tree-select |
| `frontend/src/views/Modules.vue` | 编辑弹窗增加父模块选择 + 循环引用防护 |
| `HANDOFF_UI自动化.md` | 本文档 |
## 八、踩坑记录（本次新增）
| # | 现象 | 根因 | 正确做法 |
|---|------|------|---------|
| 27 | `Cannot read properties of undefined (reading 'items')` | 前端 `request.ts` 响应拦截器 `return response.data` | 改为 `return response`，所有 API 文件统一用 `response.data` |
| 28 | Playwright Sync API inside asyncio loop | `run_in_executor` 线程中 Playwright 检测到 asyncio 循环 | 使用专用 `threading.Thread` + `asyncio.set_event_loop(None)` |
| 29 | 页面加载 `Timeout 30000ms` | `networkidle` 在 SPA 页面可能永不触发 | 改用 `domcontentloaded` + 额外等待 |
| 30 | SSH 调用 `sshpass: not found` | 容器内没有安装 sshpass | 改用 `paramiko` 库建立 SSH 连接 |
| 31 | `No module named 'paramiko'` | 容器内未安装 paramiko | `pip install paramiko` |
| 32 | 关键词匹配 0 候选 | `extract_keywords` 拆分中文逻辑不对 | 改进为去除动作词 + 拆分子词 + 单字匹配 |
| 33 | 容器重启后 `ImportError` | `database.py` 导出的是 `get_db` 不是 `get_session` | 改为 `from app.database import async_session_maker` |
| 34 | 批量定位超时 | 8 步骤需 8 次 SSH + Claude CLI，超过 90s 超时 | 增加超时时间到 300s |
| 35 | 数据库更新失败 `'dict' object has no attribute 'module_id'` | `case_service.update()` 期望 schema 对象 | 使用 SQLAlchemy `update()` 语句直接更新 |
| 36 | 宿主机元素提取为 0 | `ai_locate_worker.py` 没有登录状态 | 改为容器内提取元素，宿主机只做 Claude 匹配 |
| 37 | 微前端页面元素提取不完整 | `micro-app-body.shadowRoot` 不一定存在 | 支持多种渲染模式 + Element UI 组件提取 |
---
......@@ -511,26 +314,19 @@ PYTHONIOENCODING=utf-8 python scripts/create_supplementary_cases.py #
| 文档 | 路径 |
|------|------|
| CLAUDE.md | `CLAUDE.md` |
| 项目指南 | `CLAUDE.md` |
| 多窗口并行开发指南 | `Docs/多窗口并行开发指南.md` |
| 功能中心深层交互用例补充需求文档 | `Docs/PRD/需求文档/用例管理/_PRD_需求文档_功能中心深层交互用例补充.md` |
| 功能中心深层交互用例补充执行计划 | `Docs/PRD/需求文档/用例管理/_执行计划_功能中心深层交互用例补充.md` |
| 模块筛选器问题处理文档 | `Docs/PRD/需求文档/用例管理/_PRD_问题处理_模块筛选器显示安全测试模块.md` |
| 模块筛选器计划执行文档 | `Docs/PRD/需求文档/用例管理/_执行计划_模块筛选器显示安全测试模块.md` |
| 深层用例优化需求文档 | `Docs/PRD/需求文档/用例管理/_PRD_需求文档_深层交互用例步骤优化.md` |
| 前端适配模块父子层级需求文档 | `Docs/PRD/需求文档/用例管理/_PRD_需求文档_前端适配模块父子层级.md` |
| 功能中心深层用例创建脚本 | `backend/scripts/create_deep_cases_func_center_v3.py` |
| 补充用例创建脚本 | `backend/scripts/create_supplementary_cases.py` |
| 安全测试交接文档 | `HANDOFF_安全测试.md` |
| UI自动化交接文档 | `HANDOFF_UI自动化.md`（本文档） |
| Linux服务器部署方案 | `Docs/部署方案/Linux服务器部署方案.md` |
| 容器化部署执行计划 | `Docs/部署方案/Linux容器化部署_执行计划.md` |
| 后端 Dockerfile | `deploy/Dockerfile.backend` |
| 前端 Dockerfile | `deploy/Dockerfile.frontend` |
| Nginx 配置 | `deploy/nginx/default.conf` |
| Docker Compose 编排 | `deploy/docker-compose.yml` |
| 部署脚本 | `deploy/deploy.sh` |
| 主 PRD | `Docs/PRD/需求文档/总览/_PRD_平台自动化测试可视化系统需求文档.md` |
| UI用例录入优化 PRD | `Docs/PRD/需求文档/用例管理/_PRD_UI自动化用例录入优化.md` |
| **元素定位功能优化 PRD** | `Docs/PRD/需求文档/用例管理/_PRD_元素定位功能优化.md` |
| **元素定位功能优化计划** | `Docs/PRD/需求文档/用例管理/_执行计划_元素定位功能优化.md` |
| 当前进度记录 | `Docs/PRD/需求文档/总览/当前进度记录.md` |
| V2 部署设计 | `Docs/部署方案/Linux容器化部署方案_v2.md` |
| HANDOFF 总交接 | `HANDOFF.md` |
| UI自动化交接 | `HANDOFF_UI自动化.md`（本文档） |
| V2 部署交接 | `HANDOFF_V2部署升级.md` |
| 安全测试交接 | `HANDOFF_安全测试.md` |
---
*本文档由 Claude Code 维护，供下一次会话快速恢复上下文。*
*本文档由 Claude Code 于 2026-08-03 更新，记录元素定位功能优化 + Claude CLI 始终调用 + 前端步骤表格优化 + 功能验证测试，供下次会话快速恢复上下文。*
\ No newline at end of file
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑！
请 注册 或者 后发表评论