ee2a4d9e22
All checks were successful
技能自动化发布 / release (push) Successful in 15s
基于 skill-template 脚手架开发，包含： - 5 张业务表（教职工、请假政策、考勤日历、请假记录、假期余额） - 请假核算引擎（扣薪计算、审批层级判定、年假抵扣） - CLI 入口（import-employees / calculate-leave / render-html） - HTML 审批与扣薪报告生成 - 示例数据与完整测试套件（295 tests passed）
142 lines
5.1 KiB
Markdown
142 lines
5.1 KiB
Markdown
# 手机 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)。在团队提供真实成功案例前，该目录只能作为实施清单和验收契约，不能作为“已跑通代码”宣传或直接复制。
|