@hupan56/wlkj 3.2.0 → 3.3.1

package/templates/qoder/scripts/domain/kg/extract/java/member_extractor.py

@@ -0,0 +1,157 @@
+# -*- coding: utf-8 -*-
+"""方法/字段级提取器: 端点 + 权限 + 校验 + 调用链 + 字段映射。
+
+和 class_extractor 互补: class_extractor 处理类级（实体+注入）,
+本文件处理类内成员（方法→端点/权限, 字段→校验/列）。
+"""
+from __future__ import annotations
+from . import _parser as P
+
+
+# Sa-Token 权限注解
+_SATOKEN_PERM = {'SaCheckPermission', 'SaCheckRole', 'SaCheckLogin', 'SaMode', 'SaIgnore'}
+# 校验注解
+_VALIDATION = {'NotNull', 'NotBlank', 'NotEmpty', 'Size', 'Min', 'Max',
+               'Email', 'Pattern', 'Positive', 'Negative', 'Digits', 'Past', 'Future'}
+# MyBatis-Plus 字段注解
+_MP_FIELD = {'TableId', 'TableField', 'TableLogic'}
+
+
+def extract(root, repo_id: str, filepath: str, owner_classes: list):
+    """提取方法/字段级实体 + 边。
+
+    Args:
+        owner_classes: class_extractor 已提取的类信息 [{name, etype, id, anns}]
+                      方法级边要锚到所属类上。
+    Returns:
+        (entities, edges)
+    """
+    entities, edges = [], []
+    if root is None:
+        return entities, edges
+
+    # 建 name → owner 映射（方法/字段属于哪个类）
+    owner_map = {c['name']: c for c in owner_classes}
+
+    for cls in P.get_class_decls(root):
+        cls_name = P.get_class_name(cls)
+        owner = owner_map.get(cls_name)
+        if not owner:
+            continue  # 不是后端组件类（如普通 DTO），由 domain_extractor 处理
+        owner_id = owner['id']
+
+        # ===== 方法级: 端点 + 权限 + 调用链 =====
+        for m in P.get_methods(cls):
+            method_name = m['name']
+            m_anns = m['annotations']
+
+            # 端点: @GetMapping/@PostMapping 等
+            endpoint_path = _extract_endpoint_path(m_anns, owner.get('anns_dict', {}))
+            if endpoint_path:
+                ep_id = 'EP:%s:%s' % (repo_id, endpoint_path)
+                entities.append({
+                    'id': ep_id, 'repo_id': repo_id, 'type': 'ENDPOINT',
+                    'canonical': endpoint_path, 'cn': '',
+                    'props': {'method': _extract_http_verb(list(m_anns.keys())),
+                              'handler': '%s.%s' % (cls_name, method_name),
+                              'returns': m.get('return_type', '')},
+                })
+                edges.append({
+                    'from_id': ep_id, 'to_id': owner_id,
+                    'edge_type': 'handled_by',
+                    'from_repo': repo_id, 'to_repo': repo_id,
+                    'confidence': 1.0, 'source': 'explicit',
+                })
+
+            # 权限: @SaCheckPermission("asset:list")
+            for sa in _SATOKEN_PERM:
+                if sa in m_anns:
+                    perm_code = m_anns[sa].strip('"').strip("'") or sa
+                    perm_id = 'PERM:%s:%s' % (repo_id, perm_code)
+                    entities.append({
+                        'id': perm_id, 'repo_id': repo_id, 'type': 'PERMISSION',
+                        'canonical': perm_code, 'cn': '',
+                        'props': {'check_type': sa, 'method': '%s.%s' % (cls_name, method_name)},
+                    })
+                    edges.append({
+                        'from_id': owner_id, 'to_id': perm_id,
+                        'edge_type': 'guards',
+                        'from_repo': repo_id, 'to_repo': repo_id,
+                        'confidence': 1.0, 'source': 'explicit',
+                    })
+
+            # 调用链: 方法体内 remoteClientService.getById()
+            # 要把 object 名映射回字段类型（字段类型在 owner 的 fields 里）
+            field_types = {f['name']: f['type'] for f in P.get_fields(cls)}
+            for call in P.get_method_calls(m['body_node']):
+                obj_name = call['object']
+                method = call['method']
+                if not obj_name:
+                    continue
+                dep_type = field_types.get(obj_name) or _guess_type_by_name(obj_name)
+                if not dep_type:
+                    continue
+                dep_prefix = _guess_dep_prefix(dep_type)
+                edges.append({
+                    'from_id': owner_id,
+                    'to_id': '%s:%s:%s' % (dep_prefix, repo_id, dep_type),
+                    'edge_type': 'calls',
+                    'from_repo': repo_id, 'to_repo': repo_id,
+                    'confidence': 1.0, 'source': 'explicit',
+                    'props': {'method': method, 'callee_field': obj_name},
+                })
+
+    return entities, edges
+
+
+# ===== 端点相关 =====
+_ENDPOINT_ANN_TO_VERB = {
+    'GetMapping': 'GET', 'PostMapping': 'POST',
+    'PutMapping': 'PUT', 'DeleteMapping': 'DELETE',
+    'PatchMapping': 'PATCH', 'RequestMapping': 'ANY',
+}
+
+
+def _extract_endpoint_path(method_anns: dict, class_anns: dict) -> str:
+    """提取端点路径: 类级 @RequestMapping + 方法级 @GetMapping。"""
+    base = ''
+    if 'RequestMapping' in class_anns:
+        base = class_anns['RequestMapping'].strip('"').strip("'")
+    for ann, _ in method_anns.items():
+        if ann in _ENDPOINT_ANN_TO_VERB:
+            path = method_anns[ann].strip('"').strip("'")
+            if base and path and not path.startswith('/'):
+                path = base.rstrip('/') + '/' + path
+            elif base and not path:
+                path = base
+            return path or '/'
+    return ''
+
+
+def _extract_http_verb(ann_names: list) -> str:
+    for ann in ann_names:
+        if ann in _ENDPOINT_ANN_TO_VERB:
+            return _ENDPOINT_ANN_TO_VERB[ann]
+    return 'ANY'
+
+
+def _guess_type_by_name(field_name: str) -> str:
+    """从字段名猜类型（如 xxxMapper → XxxMapper）。
+    字段类型有时在 javadoc/import 里找不到, 用命名兜底。"""
+    parts = field_name.split('_')
+    guessed = ''.join(p.capitalize() for p in parts if p)
+    if 'mapper' in field_name.lower():
+        return guessed if guessed.endswith('Mapper') else guessed + 'Mapper'
+    if 'service' in field_name.lower():
+        return guessed if guessed.endswith('Service') else guessed + 'Service'
+    return ''
+
+
+def _guess_dep_prefix(type_name: str) -> str:
+    if type_name.endswith('Mapper'):
+        return 'MAP'
+    if type_name.endswith('ServiceImpl') or type_name.endswith('Service'):
+        return 'SVC'
+    if type_name.endswith('Controller'):
+        return 'CTRL'
+    return 'SVC'

