@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/{page_probe.py → validation/test/page_probe.py}

@@ -1,459 +1,470 @@
-# -*- coding: utf-8 -*-
-"""
-page_probe.py - 页面按钮+接口画像 (开发→测试交接物)
-
-从 DuckDB 知识图谱的 traces 表查"某个页面有哪些按钮、点按钮调哪个接口",
-输出一份测试人员能照着写用例的画像。解决痛点:开发写完代码交接给测试时,
-测试不用再满仓库找页面/按钮/接口。
-
-数据源: data/index/kg.duckdb 的 traces 表
-        (vue_file, button, handler, api_fn, endpoint, verb, confidence)
-URL→Vue 映射: data/index/menu-routes.json (sys_menu 真实路由)
-
-非侵入: 无 DuckDB / 无 traces 表 → 静默回退, 只 print 提示, 不报错。
-
-Usage (作为库):
-    from page_probe import build_page_profile, render_profile_md
-    md = render_profile_md(build_page_profile(keyword='保险'))
-
-Usage (CLI):
-    python .qoder/scripts/page_probe.py --kw 保险
-    python .qoder/scripts/page_probe.py --url /veh/vehicle/vehAffair/insurance
-"""
-
-import json
-import os
-import sys
-from typing import Optional, List, Dict, Any
-
-if sys.platform == 'win32':
-    try:
-        sys.stdout.reconfigure(encoding='utf-8')
-    except (AttributeError, IOError):
-        pass
-
-_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
-if _THIS_DIR not in sys.path:
-    sys.path.insert(0, _THIS_DIR)
-_COMMON = os.path.join(_THIS_DIR, 'common')
-if _COMMON not in sys.path:
-    sys.path.insert(0, _COMMON)
-
-from common.paths import get_repo_root  # noqa: E402
-
-
-# ============================================================
-# 路径定位
-# ============================================================
-
-def _kg_db_path(repo_root: Optional[str] = None) -> str:
-    rr = repo_root or str(get_repo_root())
-    return os.path.join(rr, 'data', 'index', 'kg.duckdb')
-
-
-def _menu_routes_path(repo_root: Optional[str] = None) -> str:
-    rr = repo_root or str(get_repo_root())
-    return os.path.join(rr, 'data', 'index', 'menu-routes.json')
-
-
-# ============================================================
-# DuckDB 查询 (只读, 失败静默回退)
-# ============================================================
-
-def _query_traces(vue_pattern: str, repo_root: Optional[str] = None) -> List[Dict[str, Any]]:
-    """查 traces 表里 vue_file 匹配 pattern 的所有按钮+接口。
-    pattern 用 LIKE (大小写不敏感, 因为下面转 lower)。
-    返回 [{vue_file, button, handler, api_fn, endpoint, verb, confidence}, ...]
-    无 DuckDB / 无表 / 查询失败 → 返回 [] (静默)。
-    """
-    try:
-        import duckdb
-    except ImportError:
-        return []
-    db = _kg_db_path(repo_root)
-    if not os.path.isfile(db):
-        return []
-    try:
-        con = duckdb.connect(db, read_only=True)
-        # 确认 traces 表存在
-        tables = [r[0] for r in con.execute(
-            "SELECT table_name FROM information_schema.tables WHERE table_schema='main'"
-        ).fetchall()]
-        if 'traces' not in tables:
-            con.close()
-            return []
-        # LIKE 匹配 (vue_file 路径里有正斜杠, pattern 用 % 通配)
-        pat = '%' + vue_pattern.lower() + '%'
-        rows = con.execute(
-            "SELECT vue_file, button, handler, api_fn, endpoint, verb, confidence "
-            "FROM traces WHERE lower(vue_file) LIKE ? "
-            "ORDER BY CASE confidence "
-            "  WHEN 'high' THEN 0 WHEN 'medium' THEN 1 WHEN 'low' THEN 2 "
-            "  WHEN 'deferred' THEN 3 ELSE 4 END, button",
-            [pat],
-        ).fetchall()
-        con.close()
-        return [
-            {
-                'vue_file': r[0], 'button': r[1], 'handler': r[2],
-                'api_fn': r[3], 'endpoint': r[4], 'verb': r[5], 'confidence': r[6],
-            }
-            for r in rows
-            if r[1]  # button 不能为空
-        ]
-    except Exception:
-        return []
-
-
-def _trace_stats(repo_root: Optional[str] = None) -> Optional[Dict[str, int]]:
-    """traces 表的置信度统计 (用于画像末尾标注覆盖率)。失败返回 None。"""
-    try:
-        import duckdb
-    except ImportError:
-        return None
-    db = _kg_db_path(repo_root)
-    if not os.path.isfile(db):
-        return None
-    try:
-        con = duckdb.connect(db, read_only=True)
-        rows = con.execute(
-            "SELECT confidence, COUNT(*) FROM traces GROUP BY confidence"
-        ).fetchall()
-        con.close()
-        stats = {r[0]: int(r[1]) for r in rows}
-        stats['total'] = sum(stats.values())
-        resolved = stats.get('high', 0) + stats.get('medium', 0) + stats.get('low', 0)
-        stats['resolved'] = resolved
-        return stats
-    except Exception:
-        return None
-
-
-# ============================================================
-# URL → Vue 文件映射 (走菜单路由表)
-# ============================================================
-
-def _load_menu_routes(repo_root: Optional[str] = None) -> List[Dict[str, Any]]:
-    """读 menu-routes.json。格式: {total, source, routes: [{name, path, component}, ...]}"""
-    p = _menu_routes_path(repo_root)
-    if not os.path.isfile(p):
-        return []
-    try:
-        for enc in ('utf-8', 'utf-8-sig', 'gbk'):
-            try:
-                with open(p, encoding=enc) as f:
-                    data = json.load(f)
-                # 支持 {routes: [...]} 包装和裸 [...] 两种
-                if isinstance(data, dict):
-                    data = data.get('routes') or []
-                return data if isinstance(data, list) else []
-            except (OSError, IOError, UnicodeDecodeError, json.JSONDecodeError):
-                continue
-    except Exception:
-        return []
-    return []
-
-
-def _match_routes(keyword: str, routes: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-    """用关键词匹配菜单 (name/path/component 任一包含关键词, 大小写不敏感)。
-    返回匹配的菜单项 [{name, path, component}], 按相关度排序。
-    """
-    kw = keyword.lower().strip()
-    if not kw:
-        return []
-    hits = []
-    for r in routes:
-        name = (r.get('name') or r.get('menu_name') or '').lower()
-        path = (r.get('path') or r.get('url') or '').lower()
-        comp = (r.get('component') or r.get('component_path') or '').lower()
-        # 完全匹配 name 优先级最高, 其次 path, 最后 component
-        score = 0
-        if kw == name:
-            score = 100
-        elif kw in name:
-            score = 80
-        elif kw in path:
-            score = 60
-        elif kw in comp:
-            score = 40
-        if score > 0:
-            hits.append((score, r))
-    hits.sort(key=lambda x: -x[0])
-    return [h[1] for h in hits[:8]]  # 最多 8 个, 避免过多
-
-
-def _route_to_vue_hint(route: Dict[str, Any]) -> str:
-    """从菜单项推断 Vue 文件路径关键词 (用于 traces 查询)。
-    component 字段常是 'veh/vehicle/vehAffair/insurance/index' 这种相对路径。
-    """
-    comp = route.get('component') or route.get('component_path') or ''
-    # 取 component 里最后两段 (模块名), 如 'insurance/record'
-    parts = [p for p in comp.replace('\\', '/').split('/') if p and p != 'index']
-    if len(parts) >= 2:
-        return '/'.join(parts[-2:])
-    if parts:
-        return parts[-1]
-    # fallback: 用 path 的最后一段
-    path = route.get('path') or route.get('url') or ''
-    seg = [p for p in path.split('/') if p]
-    return seg[-1] if seg else ''
-
-
-# ============================================================
-# 核心: 构建页面画像
-# ============================================================
-
-def build_page_profile(
-    keyword: Optional[str] = None,
-    url: Optional[str] = None,
-    repo_root: Optional[str] = None,
-) -> Dict[str, Any]:
-    """构建页面画像。
-    输入: keyword (业务名如"保险") 或 url (/veh/insurance)。
-    返回:
-        {
-          'ok': True/False,
-          'reason': '失败原因' (ok=False 时),
-          'pages': [
-            {
-              'name': '保险记录', 'url': '/veh/...', 'vue_hint': 'insurance/record',
-              'buttons': [{button, handler, endpoint, verb, confidence, resolved}, ...],
-              'vue_files': [实际命中的 vue 文件路径, ...]
-            }, ...
-          ],
-          'stats': {total, resolved, ...} or None
-        }
-    """
-    rr = repo_root or str(get_repo_root())
-
-    # 1. 定位页面 (URL 直查 / 关键词查路由表)
-    routes = _load_menu_routes(rr)
-    matched_pages = []  # [{name, url, vue_hint}]
-
-    if url:
-        # URL 模式: 在路由表里找 path 匹配的, 找不到就用 url 自身做 vue 关键词
-        url_lower = url.lower()
-        hit = None
-        for r in routes:
-            rp = (r.get('path') or r.get('url') or '').lower()
-            if rp and (rp == url_lower or url_lower in rp or rp in url_lower):
-                hit = r
-                break
-        if hit:
-            matched_pages.append({
-                'name': hit.get('name') or hit.get('menu_name') or url,
-                'url': hit.get('path') or hit.get('url') or url,
-                'vue_hint': _route_to_vue_hint(hit),
-            })
-        else:
-            # 路由表没命中, 用 url 最后一段做 vue 关键词
-            seg = [p for p in url.split('/') if p]
-            matched_pages.append({
-                'name': url, 'url': url,
-                'vue_hint': seg[-1] if seg else url.strip('/'),
-            })
-    elif keyword:
-        kw_hits = _match_routes(keyword, routes)
-        # 整词匹配不到 → 尝试关键词的前缀子串 (保险异常管理 → 保险/保险异常)
-        # 中文业务名常是"业务词+修饰词", 菜单名通常只含业务词主体
-        if not kw_hits and len(keyword) >= 3:
-            for sublen in (len(keyword) - 1, len(keyword) - 2, 2):
-                if sublen < 2:
-                    break
-                sub = keyword[:sublen]
-                sub_hits = _match_routes(sub, routes)
-                if sub_hits:
-                    kw_hits = sub_hits
-                    break
-        if kw_hits:
-            for r in kw_hits:
-                matched_pages.append({
-                    'name': r.get('name') or r.get('menu_name') or keyword,
-                    'url': r.get('path') or r.get('url') or '',
-                    'vue_hint': _route_to_vue_hint(r),
-                })
-        else:
-            # 路由表没命中, 直接用关键词做 vue 关键词 (traces 表里搜)
-            # 注意: 中文搜 vue 英文路径会失败, 但留着兜底 (英文关键词场景)
-            matched_pages.append({
-                'name': keyword, 'url': '', 'vue_hint': keyword,
-            })
-    else:
-        return {'ok': False, 'reason': '需要提供 --kw 或 --url', 'pages': [], 'stats': None}
-
-    # 2. 每个页面查 traces
-    pages_result = []
-    for pg in matched_pages:
-        hint = pg['vue_hint']
-        if not hint:
-            continue
-        traces = _query_traces(hint, rr)
-        if not traces:
-            continue
-        # 按 vue_file 分组 (一个 hint 可能命中多个 vue 文件, 各自列按钮)
-        by_vue = {}
-        for t in traces:
-            by_vue.setdefault(t['vue_file'], []).append(t)
-        for vue_file, btns in by_vue.items():
-            # 去重: 同一按钮名 + 同一 endpoint 只留一个
-            seen = set()
-            dedup = []
-            for b in btns:
-                key = (b['button'], b.get('endpoint') or '')
-                if key in seen:
-                    continue
-                seen.add(key)
-                dedup.append({
-                    'button': b['button'],
-                    'handler': b['handler'],
-                    'endpoint': b['endpoint'],
-                    'verb': b['verb'],
-                    'confidence': b['confidence'],
-                    'resolved': bool(b['endpoint'] and b['endpoint'] != 'None'),
-                })
-            pages_result.append({
-                'name': pg['name'],
-                'url': pg['url'],
-                'vue_file': vue_file,
-                'buttons': dedup,
-            })
-
-    stats = _trace_stats(rr)
-
-    if not pages_result:
-        return {
-            'ok': False,
-            'reason': '知识图谱里没找到匹配的页面按钮 (可能页面未被索引, 或关键词不准)',
-            'pages': [],
-            'stats': stats,
-        }
-    return {'ok': True, 'pages': pages_result, 'stats': stats}
-
-
-# ============================================================
-# 渲染: Markdown 画像 (给测试人员看 / 写入 test-handoff.md)
-# ============================================================
-
-def render_profile_md(profile: Dict[str, Any]) -> str:
-    """把画像渲染成 Markdown。"""
-    if not profile.get('ok'):
-        lines = ['> ' + (profile.get('reason') or '无画像数据')]
-        stats = profile.get('stats')
-        if stats:
-            lines.append('> (知识图谱 traces 覆盖率 %.0f%%, 未覆盖的交互需现场确认)'
-                         % (100.0 * stats.get('resolved', 0) / max(1, stats.get('total', 1))))
-        return '\n'.join(lines)
-
-    lines = []
-    total_buttons = 0
-    for pg in profile['pages']:
-        btns = pg['buttons']
-        total_buttons += len(btns)
-        lines.append('### %s' % pg['name'])
-        if pg.get('url'):
-            lines.append('路由: `%s`' % pg['url'])
-        # vue_file 只取 data/code/ 之后的相对路径, 更短
-        vf = pg.get('vue_file', '')
-        vf_rel = vf.split('/data/code/')[-1] if '/data/code/' in vf else vf
-        lines.append('Vue: `%s`' % vf_rel)
-        lines.append('')
-        resolved_btns = [b for b in btns if b['resolved']]
-        unresolved_btns = [b for b in btns if not b['resolved']]
-
-        if resolved_btns:
-            lines.append('| 按钮 | handler | 接口 | 方法 | 置信度 |')
-            lines.append('|------|---------|------|------|--------|')
-            for b in resolved_btns:
-                ep = b['endpoint'] or '?'
-                lines.append('| %s | %s | %s | %s | %s |' % (
-                    b['button'], b['handler'] or '?', ep, (b['verb'] or '?').upper(),
-                    b['confidence']))
-            lines.append('')
-
-        if unresolved_btns:
-            lines.append('**未解析到接口的按钮** (交互意图已知, 接口需现场确认):')
-            for b in unresolved_btns:
-                lines.append('- %s → %s (%s)' % (
-                    b['button'], b['handler'] or '?', b['confidence']))
-            lines.append('')
-
-        # 测试建议 (按按钮类型自动给提示)
-        lines.append('**测试建议:**')
-        sugg = _test_suggestions(btns)
-        for s in sugg:
-            lines.append('- %s' % s)
-        lines.append('')
-
-    stats = profile.get('stats')
-    if stats:
-        cov = 100.0 * stats.get('resolved', 0) / max(1, stats.get('total', 1))
-        lines.append('> 📊 知识图谱 traces 覆盖率 %.0f%% (resolved %d/%d)。'
-                     '未覆盖的按钮交互需现场点击确认。' % (cov, stats.get('resolved', 0), stats.get('total', 1)))
-    return '\n'.join(lines)
-
-
-def _test_suggestions(btns: List[Dict[str, Any]]) -> List[str]:
-    """根据按钮文本自动生成测试建议。"""
-    sugg = []
-    btn_texts = [b['button'] for b in btns]
-    btn_set = set(btn_texts)
-    # 按常见按钮语义给建议
-    if any(k in btn_set for k in ('新增', '添加', '新建', '创建')):
-        sugg.append('新增类: fill 表单必填项 → click 新增按钮 → 断言接口返回成功 + 列表出现新记录')
-    if any(k in btn_set for k in ('编辑', '修改', '更新')):
-        sugg.append('编辑类: 选中记录 → click 编辑 → 断言表单回填 + 保存后接口 UPDATE 调用')
-    if any(k in btn_set for k in ('删除', '移除')):
-        sugg.append('删除类: click 删除 → 二次确认弹窗 → 断言接口 DELETE 调用 + 列表记录消失')
-    if any(k in btn_set for k in ('导出', '下载')):
-        sugg.append('导出类: click 导出 → 断言下载触发 (或接口 export 调用 + 文件生成)')
-    if any(k in btn_set for k in ('查询', '搜索', '筛选', '检索')):
-        sugg.append('查询类: fill 筛选条件 → click 查询 → 断言列表按条件刷新')
-    if any(k in btn_set for k in ('导入', '上传')):
-        sugg.append('导入类: upload 文件 → 断言解析结果 + 接口 import 调用')
-    if any(k in btn_set for k in ('提交', '保存', '确认')):
-        sugg.append('提交类: 填完表单 → click 提交 → 断言接口成功 + 状态流转')
-    # 异常场景 (通用)
-    if sugg:
-        sugg.append('异常场景: 必填项留空提交 → 断言校验提示; 接口超时/失败 → 断言错误提示')
-    else:
-        sugg.append('通用: 逐个点击按钮 → 断言对应接口被调用 + 页面反馈正确')
-    return sugg
-
-
-# ============================================================
-# CLI
-# ============================================================
-
-def main(argv=None):
-    import argparse
-    p = argparse.ArgumentParser(
-        prog='page_probe.py',
-        description='查页面按钮+接口画像 (开发→测试交接物)',
-    )
-    g = p.add_mutually_exclusive_group(required=True)
-    g.add_argument('--kw', help='业务关键词 (如 保险 / 排班)')
-    g.add_argument('--url', help='页面 URL (如 /veh/vehicle/vehAffair/insurance)')
-    p.add_argument('--repo', default=None, help='仓库根目录 (默认自动检测)')
-    args = p.parse_args(argv)
-
-    profile = build_page_profile(keyword=args.kw, url=args.url, repo_root=args.repo)
-
-    if not profile.get('ok'):
-        print('## 页面画像: %s' % (args.kw or args.url))
-        print()
-        print(render_profile_md(profile))
-        print()
-        sys.exit(0)
-
-    print('## 页面画像: %s' % (args.kw or args.url))
-    print()
-    print(render_profile_md(profile))
-    n_pages = len(profile['pages'])
-    n_btns = sum(len(pg['buttons']) for pg in profile['pages'])
-    print()
-    print('[page] %d 个页面, %d 个交互点' % (n_pages, n_btns))
-    sys.exit(0)
-
-
-if __name__ == '__main__':
-    main()
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+"""
+page_probe.py - 页面按钮+接口画像 (开发→测试交接物)
+
+从 DuckDB 知识图谱的 traces 表查"某个页面有哪些按钮、点按钮调哪个接口",
+输出一份测试人员能照着写用例的画像。解决痛点:开发写完代码交接给测试时,
+测试不用再满仓库找页面/按钮/接口。
+
+数据源: data/index/kg.duckdb 的 traces 表
+        (vue_file, button, handler, api_fn, endpoint, verb, confidence)
+URL→Vue 映射: data/index/menu-routes.json (sys_menu 真实路由)
+
+非侵入: 无 DuckDB / 无 traces 表 → 静默回退, 只 print 提示, 不报错。
+
+Usage (作为库):
+    from page_probe import build_page_profile, render_profile_md
+    md = render_profile_md(build_page_profile(keyword='保险'))
+
+Usage (CLI):
+    python .qoder/scripts/page_probe.py --kw 保险
+    python .qoder/scripts/page_probe.py --url /veh/vehicle/vehAffair/insurance
+"""
+
+import json
+import os
+import sys
+from typing import Optional, List, Dict, Any
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except (AttributeError, IOError):
+        pass
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _THIS_DIR not in sys.path:
+    sys.path.insert(0, _THIS_DIR)
+_COMMON = os.path.join(_THIS_DIR, 'foundation')
+if _COMMON not in sys.path:
+    sys.path.insert(0, _COMMON)
+
+from foundation.core.paths import get_repo_root  # noqa: E402
+
+
+# ============================================================
+# 路径定位
+# ============================================================
+
+def _kg_db_path(repo_root: Optional[str] = None) -> str:
+    rr = repo_root or str(get_repo_root())
+    return os.path.join(rr, 'data', 'index', 'kg.duckdb')
+
+
+def _menu_routes_path(repo_root: Optional[str] = None) -> str:
+    rr = repo_root or str(get_repo_root())
+    return os.path.join(rr, 'data', 'index', 'menu-routes.json')
+
+
+# ============================================================
+# DuckDB 查询 (只读, 失败静默回退)
+# ============================================================
+
+def _query_traces(vue_pattern: str, repo_root: Optional[str] = None) -> List[Dict[str, Any]]:
+    """查 traces 表里 vue_file 匹配 pattern 的所有按钮+接口。
+    pattern 用 LIKE (大小写不敏感, 因为下面转 lower)。
+    返回 [{vue_file, button, handler, api_fn, endpoint, verb, confidence}, ...]
+    无 DuckDB / 无表 / 查询失败 → 返回 [] (静默)。
+    """
+    try:
+        import duckdb
+    except ImportError:
+        return []
+    db = _kg_db_path(repo_root)
+    if not os.path.isfile(db):
+        return []
+    try:
+        con = duckdb.connect(db, read_only=True)
+        # 确认 traces 表存在
+        tables = [r[0] for r in con.execute(
+            "SELECT table_name FROM information_schema.tables WHERE table_schema='main'"
+        ).fetchall()]
+        if 'traces' not in tables:
+            con.close()
+            return []
+        # LIKE 匹配 (vue_file 路径里有正斜杠, pattern 用 % 通配)
+        pat = '%' + vue_pattern.lower() + '%'
+        rows = con.execute(
+            "SELECT vue_file, button, handler, api_fn, endpoint, verb, confidence "
+            "FROM traces WHERE lower(vue_file) LIKE ? "
+            "ORDER BY CASE confidence "
+            "  WHEN 'high' THEN 0 WHEN 'medium' THEN 1 WHEN 'low' THEN 2 "
+            "  WHEN 'deferred' THEN 3 ELSE 4 END, button",
+            [pat],
+        ).fetchall()
+        con.close()
+        return [
+            {
+                'vue_file': r[0], 'button': r[1], 'handler': r[2],
+                'api_fn': r[3], 'endpoint': r[4], 'verb': r[5], 'confidence': r[6],
+            }
+            for r in rows
+            if r[1]  # button 不能为空
+        ]
+    except Exception:
+        return []
+
+
+def _trace_stats(repo_root: Optional[str] = None) -> Optional[Dict[str, int]]:
+    """traces 表的置信度统计 (用于画像末尾标注覆盖率)。失败返回 None。"""
+    try:
+        import duckdb
+    except ImportError:
+        return None
+    db = _kg_db_path(repo_root)
+    if not os.path.isfile(db):
+        return None
+    try:
+        con = duckdb.connect(db, read_only=True)
+        rows = con.execute(
+            "SELECT confidence, COUNT(*) FROM traces GROUP BY confidence"
+        ).fetchall()
+        con.close()
+        stats = {r[0]: int(r[1]) for r in rows}
+        stats['total'] = sum(stats.values())
+        resolved = stats.get('high', 0) + stats.get('medium', 0) + stats.get('low', 0)
+        stats['resolved'] = resolved
+        return stats
+    except Exception:
+        return None
+
+
+# ============================================================
+# URL → Vue 文件映射 (走菜单路由表)
+# ============================================================
+
+def _load_menu_routes(repo_root: Optional[str] = None) -> List[Dict[str, Any]]:
+    """读 menu-routes.json。格式: {total, source, routes: [{name, path, component}, ...]}"""
+    p = _menu_routes_path(repo_root)
+    if not os.path.isfile(p):
+        return []
+    try:
+        for enc in ('utf-8', 'utf-8-sig', 'gbk'):
+            try:
+                with open(p, encoding=enc) as f:
+                    data = json.load(f)
+                # 支持 {routes: [...]} 包装和裸 [...] 两种
+                if isinstance(data, dict):
+                    data = data.get('routes') or []
+                return data if isinstance(data, list) else []
+            except (OSError, IOError, UnicodeDecodeError, json.JSONDecodeError):
+                continue
+    except Exception:
+        return []
+    return []
+
+
+def _match_routes(keyword: str, routes: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """用关键词匹配菜单 (name/path/component 任一包含关键词, 大小写不敏感)。
+    返回匹配的菜单项 [{name, path, component}], 按相关度排序。
+    """
+    kw = keyword.lower().strip()
+    if not kw:
+        return []
+    hits = []
+    for r in routes:
+        name = (r.get('name') or r.get('menu_name') or '').lower()
+        path = (r.get('path') or r.get('url') or '').lower()
+        comp = (r.get('component') or r.get('component_path') or '').lower()
+        # 完全匹配 name 优先级最高, 其次 path, 最后 component
+        score = 0
+        if kw == name:
+            score = 100
+        elif kw in name:
+            score = 80
+        elif kw in path:
+            score = 60
+        elif kw in comp:
+            score = 40
+        if score > 0:
+            hits.append((score, r))
+    hits.sort(key=lambda x: -x[0])
+    return [h[1] for h in hits[:8]]  # 最多 8 个, 避免过多
+
+
+def _route_to_vue_hint(route: Dict[str, Any]) -> str:
+    """从菜单项推断 Vue 文件路径关键词 (用于 traces 查询)。
+    component 字段常是 'veh/vehicle/vehAffair/insurance/index' 这种相对路径。
+    """
+    comp = route.get('component') or route.get('component_path') or ''
+    # 取 component 里最后两段 (模块名), 如 'insurance/record'
+    parts = [p for p in comp.replace('\\', '/').split('/') if p and p != 'index']
+    if len(parts) >= 2:
+        return '/'.join(parts[-2:])
+    if parts:
+        return parts[-1]
+    # fallback: 用 path 的最后一段
+    path = route.get('path') or route.get('url') or ''
+    seg = [p for p in path.split('/') if p]
+    return seg[-1] if seg else ''
+
+
+# ============================================================
+# 核心: 构建页面画像
+# ============================================================
+
+def build_page_profile(
+    keyword: Optional[str] = None,
+    url: Optional[str] = None,
+    repo_root: Optional[str] = None,
+) -> Dict[str, Any]:
+    """构建页面画像。
+    输入: keyword (业务名如"保险") 或 url (/veh/insurance)。
+    返回:
+        {
+          'ok': True/False,
+          'reason': '失败原因' (ok=False 时),
+          'pages': [
+            {
+              'name': '保险记录', 'url': '/veh/...', 'vue_hint': 'insurance/record',
+              'buttons': [{button, handler, endpoint, verb, confidence, resolved}, ...],
+              'vue_files': [实际命中的 vue 文件路径, ...]
+            }, ...
+          ],
+          'stats': {total, resolved, ...} or None
+        }
+    """
+    rr = repo_root or str(get_repo_root())
+
+    # 1. 定位页面 (URL 直查 / 关键词查路由表)
+    routes = _load_menu_routes(rr)
+    matched_pages = []  # [{name, url, vue_hint}]
+
+    if url:
+        # URL 模式: 在路由表里找 path 匹配的, 找不到就用 url 自身做 vue 关键词
+        url_lower = url.lower()
+        hit = None
+        for r in routes:
+            rp = (r.get('path') or r.get('url') or '').lower()
+            if rp and (rp == url_lower or url_lower in rp or rp in url_lower):
+                hit = r
+                break
+        if hit:
+            matched_pages.append({
+                'name': hit.get('name') or hit.get('menu_name') or url,
+                'url': hit.get('path') or hit.get('url') or url,
+                'vue_hint': _route_to_vue_hint(hit),
+            })
+        else:
+            # 路由表没命中, 用 url 最后一段做 vue 关键词
+            seg = [p for p in url.split('/') if p]
+            matched_pages.append({
+                'name': url, 'url': url,
+                'vue_hint': seg[-1] if seg else url.strip('/'),
+            })
+    elif keyword:
+        kw_hits = _match_routes(keyword, routes)
+        # 整词匹配不到 → 尝试关键词的前缀子串 (保险异常管理 → 保险/保险异常)
+        # 中文业务名常是"业务词+修饰词", 菜单名通常只含业务词主体
+        if not kw_hits and len(keyword) >= 3:
+            for sublen in (len(keyword) - 1, len(keyword) - 2, 2):
+                if sublen < 2:
+                    break
+                sub = keyword[:sublen]
+                sub_hits = _match_routes(sub, routes)
+                if sub_hits:
+                    kw_hits = sub_hits
+                    break
+        if kw_hits:
+            for r in kw_hits:
+                matched_pages.append({
+                    'name': r.get('name') or r.get('menu_name') or keyword,
+                    'url': r.get('path') or r.get('url') or '',
+                    'vue_hint': _route_to_vue_hint(r),
+                })
+        else:
+            # 路由表没命中, 直接用关键词做 vue 关键词 (traces 表里搜)
+            # 注意: 中文搜 vue 英文路径会失败, 但留着兜底 (英文关键词场景)
+            matched_pages.append({
+                'name': keyword, 'url': '', 'vue_hint': keyword,
+            })
+    else:
+        return {'ok': False, 'reason': '需要提供 --kw 或 --url', 'pages': [], 'stats': None}
+
+    # 2. 每个页面查 traces
+    pages_result = []
+    for pg in matched_pages:
+        hint = pg['vue_hint']
+        if not hint:
+            continue
+        traces = _query_traces(hint, rr)
+        if not traces:
+            continue
+        # 按 vue_file 分组 (一个 hint 可能命中多个 vue 文件, 各自列按钮)
+        by_vue = {}
+        for t in traces:
+            by_vue.setdefault(t['vue_file'], []).append(t)
+        for vue_file, btns in by_vue.items():
+            # 去重: 同一按钮名 + 同一 endpoint 只留一个
+            seen = set()
+            dedup = []
+            for b in btns:
+                key = (b['button'], b.get('endpoint') or '')
+                if key in seen:
+                    continue
+                seen.add(key)
+                dedup.append({
+                    'button': b['button'],
+                    'handler': b['handler'],
+                    'endpoint': b['endpoint'],
+                    'verb': b['verb'],
+                    'confidence': b['confidence'],
+                    'resolved': bool(b['endpoint'] and b['endpoint'] != 'None'),
+                })
+            pages_result.append({
+                'name': pg['name'],
+                'url': pg['url'],
+                'vue_file': vue_file,
+                'buttons': dedup,
+            })
+
+    stats = _trace_stats(rr)
+
+    if not pages_result:
+        return {
+            'ok': False,
+            'reason': '知识图谱里没找到匹配的页面按钮 (可能页面未被索引, 或关键词不准)',
+            'pages': [],
+            'stats': stats,
+        }
+    return {'ok': True, 'pages': pages_result, 'stats': stats}
+
+
+# ============================================================
+# 渲染: Markdown 画像 (给测试人员看 / 写入 test-handoff.md)
+# ============================================================
+
+def render_profile_md(profile: Dict[str, Any]) -> str:
+    """把画像渲染成 Markdown。"""
+    if not profile.get('ok'):
+        lines = ['> ' + (profile.get('reason') or '无画像数据')]
+        stats = profile.get('stats')
+        if stats:
+            lines.append('> (知识图谱 traces 覆盖率 %.0f%%, 未覆盖的交互需现场确认)'
+                         % (100.0 * stats.get('resolved', 0) / max(1, stats.get('total', 1))))
+        return '\n'.join(lines)
+
+    lines = []
+    total_buttons = 0
+    for pg in profile['pages']:
+        btns = pg['buttons']
+        total_buttons += len(btns)
+        lines.append('### %s' % pg['name'])
+        if pg.get('url'):
+            lines.append('路由: `%s`' % pg['url'])
+        # vue_file 只取 data/code/ 之后的相对路径, 更短
+        vf = pg.get('vue_file', '')
+        vf_rel = vf.split('/data/code/')[-1] if '/data/code/' in vf else vf
+        lines.append('Vue: `%s`' % vf_rel)
+        lines.append('')
+        resolved_btns = [b for b in btns if b['resolved']]
+        unresolved_btns = [b for b in btns if not b['resolved']]
+
+        if resolved_btns:
+            lines.append('| 按钮 | handler | 接口 | 方法 | 置信度 |')
+            lines.append('|------|---------|------|------|--------|')
+            for b in resolved_btns:
+                ep = b['endpoint'] or '?'
+                lines.append('| %s | %s | %s | %s | %s |' % (
+                    b['button'], b['handler'] or '?', ep, (b['verb'] or '?').upper(),
+                    b['confidence']))
+            lines.append('')
+
+        if unresolved_btns:
+            lines.append('**未解析到接口的按钮** (交互意图已知, 接口需现场确认):')
+            for b in unresolved_btns:
+                lines.append('- %s → %s (%s)' % (
+                    b['button'], b['handler'] or '?', b['confidence']))
+            lines.append('')
+
+        # 测试建议 (按按钮类型自动给提示)
+        lines.append('**测试建议:**')
+        sugg = _test_suggestions(btns)
+        for s in sugg:
+            lines.append('- %s' % s)
+        lines.append('')
+
+    stats = profile.get('stats')
+    if stats:
+        cov = 100.0 * stats.get('resolved', 0) / max(1, stats.get('total', 1))
+        lines.append('> 📊 知识图谱 traces 覆盖率 %.0f%% (resolved %d/%d)。'
+                     '未覆盖的按钮交互需现场点击确认。' % (cov, stats.get('resolved', 0), stats.get('total', 1)))
+    return '\n'.join(lines)
+
+
+def _test_suggestions(btns: List[Dict[str, Any]]) -> List[str]:
+    """根据按钮文本自动生成测试建议。"""
+    sugg = []
+    btn_texts = [b['button'] for b in btns]
+    btn_set = set(btn_texts)
+    # 按常见按钮语义给建议
+    if any(k in btn_set for k in ('新增', '添加', '新建', '创建')):
+        sugg.append('新增类: fill 表单必填项 → click 新增按钮 → 断言接口返回成功 + 列表出现新记录')
+    if any(k in btn_set for k in ('编辑', '修改', '更新')):
+        sugg.append('编辑类: 选中记录 → click 编辑 → 断言表单回填 + 保存后接口 UPDATE 调用')
+    if any(k in btn_set for k in ('删除', '移除')):
+        sugg.append('删除类: click 删除 → 二次确认弹窗 → 断言接口 DELETE 调用 + 列表记录消失')
+    if any(k in btn_set for k in ('导出', '下载')):
+        sugg.append('导出类: click 导出 → 断言下载触发 (或接口 export 调用 + 文件生成)')
+    if any(k in btn_set for k in ('查询', '搜索', '筛选', '检索')):
+        sugg.append('查询类: fill 筛选条件 → click 查询 → 断言列表按条件刷新')
+    if any(k in btn_set for k in ('导入', '上传')):
+        sugg.append('导入类: upload 文件 → 断言解析结果 + 接口 import 调用')
+    if any(k in btn_set for k in ('提交', '保存', '确认')):
+        sugg.append('提交类: 填完表单 → click 提交 → 断言接口成功 + 状态流转')
+    # 异常场景 (通用)
+    if sugg:
+        sugg.append('异常场景: 必填项留空提交 → 断言校验提示; 接口超时/失败 → 断言错误提示')
+    else:
+        sugg.append('通用: 逐个点击按钮 → 断言对应接口被调用 + 页面反馈正确')
+    return sugg
+
+
+# ============================================================
+# CLI
+# ============================================================
+
+def main(argv=None):
+    import argparse
+    p = argparse.ArgumentParser(
+        prog='page_probe.py',
+        description='查页面按钮+接口画像 (开发→测试交接物)',
+    )
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument('--kw', help='业务关键词 (如 保险 / 排班)')
+    g.add_argument('--url', help='页面 URL (如 /veh/vehicle/vehAffair/insurance)')
+    p.add_argument('--repo', default=None, help='仓库根目录 (默认自动检测)')
+    args = p.parse_args(argv)
+
+    profile = build_page_profile(keyword=args.kw, url=args.url, repo_root=args.repo)
+
+    if not profile.get('ok'):
+        print('## 页面画像: %s' % (args.kw or args.url))
+        print()
+        print(render_profile_md(profile))
+        print()
+        sys.exit(0)
+
+    print('## 页面画像: %s' % (args.kw or args.url))
+    print()
+    print(render_profile_md(profile))
+    n_pages = len(profile['pages'])
+    n_btns = sum(len(pg['buttons']) for pg in profile['pages'])
+    print()
+    print('[page] %d 个页面, %d 个交互点' % (n_pages, n_btns))
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()