# 执行计划 — 自然语言用例智能定位功能

> **关联 PRD**: `_PRD_自然语言用例智能定位功能.md`
> **优先级**: P0
> **作者**: czj / Claude Code
> **创建日期**: 2026-08-05
> **预计工期**: 5 天

---

## 总体规划

| Phase | 内容 | 工期 | 依赖 |
|-------|------|------|------|
| Phase 1 | 登录流程模板化 | 1 天 | 无 |
| Phase 2 | 智能定位后端核心 | 2 天 | Phase 1 |
| Phase 3 | 前端集成与测试 | 1 天 | Phase 2 |
| Phase 4 | 优化与文档更新 | 1 天 | Phase 3 |

---

## Phase 1: 登录流程模板化（1 天）

### 目标

将已验证的登录步骤固化为模板，智能定位时自动使用，用户无需手动配置登录。

### 任务清单

- [ ] 创建 `login_templates` 表（SQLite）
- [ ] 创建 `backend/app/models/login_template.py`
- [ ] 创建 `backend/app/schemas/login_template.py`
- [ ] 创建 `backend/app/routers/login_template.py`
- [ ] 创建 `backend/app/services/login_template_service.py`
- [ ] 插入默认登录模板（已验证的 8 步登录 + 3 步功能中心导航）
- [ ] 在 `main.py` 注册路由

### 预置模板内容

**登录模板（8 步）**：

| 步骤 | 名称 | 操作 | 选择器 | 值 |
|------|------|------|--------|-----|
| 1 | 访问登录页面 | navigate | - | https://192.168.5.44 |
| 2 | 等待登录表单加载 | wait | `input[placeholder*="手机号"]` | timeout:10000 |
| 3 | 输入用户名 | fill | `input[placeholder*="手机号"]` | admin@xty |
| 4 | 输入密码 | fill | `input[type="password"]` | Ubains@13579 |
| 5 | 输入验证码 | fill | `input[placeholder*="图"]` | csba |
| 6 | 勾选协议复选框 | click | `.el-checkbox` | - |
| 7 | 点击登录按钮 | click | `button:has-text("登录")` | - |
| 8 | 等待登录跳转完成 | wait | `[class*='nav'], .container, .el-main` | timeout:15000 |

**功能中心导航模板（3 步）**：

| 步骤 | 名称 | 操作 | 选择器 |
|------|------|------|--------|
| 9 | 点击功能中心图标 | click | `//*[@id="Home"]/div[1]/div[1]` |
| 10 | 等待功能抽屉打开 | wait | `.el-drawer` |
| 11 | 点击目标菜单 | click | `.el-drawer >> text="${菜单名}"` |

### 验证标准

- [ ] API 可正常 CRUD 登录模板
- [ ] 默认模板存在且包含 11 个步骤

---

## Phase 2: 智能定位后端核心（2 天）

### 目标

实现 `/api/element/smart-locate` 接口，自动访问被测系统、执行操作、提取选择器。

### 任务清单

#### 2.1 关键词提取与匹配模块（0.5 天）

- [ ] 创建 `backend/app/services/keyword_matcher.py`

```python
# 关键词提取
def extract_keywords(description: str) -> list[str]

# 关键词匹配元素
def match_element_by_keywords(page, keywords: list[str], action: str) -> tuple[Element, list[dict]]
```

#### 2.2 选择器提取模块（0.5 天）

- [ ] 创建 `backend/app/services/selector_extractor.py`

```python
# 提取多候选选择器
def extract_selectors(element) -> dict

# 按优先级排序
# 1. data-testid  2. ID  3. placeholder  4. aria-label  5. 文本  6. 组合选择器  7. XPath
```

#### 2.3 智能定位服务（1 天）

- [ ] 创建 `backend/app/services/smart_locate_service.py`

