================================================================================
移动端自动化测试 - 智能定位系统流程图
================================================================================

一、整体架构（5层金字塔）
================================================================================

                            用户查询
                              ↓
        ┌─────────────────────────────────────────┐
        │         MobileSmartLocator              │
        │      （智能定位器 - 5层策略）            │
        └─────────────────────────────────────────┘
                              ↓
        ┌─────────────────────────────────────────┐
        │  Level 1: 缓存查询（<1ms，免费）        │
        │  ✓ 同一页面同一元素第二次定位           │
        │  ✓ 成功率：100%（如果缓存存在）          │
        └─────────────────────────────────────────┘
                    ↓ 未命中
        ┌─────────────────────────────────────────┐
        │  Level 2: 快速预匹配（50-100ms，免费）  │
        │  ✓ 同义词替换："登陆" → "登录"          │
        │  ✓ 去除无意义词："点击登录" → "登录"    │
        │  ✓ 类型预过滤：只在clickable中查找      │
        │  ✓ 成功率：60-70%                       │
        └─────────────────────────────────────────┘
                    ↓ 失败
        ┌─────────────────────────────────────────┐
        │  Level 3: XML深度分析（200-500ms，免费）│
        │  ✓ 读取XML + 解析元素                   │
        │  ✓ 文本匹配 + 智能评分                  │
        │  ✓ 位置索引定位（无标识输入框）          │
        │  ✓ 成功率：80-85%                       │
        └─────────────────────────────────────────┘
                    ↓ 失败（有候选）
        ┌─────────────────────────────────────────┐
        │ Level 3.5: AI智能兜底（0.5-1.5s，付费） │
        │  ✓ 分析候选元素列表                     │
        │  ✓ AI选择最佳匹配                       │
        │  ✓ 成功率：90-95%                       │
        │  ✓ 成本：~0.01元/次                     │
        └─────────────────────────────────────────┘
                    ↓ 失败（无候选）
        ┌─────────────────────────────────────────┐
        │  Level 4: 视觉识别（1-3s，付费）        │
        │  ✓ 截图 + 多模态AI分析                  │
        │  ✓ 返回元素坐标(x, y)                   │
        │  ✓ 成功率：85-90%                       │
        │  ✓ 成本：~0.03元/次                     │
        └─────────────────────────────────────────┘
                    ↓ 失败
        ┌─────────────────────────────────────────┐
        │  Level 5: 文本AI分析（2-5s，付费）      │
        │  ✓ XML结构 + 文本AI推理                 │
        │  ✓ 复杂语义查询                         │
        │  ✓ 成功率：70-80%                       │
        │  ✓ 成本：~0.05元/次                     │
        └─────────────────────────────────────────┘
                    ↓
                定位结果


二、详细流程（以"底部导航栏第3个图标"为例）
================================================================================

【场景1】坐标模式（推荐）
────────────────────────────────────────────────────────

用户代码：
  NAV_COMMUNITY = "[540,2186][810,2356]"
  ("点击", NAV_COMMUNITY)

执行流程：
  ┌──────────────────────────────────────┐
  │ 1. 检测坐标格式                       │
  │    if desc.startswith('[') and ']['   │
  │    → 是坐标格式 ✓                     │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 2. 计算中心点                         │
  │    x = (540 + 810) / 2 = 675         │
  │    y = (2186 + 2356) / 2 = 2271      │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 3. 直接点击                           │
  │    client.click(x=675, y=2271)       │
  │    ✅ 完成！耗时: <10ms               │
  └──────────────────────────────────────┘

优势：速度极快（<10ms）、完全免费、100%准确
劣势：需要预先获取坐标、分辨率变化需调整


【场景2】AI视觉识别模式（智能）
────────────────────────────────────────────────────────

用户代码：
  ("点击", "底部导航栏第3个图标")

