# PRD：智能定位语义化升级 — 语义化用例生成器

> **模块**: UI 自动化测试 — 智能元素定位
> **优先级**: P1
> **作者**: czj / Claude Code
> **创建日期**: 2026-08-18
> **状态**: 待评审
> **关联机制**: 复杂用例通用执行机制（语义化用例执行，阶段 1-6 已完成）

---

## 一、需求背景

### 1.1 问题现状

智能定位（`POST /api/element/smart-locate`）当前的定位准确率和稳定性已无法满足复杂用例需求。核心问题：

| # | 问题 | 表现 |
|---|------|------|
| 1 | **无页面身份（scope）校验** | 全页面文本关键词打分，无"当前在哪个页面"概念。跨页误配必然（如「会议列表-全部-时间」vs「创建会议-选择时间」），每次新用例都要靠"实测 DOM → 加评分补丁 → 部署验证"循环修 |
| 2 | **结果只回填裸选择器** | 智能定位返回 `params.selector` / `locator_type` / `locator_value`，**从不生成 semantic 语义目标**。生成的用例落库后走 keyword 评分路径，无法享受语义化执行机制的稳定性 |
| 3 | **一次性定位、无状态验证** | 定位成功即返回，点击后仅粗验弹窗/抽屉出现。会话 15「会议室选择」假通过（裸 checkbox + force 点击）即此类——定位"成功"但业务状态错误 |
| 4 | **失败一刀切** | 一步失败 `skip_remaining` 跳过全部后续步骤，无法单步诊断 |
| 5 | **Claude 全量调用** | 候选 ≥1 就调 `rank_candidates`，无"规则优先、Claude 按需"的短路机制，慢且贵 |

### 1.2 新建会议用例的关键经验（成功范式）

「新建会议」复杂用例从"21 步 + `element_mapping_service` 30+ 条模糊评分补丁堆叠"（会话 9-20）重写为**语义化机制**后，连跑 4 次全绿零残留（会话 22-24 验收通过）。成功范式：

```
业务意图(semantic) + 执行期现场解析 + 上下文变量 + 状态验证 + 数据自建/自清理
```

| 语义化机制成功经验 | 解决的问题 |
|------|------|
| **scope 页面身份校验**（页面注册表 url_patterns + fingerprint） | 根治跨层级误配（root cause 级） |
| **映射表 v2 精确键**（`lookup_by_key(scope, key)` 纯 dict 查找） | 替代 30+ 条模糊评分补丁 |
| **强结构模式选择器**（tab / row_checkbox / checkbox / row） | 确定性 DOM 结构，无需全页扫描 |
| **规则优先、Claude 按需仲裁**（置信度差 ≥0.1 短路） | 降成本、提速 |
| **verify 状态验证**（防假通过） | 校验业务状态而非"点到了" |
| **`{__CTX:key__}` 上下文变量** + `save_as` | 动态数据自建/自断言/自清理同名 |
| **finally 数据自清理** | 执行无残留 |

**这套经验没有回流到智能定位**——智能定位至今仍在走"无 scope 的关键词打分 + 裸选择器输出"旧路。

### 1.3 改造方向

**把智能定位从"裸选择器提取器"升级为"语义化用例生成器"**：定位阶段复用执行期的 `semantic_resolver.resolve_step` 解析链，产出 `semantic` 语义目标（type/scope/text/contains/container + 条件 verify），让智能定位生成的用例**天然走语义化执行机制**，与「新建会议-语义化重写示范」同级别稳定。

同时解决 HANDOFF P2 遗留的"智能定位 API 与用例执行路径统一"——两套逻辑共用一条解析链，一次开发双端受益。

---

## 二、需求目标

### 2.1 核心目标

智能定位产物从 `{selectors, params.selector}` 升级为 `{selectors, semantic, verify?}`，生成语义化用例并稳定执行。

### 2.2 量化指标

| 指标 | 现状 | 目标 |
|------|------|------|
| 定位结果回填 semantic 目标的步骤占比 | 0% | ≥80% |
| 智能定位生成用例的执行通过率 | 依赖 keyword 评分，不稳定 | 复杂用例连跑两次全绿、零残留 |
| 跨页误配次数 | 频繁（靠补丁逐个修） | 借助 scope 校验根治 |
| Claude 调用次数/用例 | 候选≥1 即调 | 仅真歧义时调用（规则优先短路） |

### 2.3 不包含的范围

- **finally 数据自清理自动生成**：智能定位仅生成主流程步骤；`run_on=finally` 的 api_call 清理步骤由用户按示范用例模板手动追加
- **自愈合机制**（选择器失效自动修复）：中期目标，本次不实施
- **视觉定位（CV/OCR）**：长期目标，本次不实施

---

## 三、功能需求

### 3.1 需求 1：语义解析优先定位（反向复用解析链）

**模块**: `backend/app/services/smart_locate_service.py`

#### 3.1.1 功能描述