package/templates/qoder/scripts/domain/kg/extract/java/mybatisplus_extractor.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""MyBatis-Plus ORM 提取器（@TableName/@TableId/@TableField/@TableLogic）。
+
+职责: 识别 Entity→Table 映射 + 字段→列映射。
+本项目用 MyBatis-Plus 不是 JPA, @TableName("employee_online") 是表名真源。
+实体识别在 class_extractor(Entity 类型) + domain_extractor(字段映射),
+这里按 MyBatis-Plus 关注点导出。
+"""
+from __future__ import annotations
+from . import _parser as P
+from . import class_extractor as _ce
+from . import domain_extractor as _de
+
+MP_TABLE = {'TableName'}
+MP_ID = {'TableId'}
+MP_FIELD = {'TableField'}
+MP_LOGIC = {'TableLogic'}
+MP_ALL = MP_TABLE | MP_ID | MP_FIELD | MP_LOGIC
+
+
+def is_mybatis_entity(annotations: dict) -> bool:
+    """类是否 @TableName（MyBatis-Plus Entity）。"""
+    return 'TableName' in annotations
+
+
+def extract_table_name(annotations: dict) -> str:
+    """从 @TableName 注解取表名。"""
+    v = annotations.get('TableName', '')
+    return v.strip('"').strip("'") if v else ''
+
+
+def extract(root, repo_id: str, filepath: str):
+    """MyBatis-Plus Entity 提取（= domain_extractor, 处理 Entity/字段/列映射）。"""
+    return _de.extract(root, repo_id, filepath)

package/templates/qoder/scripts/domain/kg/extract/java/pg_upsert.py

@@ -0,0 +1,165 @@
+# -*- coding: utf-8 -*-
+"""PG 批量 upsert: 把 Java extractor 的 entities/edges 写进 PostgreSQL。
+
+独立于 DuckDB 写入路径 —— GOAL 2 直接写 PG（KNOWLEDGE_BACKEND=pg 时）。
+用 executemany + ON CONFLICT 幂等 upsert。
+"""
+from __future__ import annotations
+import os
+import sys
+import json
+import time
+
+# 路径自举
+_THIS = os.path.dirname(os.path.abspath(__file__))
+for _i in range(8):
+    _p = os.path.dirname(_THIS)
+    if os.path.isfile(os.path.join(_p, 'foundation', 'bootstrap.py')):
+        sys.path.insert(0, _p)
+        break
+    _THIS = _p
+
+
+def _get_pg_engine():
+    """获取 PG 引擎（优先用工作台的 SessionLocal 引擎）。"""
+    # 优先工作台 backend（KNOWLEDGE_BACKEND=pg 时）
+    ws_backend = os.path.join(os.getcwd(), 'wlinkj-workspace', 'backend')
+    if os.path.isfile(os.path.join(ws_backend, '.env')) or os.path.isfile(os.path.join(ws_backend, '..', '..', '.env')):
+        try:
+            from dotenv import load_dotenv
+            for env_path in [os.path.join(ws_backend, '.env'),
+                             os.path.join(ws_backend, '..', '..', '.env')]:
+                if os.path.isfile(env_path):
+                    load_dotenv(env_path); break
+        except Exception:
+            pass
+    # 用工作台 db 引擎
+    sys.path.insert(0, ws_backend)
+    try:
+        from app.db import engine
+        return engine, 'app.db'
+    except Exception:
+        pass
+    # 兜底: 直接从环境变量建引擎
+    db_url = os.environ.get('DATABASE_URL', '')
+    if db_url and 'postgresql' in db_url:
+        from sqlalchemy import create_engine
+        return create_engine(db_url), 'env'
+    return None, None
+
+
+def upsert_batch(entities: list, edges: list, batch_size: int = 500):
+    """批量 upsert entities + edges 到 PG。
+
+    entities: [{id, repo_id, type, canonical, cn, props}]
+    edges:    [{from_id, to_id, edge_type, from_repo, to_repo, confidence, source, props}]
+    幂等: ON CONFLICT 覆盖。
+    """
+    engine, src = _get_pg_engine()
+    if engine is None:
+        return {'ok': False, 'error': 'PG 引擎不可用 (检查 DATABASE_URL/工作台路径)'}
+
+    from sqlalchemy import text
+    ent_ok = ent_fail = ed_ok = ed_fail = 0
+    t0 = time.time()
+
+    with engine.begin() as conn:
+        # === 先确保所有 repo_id 在 repos 表注册 (entities.repo_id 有FK约束) ===
+        repo_ids = set()
+        for e in entities:
+            if e.get('repo_id'):
+                repo_ids.add(e['repo_id'])
+        for e in edges:
+            if e.get('from_repo'):
+                repo_ids.add(e['from_repo'])
+            if e.get('to_repo'):
+                repo_ids.add(e['to_repo'])
+        for rid in repo_ids:
+            try:
+                conn.execute(text("""
+                    INSERT INTO repos (id, name) VALUES (:id, :id)
+                    ON CONFLICT (id) DO NOTHING
+                """), {'id': rid})
+            except Exception:
+                pass
+
+        # === entities ===
+        for i in range(0, len(entities), batch_size):
+            batch = entities[i:i + batch_size]
+            for e in batch:
+                try:
+                    props_json = e.get('props') or {}
+                    if not isinstance(props_json, str):
+                        props_json = json.dumps(props_json, ensure_ascii=False)
+                    conn.execute(text("""
+                        INSERT INTO entities (id, repo_id, type, canonical, cn, props)
+                        VALUES (:id, :repo_id, :type, :canonical, :cn, CAST(:props AS JSONB))
+                        ON CONFLICT (id) DO UPDATE SET
+                            type=EXCLUDED.type, canonical=EXCLUDED.canonical,
+                            cn=EXCLUDED.cn, props=EXCLUDED.props
+                    """), {
+                        'id': e['id'], 'repo_id': e.get('repo_id', ''),
+                        'type': e['type'], 'canonical': e.get('canonical', ''),
+                        'cn': e.get('cn', ''), 'props': props_json,
+                    })
+                    ent_ok += 1
+                except Exception:
+                    ent_fail += 1
+
+        # === edges ===
+        for i in range(0, len(edges), batch_size):
+            batch = edges[i:i + batch_size]
+            for e in batch:
+                try:
+                    props_json = e.get('props') or {}
+                    if not isinstance(props_json, str):
+                        props_json = json.dumps(props_json, ensure_ascii=False)
+                    conn.execute(text("""
+                        INSERT INTO edges (from_id, to_id, edge_type, from_repo, to_repo,
+                                          confidence, source, expires_at, fingerprint, props)
+                        VALUES (:from_id, :to_id, :edge_type, :from_repo, :to_repo,
+                                :confidence, :source,
+                                CAST(:expires_at AS TIMESTAMPTZ), :fingerprint,
+                                CAST(:props AS JSONB))
+                        ON CONFLICT DO NOTHING
+                    """), {
+                        'from_id': e['from_id'], 'to_id': e['to_id'],
+                        'edge_type': e['edge_type'],
+                        'from_repo': e.get('from_repo', ''),
+                        'to_repo': e.get('to_repo', ''),
+                        'confidence': e.get('confidence', 1.0),
+                        'source': e.get('source', 'explicit'),
+                        'expires_at': e.get('expires_at_iso') or e.get('expires_at'),
+                        'fingerprint': e.get('fingerprint'),
+                        'props': props_json,
+                    })
+                    ed_ok += 1
+                except Exception:
+                    ed_fail += 1
+
+    return {
+        'ok': True, 'engine_source': src,
+        'entities_ok': ent_ok, 'entities_fail': ent_fail,
+        'edges_ok': ed_ok, 'edges_fail': ed_fail,
+        'seconds': round(time.time() - t0, 1),
+    }
+
+
+def upsert_freshness(entities: list, fingerprint_map: dict):
+    """更新 knowledge_freshness 表（增量构建依赖）。
+
+    fingerprint_map: {entity_id: content_hash}（可选, 没传则不写指纹）
+    """
+    engine, _ = _get_pg_engine()
+    if engine is None:
+        return
+    from sqlalchemy import text
+    with engine.begin() as conn:
+        for e in entities:
+            fp = fingerprint_map.get(e['id'], '')
+            conn.execute(text("""
+                INSERT INTO knowledge_freshness (entity_id, source, fingerprint, extracted_at)
+                VALUES (:id, 'java_ast', :fp, now())
+                ON CONFLICT (entity_id) DO UPDATE SET
+                    source='java_ast', fingerprint=EXCLUDED.fingerprint, extracted_at=now()
+            """), {'id': e['id'], 'fp': fp})

package/templates/qoder/scripts/domain/kg/extract/java/satoken_extractor.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+"""Sa-Token 权限提取器（@SaCheckPermission/@SaCheckRole/@SaCheckLogin）。
+
+职责: 识别 Sa-Token 权限注解 → PERMISSION 实体 + guards 边。
+本项目用 Sa-Token 不是 Spring Security, @SaCheckPermission 是真实权限点来源。
+方法级权限提取在 member_extractor, 这里是类级判定 + 常量定义。
+"""
+from __future__ import annotations
+from . import _parser as P
+from . import class_extractor as _ce
+
+# Sa-Token 权限注解
+SATOKEN_PERM = {'SaCheckPermission'}
+SATOKEN_ROLE = {'SaCheckRole'}
+SATOKEN_LOGIN = {'SaCheckLogin'}
+SATOKEN_IGNORE = {'SaIgnore'}
+SATOKEN_ALL = SATOKEN_PERM | SATOKEN_ROLE | SATOKEN_LOGIN | SATOKEN_IGNORE
+
+
+def has_satoken_guard(annotations: dict) -> bool:
+    """类/方法是否有 Sa-Token 权限注解。"""
+    return bool(set(annotations.keys()) & SATOKEN_ALL)
+
+
+def extract(root, repo_id: str, filepath: str):
+    """Sa-Token 类级提取（转发到 class_extractor, 行为一致）。
+
+    PERMISSION 实体 + guards 边在 member_extractor 的方法级遍历里产出。
+    """
+    return _ce.extract(root, repo_id, filepath)

package/templates/qoder/scripts/domain/kg/extract/java/spring_extractor.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+"""Spring 注解提取器（@RestController/@Service/@Mapper/@Autowired/@Bean）。
+
+职责: 识别 Spring 后端组件类型 + 构造器/Autowired 注入关系。
+本文件按 GOAL 2 目标要求独立拆分, 与 class_extractor.py 共享同一套提取逻辑
+(单一事实源在 class_extractor, 这里导出 Spring 相关部分)。
+"""
+from __future__ import annotations
+from . import _parser as P
+from . import class_extractor as _ce
+
+# Spring 注解集合（供外部判定用）
+SPRING_SERVICE = {'Service', 'DubboService'}
+SPRING_CONTROLLER = {'RestController', 'Controller'}
+SPRING_MAPPER = {'Mapper', 'Repository'}
+SPRING_CONFIG = {'Configuration', 'Component', 'ConfigurationProperties'}
+SPRING_INJECT = {'Autowired', 'Resource'}
+
+
+def is_spring_component(annotations: dict) -> bool:
+    """类是否带 Spring 组件注解。"""
+    keys = set(annotations.keys())
+    return bool(keys & (SPRING_SERVICE | SPRING_CONTROLLER | SPRING_MAPPER | SPRING_CONFIG))
+
+
+def classify(name: str, annotations: dict):
+    """按 Spring 注解 + 命名规则判定实体类型（与 class_extractor._classify 一致）。"""
+    return _ce._classify(name, annotations)
+
+
+# 复用 class_extractor 的完整提取入口（保证行为一致）
+def extract(root, repo_id: str, filepath: str):
+    """提取 Spring 类级实体 + 边（= class_extractor.extract 的 Spring 部分）。
+
+    实际实现见 class_extractor.extract（一次遍历识别 Spring/Dubbo/Sa-Token/MyBatis-Plus），
+    本函数等价于对结果按注解来源过滤 Spring 部分。为保证 zero-behavior-change，
+    这里直接转发到 class_extractor.extract。
+    """
+    return _ce.extract(root, repo_id, filepath)

package/templates/qoder/scripts/domain/kg/extract/java/validation_extractor.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""校验规则提取器（@NotNull/@NotBlank/@Size/@Email/@Pattern 等）。
+
+职责: 从字段注解提取校验规则 → VALIDATION 实体 + validates 边。
+按 GOAL 2 目标要求独立拆分, 共享 domain_extractor 的字段遍历逻辑
+(字段校验在 domain_extractor 处理 Entity 字段时一并产出)。
+"""
+from __future__ import annotations
+from . import _parser as P
+from . import domain_extractor as _de
+
+VALIDATION_ANN = {'NotNull', 'NotBlank', 'NotEmpty', 'Size', 'Min', 'Max',
+                  'Email', 'Pattern', 'Positive', 'Negative', 'Digits',
+                  'Past', 'Future', 'DecimalMin', 'DecimalMax'}
+
+
+def has_validation(annotations: dict) -> bool:
+    """字段是否有校验注解。"""
+    return bool(set(annotations.keys()) & VALIDATION_ANN)
+
+
+def rule_summary(annotations: dict) -> list:
+    """汇总字段的校验规则 → [{rule, arg}]。"""
+    out = []
+    for ann, arg in annotations.items():
+        if ann in VALIDATION_ANN:
+            out.append({'rule': ann, 'arg': arg})
+    return out
+
+
+def extract(root, repo_id: str, filepath: str):
+    """校验规则提取（转发到 domain_extractor, Entity 字段的校验在那里产出）。"""
+    return _de.extract(root, repo_id, filepath)