```python
class SmartLocateService:
    def locate_steps(self, steps: list[dict], auto_login: bool, navigate_menu: str) -> list[dict]:
        """
        主流程：
        1. 启动 Playwright
        2. 执行登录模板
        3. 导航到目标菜单
        4. 逐步骤定位 + 执行
        5. 返回结果
        """

    def locate_single_step(self, step: dict) -> dict:
        """
        单步骤定位：
        1. 提取关键词
        2. 关键词匹配
        3. 语义推断
        4. 回退策略
        """
```

#### 2.4 智能定位路由（0.5 天）

- [ ] 创建 `backend/app/routers/smart_locate.py`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/element/smart-locate` | 智能定位主接口 |
| POST | `/api/element/verify-step` | 单步骤验证（调试用） |

- [ ] 在 `main.py` 注册路由

### 验证标准

- [ ] `/api/element/smart-locate` 可自动登录并定位元素
- [ ] 每个步骤返回多种候选选择器
- [ ] 定位的选择器执行通过率 ≥ 90%

---

## Phase 3: 前端集成与测试（1 天）

### 目标

改造前端"获取定位"功能，调用智能定位接口。

### 任务清单

- [ ] 修改 `frontend/src/api/elementLocate.ts`，增加 `smartLocate` 接口
- [ ] 修改 `frontend/src/views/Cases.vue`，"获取定位"按钮改为调用智能定位接口
- [ ] 保留现有配置弹窗（目标菜单、自动登录等）
- [ ] 实时显示定位进度（WebSocket）
- [ ] 定位结果展示：成功/不确定/失败，可编辑选择器

### 验证标准

- [ ] 点击"获取定位"后可正常调用智能定位接口
- [ ] 定位结果自动填充到步骤表格
- [ ] 可直接保存并执行用例

---

## Phase 4: 优化与文档更新（1 天）

### 任务清单

- [ ] 端到端测试：创建"会议管理"模块用例并验证执行
- [ ] 更新 `HANDOFF_UI自动化.md`
- [ ] 删除旧的 `prd-code` skill 相关文档（`_PRD_用例录制器功能.md`）
- [ ] 清理临时脚本

### 验证标准

- [ ] 新建用例定位准确率 ≥ 95%
- [ ] 用例首次执行通过率 ≥ 90%

---

## 文件清单

### 新增文件

| 文件 | Phase | 说明 |
|------|-------|------|
| `backend/app/models/login_template.py` | 1 | 登录模板 ORM |
| `backend/app/schemas/login_template.py` | 1 | 登录模板 Schema |
| `backend/app/routers/login_template.py` | 1 | 登录模板路由 |
| `backend/app/services/login_template_service.py` | 1 | 登录模板服务 |
| `backend/app/services/keyword_matcher.py` | 2 | 关键词匹配模块 |
| `backend/app/services/selector_extractor.py` | 2 | 选择器提取模块 |
| `backend/app/services/smart_locate_service.py` | 2 | 智能定位服务 |
| `backend/app/routers/smart_locate.py` | 2 | 智能定位路由 |

### 修改文件

| 文件 | Phase | 说明 |
|------|-------|------|
| `backend/app/main.py` | 1,2 | 注册新路由 |
| `backend/app/database.py` | 1 | 新增 login_templates 表 |
| `backend/app/executors/playwright_executor.py` | 2 | 增加 `do_login_template()` 方法 |
| `frontend/src/api/elementLocate.ts` | 3 | 增加 smartLocate 接口 |
| `frontend/src/views/Cases.vue` | 3 | 改造获取定位功能 |

---

## 与旧方案对比

| 对比项 | 旧方案（AI 推断） | 新方案（智能定位） |
|--------|-----------------|------------------|
| 核心接口 | `/api/element/locate-batch` | `/api/element/smart-locate` |
| Claude CLI | 必须依赖 | 不需要 |
| 选择器来源 | AI 静态推断 | 实际执行验证 |
| 准确率 | 不稳定 | 高（已验证 12/12 通过） |
| 延迟 | 10-30s | 预计 5-15s |
| 成本 | Claude API 调用 | 无额外成本 |

---

*本文档由 Claude Code 于 2026-08-05 创建。*