对每个步骤的定位流程，从"关键词打分优先"改为"**语义解析优先**"：

```
当前页面 → recognize_current_page 得 scope
→ 构造候选 semantic 目标（步骤名 + action 推断）
→ semantic_resolver.resolve_step(page, step, scope, ctx) 命中 chain？
   ├─ 命中 → 用 chain 实际执行（复用 _execute_step）→ 执行成功
   │          = 该 semantic 目标已通过执行期解析器验证 → 返回
   └─ 未命中 → 走现有 keyword 定位 + 执行验证 → 成功后反向生成 semantic
```

#### 3.1.2 关键保证

生成的 semantic 目标**必须经 `resolve_step` 命中并实际执行成功**才返回。落库后执行必稳——复制示范用例"不是选择器正确，而是语义目标能稳定解析并执行"的成功经验。

#### 3.1.3 影响范围

- `backend/app/services/smart_locate_service.py`

### 3.2 需求 2：semantic 目标生成规则

**模块**: `backend/app/services/smart_locate_service.py`

#### 3.2.1 功能描述

定位成功后生成 semantic 目标，字段推断规则：

| 字段 | 推断来源 |
|------|---------|
| `type` | action 映射 + 候选元素 tag/class/role 反推：fill→input/textarea；`.el-checkbox`/`input[type=checkbox]` 且父容器 table→row_checkbox 否则 checkbox；`.el-tabs__item`/`role=tab`→tab；图标/抽屉→icon；`<button>`→button；表格行→row；其余 button |
| `text` | 语义键：步骤名核心词（剔除动作词和动态值），作执行期 v2 键 / pattern / keyword 查找文本 |
| `scope` | `recognize_current_page` 识别的页面 id；识别不到留空（执行期降级安全） |
| `contains` | 步骤名"xxx：值"模式中的锚点值（动态数据用 `{__CTX:key__}` 占位），供 pattern `:has-text()` 精确命中 |
| `container` | 候选元素父容器（`_detect_parent_container` / `_generate_combined_selectors` 运行时容器信息）→ `{type, selector}` |
| `nth` | 步骤名含"第 N 个"时提取；否则不生成 |

#### 3.2.2 影响范围

- `backend/app/services/smart_locate_service.py`
- `backend/app/routers/smart_locate.py`（`SmartLocateResult` schema 增加 `semantic`/`verify` 字段）

### 3.3 需求 3：条件 verify 生成

**模块**: `backend/app/services/smart_locate_service.py`

#### 3.3.1 功能描述

定位执行后**观察到确定状态变化才生成 verify**：

| 观察到的状态 | 生成的 verify |
|------|------|
| 点击后出现成功提示（`.el-message--success` 等） | `{type: "text_visible", text: 提示文案}` |
| 点击后出现弹窗/抽屉/确认框 | `{type: "dialog"}`（或带 text） |
| 点击后出现特定元素（如 `.room .user_list`） | `{type: "element_visible", selector: ...}` |

**保守策略**：观察不到确定状态变化则不生成 verify——避免生成错误断言导致执行失败。verify 用于防假通过，不引入假失败。

#### 3.3.2 影响范围

- `backend/app/services/smart_locate_service.py`

### 3.4 需求 4：动态数据 CTX 化

**模块**: `backend/app/services/smart_locate_service.py`

#### 3.4.1 功能描述

步骤名含"xxx：值"模式时，把值识别为动态数据 → 替换为 `{__CTX:key__}`，初始值写入用例级 `parameters[key]`，保证创建/断言/清理同名（对齐示范用例 `meetingName/room/participant` 经验）。仅对明显动态值生效，静态值保留原样。

#### 3.4.2 影响范围

- `backend/app/services/smart_locate_service.py`
- 前端 `Cases.vue batchLocate` 返回的 `parameters` 合并进用例参数

### 3.5 需求 5：前端回填 semantic

**模块**: `frontend/src/views/Cases.vue`, `frontend/src/api/elementLocate.ts`

#### 3.5.1 功能描述

`batchLocate()` 处理定位结果时，除现有 `params.selector` / `locator_type` / `locator_value` 回填外，**合并 `semantic`/`verify` 进步骤并落库**：

```ts
updatedSteps = steps.map(s => {
  const r = result.results.find(r => r.order === s.order && r.success)
  if (r) {
    return { ...s, params: {...}, locator_type, locator_value,
             semantic: r.semantic ?? s.semantic,
             verify: r.verify ?? s.verify }
  }
  return s
})
```

保存后编辑模式自动切 semantic（已有判定：任一步有 `semantic.text` 即切）。

#### 3.5.2 复用（无需新建）

- `CaseStepEditor.vue` 现有 semantic/verify/run_on 编辑 UI
- `types/case.ts` 的 `SemanticTarget` / `StepVerify` 类型已完备

#### 3.5.3 影响范围

- `frontend/src/views/Cases.vue`
- `frontend/src/api/elementLocate.ts`