package/templates/qoder/scripts/domain/kg/extract/mybatis/__init__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""MyBatis mapper XML 提取器 (GOAL 3)。
+
+子模块:
+  mapper_parser    XML namespace + resultMap + 方法→SQL
+  sql_extractor    SQL 文本 → 表名 + 列引用
+  relation_builder Mapper ↔ Entity ↔ Table 三向关联
+  all              协调器: 扫所有 mapper XML → 提取 → 返回 (entities, edges)
+"""

package/templates/qoder/scripts/domain/kg/extract/mybatis/all.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+"""MyBatis XML 提取协调器。
+
+扫所有 *Mapper.xml → 解析 → 建关系 → 返回 (entities, edges)。
+"""
+from __future__ import annotations
+import os
+import sys
+import glob
+import time
+
+_THIS = os.path.dirname(os.path.abspath(__file__))
+for _i in range(8):
+    _p = os.path.dirname(_THIS)
+    if os.path.isfile(os.path.join(_p, 'foundation', 'bootstrap.py')):
+        sys.path.insert(0, _p); break
+    _THIS = _p
+
+from domain.kg.extract.mybatis import mapper_parser as mp
+from domain.kg.extract.mybatis import relation_builder as rb
+
+
+def extract_file(filepath: str, repo_id: str):
+    """单文件提取 → (entities, edges)。"""
+    parsed = mp.parse_mapper_xml(filepath)
+    if not parsed.get('namespace_short'):
+        return [], []
+    return rb.build_relations(parsed, repo_id, filepath)
+
+
+def extract_repo(repo_dir: str, repo_id: str, logger=print):
+    """扫 repo 下所有 mapper XML → 提取。"""
+    t0 = time.time()
+    patterns = [
+        os.path.join(repo_dir, '**', '*Mapper.xml'),
+        os.path.join(repo_dir, '**', '*mapper*.xml'),
+        os.path.join(repo_dir, '**', 'mapper', '*.xml'),
+    ]
+    xml_files = set()
+    for pat in patterns:
+        xml_files.update(glob.glob(pat, recursive=True))
+    # 跳过编译产物 target/classes 和测试资源
+    xml_files = [f for f in xml_files if '/target/' not in f.replace('\\', '/')
+                 and '\\target\\' not in f.lower()
+                 and '/test/' not in f.replace('\\', '/').lower()]
+    total = len(xml_files)
+    logger('  [mybatis] 扫描 %d 个 mapper XML (repo=%s)' % (total, repo_id))
+
+    all_entities, all_edges = [], []
+    err = 0
+    for xf in xml_files:
+        try:
+            es, eds = extract_file(xf, repo_id)
+            all_entities += es
+            all_edges += eds
+        except Exception as e:
+            err += 1
+            if err <= 2:
+                logger('  [mybatis] 失败 %s: %s' % (xf, str(e)[:50]))
+
+    dt = time.time() - t0
+    tables = set()
+    for e in all_entities:
+        if e['type'] == 'TABLE':
+            tables.add(e['canonical'])
+    logger('  [mybatis] 完成: %d 实体 / %d 边 / %d 表 / %d 错 / %.1fs' % (
+        len(all_entities), len(all_edges), len(tables), err, dt))
+    return all_entities, all_edges
+
+
+if __name__ == '__main__':
+    import argparse, json
+    ap = argparse.ArgumentParser()
+    ap.add_argument('repo_dir')
+    ap.add_argument('--repo-id', default='')
+    args = ap.parse_args()
+    rid = args.repo_id or os.path.basename(args.repo_dir.rstrip('/\\'))
+    es, eds = extract_repo(args.repo_dir, rid)
+    print(json.dumps({'entities': len(es), 'edges': len(eds)}, ensure_ascii=False, indent=2))

package/templates/qoder/scripts/domain/kg/extract/mybatis/mapper_parser.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""mapper XML 解析器: namespace + resultMap + 方法→SQL 映射。
+
+输出每个 mapper 文件的结构化信息, 供 relation_builder 建 queries 边 + COLUMN 实体。
+"""
+from __future__ import annotations
+import os
+import re
+import xml.etree.ElementTree as ET
+
+from . import sql_extractor as _sq
+
+
+def _extract_table_names(sql):
+    """从 SQL 提取表名 (转发到 sql_extractor)。"""
+    return _sq.extract_table_names(sql)
+
+
+def parse_mapper_xml(filepath: str) -> dict:
+    """解析一个 mapper XML。
+
+    Returns:
+        {
+            'namespace': 'com.fywl.ics.demo.mapper.TestDemoMapper',
+            'namespace_short': 'TestDemoMapper',
+            'statements': [{'id':'customPageList','type':'select','sql':'SELECT * FROM test_demo...', 'tables':['test_demo']}],
+            'result_maps': {'TestDemoResult': [{'property':'id','column':'id'}, ...]},
+            'result_types': ['com.fywl.ics.demo.domain.vo.TestDemoVo'],
+        }
+    """
+    try:
+        tree = ET.parse(filepath)
+        root = tree.getroot()
+    except Exception:
+        return _empty_result()
+
+    namespace = root.get('namespace', '') or ''
+    namespace_short = namespace.rsplit('.', 1)[-1] if namespace else os.path.basename(filepath).replace('.xml', '')
+
+    statements = []
+    result_maps = {}
+    result_types = set()
+
+    for tag in ('select', 'insert', 'update', 'delete'):
+        for stmt in root.findall(tag):
+            sid = stmt.get('id', '')
+            sql_text = _extract_sql_text(stmt)
+            tables = _extract_table_names(sql_text)
+            if stmt.get('resultType'):
+                result_types.add(stmt.get('resultType'))
+            statements.append({
+                'id': sid, 'type': tag, 'sql': sql_text, 'tables': tables,
+            })
+
+    for rm in root.findall('resultMap'):
+        rm_id = rm.get('id', '')
+        cols = []
+        for child_tag in ('id', 'result'):
+            for child in rm.findall(child_tag):
+                cols.append({
+                    'property': child.get('property', ''),
+                    'column': child.get('column', ''),
+                })
+        if rm.get('type'):
+            result_types.add(rm.get('type'))
+        result_maps[rm_id] = cols
+
+    return {
+        'namespace': namespace,
+        'namespace_short': namespace_short,
+        'statements': statements,
+        'result_maps': result_maps,
+        'result_types': list(result_types),
+    }
+
+
+def _extract_sql_text(node) -> str:
+    """提取 statement 节点的完整 SQL 文本（含 <if>/<foreach> 展开）。"""
+    parts = []
+    if node.text:
+        parts.append(node.text)
+    for child in node:
+        # <if>/<foreach>/<choose>/<where>/<set>/<trim> 等, 取 text + tail
+        if child.text:
+            parts.append(child.text)
+        # 递归子节点 (foreach 里可能有 if)
+        for sub in child:
+            if sub.text:
+                parts.append(sub.text)
+            if sub.tail:
+                parts.append(sub.tail)
+        if child.tail:
+            parts.append(child.tail)
+    return ' '.join(p.strip() for p in parts if p and p.strip())
+
+
+def _empty_result():
+    return {'namespace': '', 'namespace_short': '', 'statements': [],
+            'result_maps': {}, 'result_types': []}