# 手机 RPA 元素拾取与定位标准

> 先读 [`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md)。Android 首选 uiautomator2 或 Appium UiAutomator2；iOS 使用 Appium + XCUITest/WebDriverAgent。当前模板尚无团队真实成功案例，因此本文是强制设计标准，example 仅为规格骨架，不得宣称已生产验证。

## 目录

1. 状态与边界
2. 设备准备
3. 拾取工具和步骤
4. Android 定位优先级
5. iOS 定位优先级
6. Native/WebView 与动态界面
7. 手势、输入和等待
8. 降级与留证
9. example 路由

## 1. 状态与边界

- Android 标准可用于设计和实现，但交付前必须在授权真机和官方 App 上验证。
- iOS 必须有 Mac、签名可用的 WebDriverAgent 和授权设备。
- 不 Root、不越狱、不 Hook、不修改 APK/IPA、不伪造设备身份。
- 短信、人脸、指纹、系统安全确认交给人工。

## 2. 设备准备

每次运行前检查：

- 唯一设备 serial/UDID；多个设备时不得默认取第一个。
- USB/网络连接和调试授权。
- Android 包名/Activity，或 iOS bundle id。
- 屏幕是否解锁、方向、分辨率和系统弹窗状态。
- 自动化 driver/service 是否可用。
- 设备租约/互斥；同一设备默认串行。

`doctor` 应输出上述信息，但不得输出设备隐私数据。

## 3. 拾取工具和步骤

Android 可使用 Appium Inspector、uiautomator2 的 UIAutoDev/层级导出；iOS 使用 Appium Inspector。

1. 在真机上手工进入准确页面。
2. 刷新 Inspector screenshot 和 page source。
3. 在截图或 XML 树中点选元素。
4. 记录：
   - Android：resource-id、content-desc、text、class、package、clickable、enabled、bounds
   - iOS：name/accessibility id、label、value、type、enabled、visible
5. 确认当前 context 是 Native 还是正确 WebView。
6. 记录稳定父容器、列表行和业务锚点。
7. 在 Inspector 搜索定位器，确认匹配数量。
8. 写入 element map，保存 screenshot + XML。
9. 重启 App、重新进入页面并复测。

截图上看到的元素不一定存在于控件树；必须以 page source/可访问性树验证，不能直接凭坐标写代码。

## 4. Android 定位优先级

从高到低：

1. 稳定且唯一的 `resourceId`
2. `description/content-desc`（accessibility）
3. 稳定 `text + className`
4. 业务父容器内的子元素组合
5. UiSelector / 相对关系
6. 短 XPath
7. 已验证的 instance/index
8. 图像/坐标

示例：

```python
search = d(resourceId="com.example:id/search_input")
if search.count != 1:
    raise RuntimeError("ERROR:ELEMENT_AMBIGUOUS search_input")
search.click()
search.set_text(keyword)
if not d(resourceId="com.example:id/result_list").wait(timeout=10):
    raise RuntimeError("ERROR:RESULT_TIMEOUT")
```

第三方 App 没有 resource-id 时，使用可访问性描述、稳定文案和父容器组合；不得修改第三方 APK 添加 id。

## 5. iOS 定位优先级

从高到低：

1. accessibility id / name
2. `type + name/label/value`
3. iOS predicate string
4. iOS class chain
5. XPath
6. 图像/坐标

XPath 依赖完整 XML 且通常较慢，只作后备。多个同名按钮时先定位 navigation bar、cell、alert 或其他业务容器。

## 6. Native/WebView 与动态界面

### Native/WebView

- 先枚举 contexts。
- Native 元素使用移动端控件树。
- WebView 元素切换到正确 web context 后使用 Web 定位器。
- context 数量或名称变化时按包名、URL或页面特征验证，不默认取第一个 WebView。

### 动态列表

- 虚拟列表只暴露屏幕附近元素。
- 每次滚动后重新定位。
- 用业务键/行文案选择条目，不依赖当前 instance。
- 到达末尾必须有明确状态或滚动前后内容对比。

### 系统弹窗

权限、通知、文件选择等可能属于系统包或 SpringBoard；为其建立独立作用域和显式处理策略，不把它们当业务 App 元素。

## 7. 手势、输入和等待

- 点击前确认元素可见、启用且 bounds 有效。
- 输入后读取文本或等待结果状态。
- 滑动以元素/屏幕相对区域描述，不跨设备写死绝对像素。
- 页面切换等待 Activity/view/context 或业务元素变化。
- 后台切前台、横竖屏变化后重新获取元素。
- 人工验证期间可用 scrcpy/Appium Inspector 辅助观察，程序轮询真实状态并有超时。

## 8. 降级与留证

找不到元素先检查 context、Activity、系统弹窗、滚动位置和页面 source。确认控件树未暴露后才评估局部图像/OCR。

失败保存：

- 设备 screenshot。
- page source XML。
- serial 脱敏值、包名、Activity、context 列表。
- 屏幕分辨率、方向和系统版本。
- element map 逻辑名、定位器和匹配数量。
- App 版本、driver 版本和失败阶段。

图像方案必须限定设备矩阵和搜索区域；匹配不唯一时停止。

## 9. example 路由

手机 example 规格见 [`../examples/mobile_rpa/README.md`](../examples/mobile_rpa/README.md)。在团队提供真实成功案例前，该目录只能作为实施清单和验收契约，不能作为“已跑通代码”宣传或直接复制。