执行流程：
  ┌──────────────────────────────────────┐
  │ Level 1: 缓存查询                     │
  │   cache_key = page_hash + query_hash │
  │   → 未命中 ✗                          │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ Level 2: 快速预匹配                   │
  │   query = "底部导航栏第3个图标"       │
  │   → 不包含特定关键词 ✗                │
  │   → 跳过                              │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ Level 3: XML深度分析                  │
  │   1. 读取XML（200-400ms）             │
  │   2. 解析元素（50-100ms）             │
  │   3. 文本匹配                         │
  │      → 图标没有text/desc/id ✗        │
  │   4. 返回：result=None, candidates=[] │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ Level 3.5: AI智能兜底                 │
  │   candidates = [] → 跳过 ✗           │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ Level 4: 视觉识别 ✅                  │
  │   1. 截取屏幕（100ms）                │
  │   2. 调用多模态AI（1-2s）             │
  │      Prompt: "找到底部导航栏第3个图标" │
  │      Response: {                      │
  │        "found": true,                 │
  │        "x": 675,                      │
  │        "y": 2271,                     │
  │        "confidence": 90               │
  │      }                                │
  │   3. 返回坐标                         │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 4. 点击坐标                           │
  │    client.click(x=675, y=2271)       │
  │    ✅ 完成！耗时: 1-3s                │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 5. 缓存结果                           │
  │    cache[key] = {                    │
  │      'x': 675, 'y': 2271,            │
  │      'timestamp': now()              │
  │    }                                 │
  │    下次直接用缓存 ✅                  │
  └──────────────────────────────────────┘

优势：完全自动化、适应性强、语义理解
劣势：第一次慢（1-3秒）、付费（~0.03元）


三、XML分析详细流程（以"邮箱输入框"为例）
================================================================================

用户代码：
  ("输入", "邮箱输入框", "test@example.com")

执行流程：
  ┌──────────────────────────────────────┐
  │ 1. 进入Level 3: XML深度分析          │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 2. 读取XML（一次性）                  │
  │    xml_string = u2.dump_hierarchy()  │
  │    ⏱️  耗时: 200-400ms                │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 3. 解析XML                            │
  │    elements = xml_parser.parse(xml)  │
  │    ⏱️  耗时: 50-100ms                 │
  │    📊 结果: 500个元素                 │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 4. 类型预过滤（性能优化）             │
  │    query包含"输入框"                  │
  │    → 只在EditText中查找               │
  │    candidate_elements = [             │
  │      e for e in elements              │
  │      if e.class == 'EditText'         │
  │    ]                                  │
  │    📊 从500个缩减到2个 ✅              │
  │    ⏱️  耗时: 10ms                     │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 5. 文本匹配                           │
  │    query = "邮箱输入框"               │
  │    → 查找text/desc包含"邮箱"          │
  │    → 未找到（2个EditText都没标识）✗   │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 6. 位置索引定位（Phase 1优化）⭐      │
  │    检测：所有匹配都是空EditText       │
  │    → 使用位置索引                     │
  │                                       │
  │    按Y坐标排序：                      │
  │      EditText[0]: Y=379（顶部）       │
  │      EditText[1]: Y=550（中部）       │
  │                                       │
  │    关键词匹配：                       │
  │      query包含"邮箱"                  │
  │      → 选择第1个（顶部）✅            │
  │                                       │
  │    返回：                             │
  │      ref = "[58,379][1022,909]"      │
  │      (使用bounds作为ref)              │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 7. 点击输入框                         │
  │    client.click(ref)                 │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 8. 输入文本                           │
  │    client.type_text("test@...")      │
  │    ✅ 完成！总耗时: 200-500ms         │
  └──────────────────────────────────────┘

关键优化：
  ✓ 类型预过滤：500个 → 2个（节省90%遍历）
  ✓ 位置索引：智能选择第1个（顶部）
  ✓ 一次读取：避免重复dump_hierarchy()


四、AI智能兜底流程（以"密码输入框"为例）
================================================================================

场景：页面有2个EditText，都没有标识，但位置索引也无法确定

用户代码：
  ("输入", "密码输入框", "password123")

执行流程：
  ┌──────────────────────────────────────┐
  │ Level 3: XML深度分析                  │
  │   找到2个EditText（都没标识）         │
  │   位置索引：query包含"密码"           │
  │   → 应该选第2个，但不够确定           │
  │   返回：result=None, candidates=[2个] │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ Level 3.5: AI智能兜底 ✅              │
  │   输入：                              │
  │     query = "密码输入框"              │
  │     candidates = [                   │
  │       {                              │
  │         class: "EditText",           │
  │         bounds: "[58,379][1022,909]",│
  │         position: "顶部"             │
  │       },                             │
  │       {                              │
  │         class: "EditText",           │
  │         bounds: "[58,550][1022,680]",│
  │         position: "中部"             │
  │       }                              │
  │     ]                                │
  │     context: "页面有2个输入框"        │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ AI分析（通义千问）                    │
  │   Prompt:                            │
  │     "用户查询：密码输入框             │
  │      候选1：EditText，顶部            │
  │      候选2：EditText，中部            │
  │      请选择最匹配的元素"              │
  │                                       │
  │   Response:                          │
  │     {                                │
  │       "selected_index": 2,           │
  │       "confidence": 90,              │
  │       "reason": "密码框通常在邮箱框   │
  │                 下方，选择中部的"     │
  │     }                                │
  │   ⏱️  耗时: 500-1500ms                │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 返回结果                              │
  │   selected = candidates[1]           │
  │   ref = "[58,550][1022,680]"         │
  │   ✅ AI选择成功！                     │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 点击输入框 + 输入文本                 │
  │   ✅ 完成！总耗时: 0.7-2s             │
  └──────────────────────────────────────┘