### 3.6 需求 6：配套数据（可选增强）

**模块**: `backend/app/data/page_url_mapping.json`, `backend/app/data/elements_mapping.json`

#### 3.6.1 功能描述

提升 scope 覆盖度与映射表命中率：

1. **注册 `meeting_list` 会议列表页 scope**（url_patterns + fingerprint）——当前注册表仅 create_meeting/login/home/meeting_detail 4 页，会议列表无法被 `recognize_current_page` 识别
2. **映射表 v2 页级键对齐**——当前数据层是 v1 扁平结构，service 内存归组存在"会议子页键归到会议预约"的 scope 对齐隐患（`lookup_by_key("meeting_list", key)` 大概率落空）

#### 3.6.2 影响范围

- `backend/app/data/page_url_mapping.json`
- `backend/app/data/elements_mapping.json`

---

## 四、非功能需求

### 4.1 性能要求

| 指标 | 要求 |
|------|------|
| 语义解析优先命中路径 | 命中则跳过关键词打分 + Claude，单步耗时下降 |
| Claude 调用 | 仅规则无法判定时调用（同 semantic_resolver._arbitrate 短路） |
| 智能定位总耗时 | 不高于现状（语义优先路径更短） |

### 4.2 兼容性要求

- **向后兼容**：现有 `selectors` / `params.selector` / `locator_type` / `locator_value` 输出保留，老前端不回归
- **老用例零影响**：生成的 semantic 仅附加到新定位的步骤；已有步骤（含已有选择器）原样保留
- **不修改解析链**：`semantic_resolver.py` / `playwright_executor.py` / `element_mapping_service.py` / `page_url_service.py` 只消费不修改
- 数据库 schema 无变更

### 4.3 可维护性要求

- semantic 生成规则集中在 `smart_locate_service.py` 新增辅助方法，纯函数可单测
- 生成规则与执行期解析链解耦（生成器只构造目标，解析器负责验证）

---

## 五、验收标准

### 5.1 功能验收

| # | 验收项 | 验收标准 |
|---|--------|---------|
| 1 | 语义解析优先 | 定位步骤命中语义路径时不走关键词打分，且实际执行成功 |
| 2 | semantic 生成 | 定位结果含 `semantic`（type/scope/text/contains/container），生成后经 `resolve_step` 命中验证 |
| 3 | 条件 verify | 观察到确定状态变化才生成 verify，观察不到不生成 |
| 4 | 前端回填 | `batchLocate` 后步骤含 `semantic`/`verify` 并落库，编辑弹窗自动切语义模式 |
| 5 | 动态数据 CTX | "xxx：值"步骤值转 `{__CTX:key__}`，初始值进 `parameters` |

### 5.2 执行验收（关键）

| # | 验收项 | 验收标准 |
|---|--------|---------|
| 1 | 智能定位生成用例 | 用「新建会议」相关用例调智能定位，生成 semantic 目标并落库 |
| 2 | 连跑两次无残留 | 生成的用例真实执行连跑两次全绿、零残留（对照示范用例验收标准） |
| 3 | 回归 | 老用例（无 semantic 字段）执行不受影响，全部通过 |

### 5.3 测试要求

- 后端 pytest：新增 semantic 生成规则纯函数单测（`_build_candidate_semantic` / `_infer_semantic_from_element` / `_detect_verify_after`）
- 前端 `npm run build` 通过
- 已知预存坏 `tests/test_api.py` 用例以 `--deselect` 排除

---

## 六、风险与缓解

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| 生成的 semantic.text 过拟合当前 DOM | 中 | 执行漂移 | 强制"resolve_step 命中 + 实际执行成功才返回" |
| verify 生成错误导致执行失败 | 中 | 假失败 | 保守策略：仅生成观察到的确定状态断言 |
| scope 覆盖不全（注册表仅 4 页） | 中 | 部分步骤 scope 留空 | 识别不到时 semantic.scope 留空，执行期语义解析降级安全 |
| 老用例/老范式回归 | 低 | 存量用例受影响 | 新逻辑仅在智能定位流程启用，keyword 路径与执行器零改动 |

---

## 七、相关文档

| 文档 | 路径 |
|------|------|
| 复杂用例通用执行机制 PRD | `Docs/PRD/需求文档/用例管理/_PRD_复杂用例通用执行机制_语义化用例执行.md` |
| 智能定位准确率提升 PRD | `Docs/PRD/需求文档/用例管理/_PRD_智能定位准确率提升_聚焦核心快速见效.md` |
| 智能定位执行稳定性优化 PRD | `Docs/PRD/需求文档/用例管理/_PRD_智能定位功能执行稳定性优化.md` |
| UI 自动化交接文档 | `HANDOFF_UI自动化.md` |
| 语义化示范用例构造脚本 | `backend/scripts/create_semantic_meeting_case.py` |

---

*本文档由 Claude Code 于 2026-08-18 创建，评审通过后走 prd-plan 生成执行计划。*