五、断言系统流程（以"发帖成功"为例）
================================================================================

用户代码：
  ("断言", "发帖成功")

执行流程：
  ┌──────────────────────────────────────┐
  │ SmartAssertion.assert_text_exists()  │
  │   text = "发帖成功"                   │
  │   timeout = 5.0秒                    │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ Level 1: XML文本查找（优先）          │
  │   1. 读取XML                          │
  │   2. 遍历所有元素                     │
  │   3. 查找text/desc包含"发帖成功"      │
  │                                       │
  │   找到？                              │
  │   ├─ 是 → ✅ 返回True（50-200ms）     │
  │   └─ 否 → 继续Level 2                │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ Level 2: AI视觉识别（兜底）          │
  │   1. 截取屏幕                         │
  │   2. 调用多模态AI                     │
  │      Prompt: "页面上是否显示'发帖成功'？" │
  │      Response: {                      │
  │        "found": true,                 │
  │        "confidence": 95               │
  │      }                                │
  │   3. 返回True/False                   │
  │   ⏱️  耗时: 1-2s                      │
  └──────────────────────────────────────┘
                ↓
  ┌──────────────────────────────────────┐
  │ 返回断言结果                          │
  │   ✅ True: 断言成功                   │
  │   ❌ False: 断言失败                  │
  └──────────────────────────────────────┘


六、性能优化关键点
================================================================================

【优化1】缓存复用
  第1次定位：500ms
  第2次定位：<1ms ✅（节省99.8%）

【优化2】XML一次读取
  优化前：每个步骤读一次 → 400ms × 3 = 1200ms
  优化后：只读一次 → 400ms ✅（节省66%）

【优化3】类型预过滤
  优化前：遍历500个元素 → 200ms
  优化后：只遍历5个EditText → 50ms ✅（节省75%）

【优化4】坐标模式
  优化前：AI视觉识别 → 1-3s
  优化后：直接点击坐标 → <10ms ✅（节省99.7%）

【优化5】智能降级
  优化前：所有元素都用AI → 0.5元
  优化后：85%用XML，15%用AI → 0.075元 ✅（节省85%）


七、成本对比
================================================================================

【方案1】坐标模式（100%）
  成本：0元
  速度：极快（<10ms）
  维护：需要手动维护坐标

【方案2】混合模式（85% XML + 15% AI）
  成本：0.045元/用例
  速度：快（平均200ms）
  维护：自动化，无需维护

【方案3】纯AI模式（100% AI）
  成本：0.3元/用例
  速度：慢（平均2s）
  维护：完全自动化

推荐：混合模式（性能+成本最优）✅


八、总结
================================================================================

【核心设计】
  ✓ 5层金字塔：从快到慢，从免费到付费
  ✓ 互补策略：XML分析 + AI识别 = 完整覆盖
  ✓ 智能兜底：XML失败时AI接管
  ✓ 渐进降级：优先使用免费方法

【适用场景】
  ✓ 底部导航栏图标：坐标模式 or AI视觉识别
  ✓ 文字按钮/标签：XML快速匹配
  ✓ 输入框：XML深度分析 + 位置索引
  ✓ 断言检查：XML优先，AI兜底

【性能指标】
  ✓ 缓存命中：<1ms（免费）
  ✓ XML分析：50-500ms（免费）
  ✓ AI兜底：500-1500ms（~0.01元）
  ✓ 视觉识别：1-3秒（~0.03元）

【推荐方案】
  ✓ 开发阶段：坐标模式（快速验证）
  ✓ 稳定阶段：混合模式（性能+成本最优）⭐
  ✓ 完全自动化：纯AI模式（维护成本最低）

================================================================================

