precis-cli 0.1.3__py3-none-any.whl

app/shared/services/validation/chunked_loader.py

@@ -0,0 +1,509 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 分块数据加载器
+
+功能概述:
+- 支持大文件（>500MB）的分块读取和校验
+- 对 CSV 文件使用 pandas chunksize 分块读取
+- 对 Excel 文件按行范围分块读取
+- 每个分块独立执行约束校验，合并结果
+
+架构设计:
+- 组合模式: ChunkedDataLoader 使用 DataSourceResolver 做路径解析
+- 与 DataLoader 并行存在，由 ValidationExecutor 根据文件大小决定使用哪个
+- 分块校验结果通过 ChunkedValidationResult 聚合
+
+输入示例:
+    loader = ChunkedDataLoader(resolver, dataset_schema, schema_by_id, settings)
+    result = loader.load_and_validate_chunked(data_directory, schema, engine_fn)
+
+输出示例:
+    result = ChunkedValidationResult(
+        parsed_datasets={...},
+        errors=[...],
+        validation_details={...},
+        chunk_count=5,
+        total_rows=500000
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+import pandas as pd
+
+from app.shared.core.data_source.loaders.csv_loader import build_csv_read_kwargs
+from app.shared.core.data_source.loaders.excel_loader import apply_merged_ranges_fill, read_merged_ranges_from_xlsx
+from app.shared.core.data_source.schema_info import DataSourceInfo
+from app.shared.core.project.schema.types import TableSchemaFile
+from app.shared.domain.dataset_schema import DataSetSchema, TableSchema
+
+from .data_loader import collect_foreign_key_tables
+from .memory_monitor import MemoryMonitor
+from .resolver import DataSourceResolver
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ChunkedValidationResult:
+    """分块校验结果聚合。"""
+
+    parsed_datasets: dict[str, pd.DataFrame] = field(default_factory=dict)
+    errors: list[dict] = field(default_factory=list)
+    validation_details: dict[str, list[dict]] = field(
+        default_factory=lambda: {"format_checks": [], "constraint_checks": []}
+    )
+    loading_errors: list[dict] = field(default_factory=list)
+    chunk_count: int = 0
+    total_rows: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+
+class ChunkedDataLoader:
+    """
+    @classdesc 分块数据加载器
+
+    负责：
+    - 对大文件进行分块读取
+    - 每个分块独立执行格式解析和约束校验
+    - 聚合所有分块的校验结果
+
+    设计决策：
+    - CSV 使用 pandas read_csv(chunksize=...) 流式读取
+    - Excel 按行范围分块读取（pandas read_excel + skiprows/nrows）
+    - JSON 不支持分块（需全量加载），但仍可对加载后的 DataFrame 分块校验
+    """
+
+    def __init__(
+        self,
+        resolver: DataSourceResolver,
+        dataset_schema: DataSetSchema,
+        schema_by_id: dict[str, TableSchemaFile],
+        settings: Any,
+        memory_monitor: MemoryMonitor | None = None,
+    ):
+        self._resolver = resolver
+        self.dataset_schema = dataset_schema
+        self._schema_by_id = schema_by_id
+        self.settings = settings
+        self._monitor = memory_monitor or MemoryMonitor()
+
+    def _load_csv_chunked(
+        self,
+        file_path: str,
+        schema: TableSchema,
+        chunk_size: int,
+    ) -> list[pd.DataFrame]:
+        """
+        @methoddesc 分块加载 CSV 文件
+
+        使用 pandas read_csv 的 chunksize 参数进行流式读取。
+
+        参数:
+            file_path: CSV 文件路径
+            schema: 表 Schema 定义
+            chunk_size: 每个分块的行数
+
+        返回:
+            DataFrame 分块列表
+        """
+        try:
+            # A2 修复：与标准 CSVLoader 共用 read_kwargs 构造（含 utf-8→utf-8-sig BOM 升级、
+            # quotechar/on_bad_lines/escapechar/skiprows 透传）。schema.source_config 是
+            # SourceSpec.to_loader_config() 的产物，恒含 encoding 真值（默认 "utf-8"），
+            # 过去 `or "utf-8-sig"` 兜底永不生效 → BOM 不剥、首列变 \ufeffxxx。
+            # 注意：CSVOptions 无 nrows 字段，分块路径不发明 nrows 支持。
+            source_config = getattr(schema, "source_config", None) or {}
+
+            # on_bad_lines 来自自由字典，按标准路径的白名单收窄，非法值兜底 "error"
+            # （与 CSVSourceSpec/CSVOptions 默认值同口径：坏行静默跳过=校验工具漏报），
+            # 避免把任意字符串透传给 pandas.read_csv 导致加载失败
+            on_bad_lines = source_config.get("on_bad_lines")
+            if on_bad_lines not in ("error", "warn", "skip"):
+                on_bad_lines = "error"
+
+            read_kwargs = build_csv_read_kwargs(
+                header_row=schema.header_row if schema.header_row is not None else 0,
+                encoding=source_config.get("encoding") or "utf-8",
+                delimiter=source_config.get("delimiter", ","),
+                quotechar=source_config.get("quotechar", '"'),
+                on_bad_lines=on_bad_lines,
+                escapechar=source_config.get("escapechar"),
+                skip_rows=int(source_config.get("skip_rows", 0) or 0),
+            )
+            read_kwargs["chunksize"] = chunk_size
+
+            chunks: list[pd.DataFrame] = []
+            for chunk in pd.read_csv(file_path, **read_kwargs):
+                chunks.append(chunk)
+
+            logger.info(f"CSV 分块加载完成: {os.path.basename(file_path)}, {len(chunks)} 个分块")
+            return chunks
+
+        except Exception as e:
+            logger.error(f"CSV 分块加载失败: {file_path}, 错误: {e}")
+            raise
+
+    def _load_excel_chunked(
+        self,
+        file_path: str,
+        sheet_name: str,
+        header_row: int,
+        chunk_size: int,
+    ) -> list[pd.DataFrame]:
+        """
+        @methoddesc 分块加载 Excel 文件
+
+        Excel 不支持原生 chunksize，通过多次调用 read_excel（skiprows + nrows）实现分块。
+
+        参数:
+            file_path: Excel 文件路径
+            sheet_name: Sheet 名称
+            header_row: 表头行号
+            chunk_size: 每个分块的行数
+
+        返回:
+            DataFrame 分块列表
+        """
+        try:
+            # 先读取表头确定列数
+            header_df = pd.read_excel(
+                file_path,
+                sheet_name=sheet_name,
+                header=header_row,
+                nrows=0,
+            )
+            columns = header_df.columns.tolist()
+
+            if not columns:
+                logger.warning(f"Excel 文件无列: {file_path}, sheet={sheet_name}")
+                return []
+
+            # §1.27: 分块路径补 B7 同构的合并单元格前向填充（一次 openpyxl 读取 merged ranges，
+            # 每块读出后按"区域首行在本块内"填充；跨块悬挂区域跳过并累计告警）。
+            # 与标准路径（excel_loader._apply_merged_cell_fill）共用 apply_merged_ranges_fill
+            # 单一事实源，防止两条路径语义再漂移。读取失败降级为不填充（照 B27 惯例留诊断日志）。
+            merged_ranges = self._read_excel_merged_ranges(file_path, sheet_name)
+
+            chunks: list[pd.DataFrame] = []
+            current_skip = header_row + 1  # 跳过表头行
+            # 回归 #8: 累计已读数据行数(不含表头),用于给每块设置全局连续的 0-based 数据行号,
+            # 使约束校验的 row_index 反映行在原文件的真实数据位置(与 CSV 分块的全局连续 index 对齐)。
+            data_row_offset = 0
+            skipped_cross_total = 0
+
+            while True:
+                read_kwargs: dict[str, Any] = {
+                    "sheet_name": sheet_name,
+                    "header": None,
+                    "skiprows": current_skip,
+                    "nrows": chunk_size,
+                }
+
+                chunk = pd.read_excel(file_path, **read_kwargs)
+
+                if chunk.empty:
+                    break
+
+                # 设置列名
+                if len(chunk.columns) == len(columns):
+                    chunk.columns = columns
+
+                if merged_ranges is not None:
+                    chunk, _filled, skipped_cross = apply_merged_ranges_fill(
+                        chunk,
+                        merged_ranges,
+                        header_row=header_row,
+                        skip_rows=0,
+                        global_row_offset=data_row_offset,
+                    )
+                    skipped_cross_total += skipped_cross
+
+                # 回归 #8: 把块内 index 重置为全局连续的数据行号(从 data_row_offset 开始),
+                # 而非 pd.read_excel 默认的每块从 0 重启的 RangeIndex。否则第 2 块起 row_index
+                # 与原文件位置错位,财务/审计场景无法据报告行号定位错误。
+                chunk.index = range(data_row_offset, data_row_offset + len(chunk))
+
+                chunks.append(chunk)
+                current_skip += chunk_size
+                data_row_offset += len(chunk)
+
+                # 如果返回的行数小于 chunk_size，说明已到文件末尾
+                if len(chunk) < chunk_size:
+                    break
+
+            if skipped_cross_total > 0:
+                logger.warning(
+                    "分块 Excel 合并单元格填充：%d 个合并区域跨越分块边界，其跨块部分未填充"
+                    "（区域首行所在块已填充该块内部分），可能产生少量 NotNull 误报，file=%s",
+                    skipped_cross_total,
+                    file_path,
+                )
+
+            logger.info(f"Excel 分块加载完成: {os.path.basename(file_path)}, {len(chunks)} 个分块")
+            return chunks
+
+        except Exception as e:
+            logger.error(f"Excel 分块加载失败: {file_path}, 错误: {e}")
+            raise
+
+    @staticmethod
+    def _read_excel_merged_ranges(file_path: str, sheet_name: str) -> Any:
+        """一次性读取 sheet 的合并单元格区域及其首行值（§1.27），供分块填充复用。
+
+        返回 (min_row, min_col, max_row, max_col, values) 五元组列表——values 为区域
+        首行各列的值，使跨块悬挂区域能直接赋值续填（合并单元格区域内所有格本就同值）。
+        任何失败降级返回 None（调用方跳过填充，与 B27 降级语义一致——填充是尽力而为的增强）。
+
+        2026-09-20 修复：改用 excel_loader.read_merged_ranges_from_xlsx
+        （zipfile+ElementTree 流式解析）。此前 openpyxl 普通模式 load_workbook 会把
+        全部 sheet 的 Cell 对象图整体物化（read_only 模式的 ReadOnlyWorksheet 无
+        merged_cells 属性才退而用普通模式）——0.5MB/15 万格实测峰值 55MB vs
+        read_only ≈0MB（~120 倍放大），恰好落在 >500MB 分块阈值场景上。
+        """
+        try:
+            return read_merged_ranges_from_xlsx(file_path, sheet_name)
+        except Exception as e:
+            logger.warning(f"分块 Excel 合并单元格区域读取失败，跳过填充（可能导致 NotNull 误报）: {file_path}: {e}")
+            return None
+
+    def _load_dataframe_chunked(
+        self,
+        file_path: str,
+        schema: TableSchema,
+        chunk_size: int,
+    ) -> list[pd.DataFrame]:
+        """
+        @methoddesc 根据文件类型选择分块加载策略
+
+        参数:
+            file_path: 数据文件路径
+            schema: 表 Schema 定义
+            chunk_size: 每个分块的行数
+
+        返回:
+            DataFrame 分块列表
+        """
+        ext = os.path.splitext(file_path)[1].lower()
+
+        if ext == ".csv":
+            return self._load_csv_chunked(file_path, schema, chunk_size)
+        elif ext in (".xlsx", ".xls"):
+            sheet_name = getattr(schema, "sheet_name", None) or "Sheet1"
+            header_row = getattr(schema, "header_row", 0) or 0
+            return self._load_excel_chunked(file_path, sheet_name, header_row, chunk_size)
+        else:
+            # JSON 等格式不支持分块，全量加载后按行切分
+            logger.info(f"文件格式 {ext} 不支持原生分块加载，将全量加载后切分")
+            from app.shared.core.data_source.loader import _LOADER_FNS
+
+            loader_fn = _LOADER_FNS.get(ext)
+            if not loader_fn:
+                raise ValueError(f"不支持的文件格式: {ext}")
+
+            info = DataSourceInfo(
+                schema_id=getattr(schema, "id", None) or getattr(schema, "name", None) or "",
+                name=getattr(schema, "name", None),
+                sheet_name=getattr(schema, "sheet_name", None),
+                header_row=getattr(schema, "header_row", 0),
+                source_config=getattr(schema, "source_config", {}),
+            )
+            full_datasets = loader_fn(file_path, [info])
+            if not full_datasets:
+                return []
+
+            # 取第一个 DataFrame 进行分块切分
+            df = next(iter(full_datasets.values()))
+            return [df[i : i + chunk_size] for i in range(0, len(df), chunk_size)]
+
+    def load_chunked_sources(
+        self,
+        data_directory: str,
+        table_filter: str | list[str] | None = None,
+    ) -> tuple[dict[str, list[pd.DataFrame]], list[dict]]:
+        """
+        @methoddesc 分块加载所有数据源
+
+        对需要分块的大文件进行分块读取，小文件返回单个分块。
+
+        参数:
+            data_directory: 数据文件所在目录
+            table_filter: 表过滤条件
+
+        返回:
+            二元组 (datasets, loading_errors):
+            - datasets: 键为表 ID，值为 DataFrame 分块列表
+            - loading_errors: 加载阶段产生的错误列表（源找不到、加载异常等），
+              供 executor 上报到校验报告。回归 #5: 原实现吞掉所有错误导致损坏表静默消失。
+        """
+        chunked_datasets: dict[str, list[pd.DataFrame]] = {}
+        loading_errors: list[dict] = []
+        # Excel 回退 sheet 名映射：与 data_loader 的标准模式保持一致，
+        # schema 未显式指定 sheet_name 时作为加载回退
+        file_to_sheet_names: dict[str, str] = {}
+
+        # 解析搜索目录
+        search_directory = data_directory
+        first_data_source = self._resolver.resolve_first_data_source()
+        if first_data_source:
+            search_directory = first_data_source
+
+        if not os.path.isdir(search_directory):
+            logger.error(f"数据目录不存在: {data_directory}")
+            return chunked_datasets, loading_errors
+
+        # 处理过滤
+        filter_set: set | None = None
+        if table_filter:
+            if isinstance(table_filter, str):
+                filter_set = {table_filter}
+            else:
+                filter_set = set(table_filter)
+
+        # A3 修复: 与 data_loader 标准路径一致，过滤时必须把 FK 目标表并入加载集。
+        # 否则按 A 过滤时 B 不加载，FK 校验因目标表缺失误报「表不在提供的数据集中」。
+        tables_to_load: set | None = None
+        if filter_set:
+            tables_to_load = collect_foreign_key_tables(self.dataset_schema, filter_set)
+
+        for table_id, table_schema in self.dataset_schema.tables.items():
+            schema_file = self._schema_by_id.get(table_id)
+            if not schema_file:
+                continue
+
+            # 应用过滤
+            if tables_to_load:
+                table_name = table_schema.name or table_id
+                if table_name not in tables_to_load and table_id not in tables_to_load:
+                    continue
+
+            table_name = table_schema.name or table_id
+
+            # 解析数据源路径（第二个返回值是 Excel sheet 名，用于构建回退映射）
+            source_path, sheet_name_resolved = self._resolver.resolve_source_path(data_directory, schema_file)
+            if not source_path:
+                # 回归 #5: 源找不到必须上报,否则该表静默消失、报告显示"全部通过"。
+                logger.warning(f"表 '{table_name}' 未找到数据源，跳过分块加载")
+                loading_errors.append(
+                    {
+                        "error_type": "SourceNotFound",
+                        "table": table_name,
+                        "message": f"表 '{table_name}' 未找到数据源，已跳过分块加载。",
+                    }
+                )
+                continue
+
+            if sheet_name_resolved:
+                file_to_sheet_names.setdefault(source_path, sheet_name_resolved)
+
+            # 判断是否需要分块
+            if self._monitor.should_chunk(source_path):
+                self._monitor.take_snapshot(source_path)
+                logger.info(f"表 '{table_name}' 文件较大，启用分块加载模式")
+
+                try:
+                    chunks = self._load_dataframe_chunked(source_path, table_schema, self._monitor.chunk_rows)
+                    chunked_datasets[table_id] = chunks
+                except Exception as e:
+                    logger.error(f"分块加载失败: {table_id}, 错误: {e}")
+                    # 回退到全量加载
+                    logger.info(f"回退到全量加载: {table_id}")
+                    try:
+                        from app.shared.core.data_source.loader import load_grouped_sources
+
+                        info = DataSourceInfo(
+                            schema_id=table_id,
+                            name=getattr(table_schema, "name", table_id),
+                            sheet_name=getattr(table_schema, "sheet_name", None),
+                            header_row=getattr(table_schema, "header_row", 0),
+                            source_config=getattr(table_schema, "source_config", None) or {},
+                        )
+                        file_to_schemas = {source_path: [info]}
+                        # 与 data_loader 标准模式对齐：透传 manifest 级编码/分隔符默认值与 sheet 回退映射
+                        loaded, _ = load_grouped_sources(
+                            file_to_schemas,
+                            default_encoding=self.settings.file_processing.default_encoding,
+                            csv_delimiter=self.settings.file_processing.csv_delimiter,
+                            file_to_sheet_names=file_to_sheet_names or None,
+                        )
+                        if loaded:
+                            df = next(iter(loaded.values()))
+                            chunked_datasets[table_id] = [df]
+                        else:
+                            loading_errors.append(
+                                {
+                                    "error_type": "DataLoadingError",
+                                    "table": table_name,
+                                    "message": f"表 '{table_name}' 分块加载及全量回退均未返回数据。",
+                                }
+                            )
+                    except Exception as fallback_err:
+                        logger.error(f"全量加载也失败: {table_id}, 错误: {fallback_err}")
+                        loading_errors.append(
+                            {
+                                "error_type": "DataLoadingError",
+                                "table": table_name,
+                                "message": f"表 '{table_name}' 加载失败: 分块错误({e}); 全量回退错误({fallback_err})。",
+                            }
+                        )
+            else:
+                # 小文件，全量加载为单个分块
+                try:
+                    from app.shared.core.data_source.loader import load_grouped_sources
+
+                    info = DataSourceInfo(
+                        schema_id=table_id,
+                        name=getattr(table_schema, "name", table_id),
+                        sheet_name=getattr(table_schema, "sheet_name", None),
+                        header_row=getattr(table_schema, "header_row", 0),
+                        source_config=getattr(table_schema, "source_config", None) or {},
+                    )
+                    file_to_schemas = {source_path: [info]}
+                    # 与 data_loader 标准模式对齐：透传 manifest 级编码/分隔符默认值与 sheet 回退映射
+                    loaded, _ = load_grouped_sources(
+                        file_to_schemas,
+                        default_encoding=self.settings.file_processing.default_encoding,
+                        csv_delimiter=self.settings.file_processing.csv_delimiter,
+                        file_to_sheet_names=file_to_sheet_names or None,
+                    )
+                    if loaded:
+                        df = next(iter(loaded.values()))
+                        chunked_datasets[table_id] = [df]
+                    else:
+                        loading_errors.append(
+                            {
+                                "error_type": "DataLoadingError",
+                                "table": table_name,
+                                "message": f"表 '{table_name}' 加载未返回数据。",
+                            }
+                        )
+                except Exception as e:
+                    logger.error(f"加载失败: {table_id}, 错误: {e}")
+                    loading_errors.append(
+                        {
+                            "error_type": "DataLoadingError",
+                            "table": table_name,
+                            "message": f"表 '{table_name}' 加载失败: {e}",
+                        }
+                    )
+
+        return chunked_datasets, loading_errors

app/shared/services/validation/dag/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview DAG 执行包
+
+导出:
+- build_transform_dag: 构建 Transform DAG
+- topological_sort: 拓扑排序
+- execute_transform_dag: 执行 DAG
+"""
+
+from .builder import ExecutionDAG, build_execution_dag, build_transform_dag
+from .executor import execute_transform_dag
+from .sorter import topological_sort
+
+__all__ = [
+    "ExecutionDAG",
+    "build_execution_dag",
+    "build_transform_dag",
+    "topological_sort",
+    "execute_transform_dag",
+]

app/shared/services/validation/dag/builder.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview DAG 构建器
+
+功能概述:
+- 从 TransformFile 列表构建有向无环图（DAG）
+- 节点 = transform 或 schema（数据源）
+- 边 = input_from_node 依赖关系
+
+架构设计:
+- 节点类型: "schema" | "transform"
+- 使用邻接表表示图结构
+- 支持检测循环依赖
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from app.shared.core.project.regex.types import RegexNodeFile
+from app.shared.core.project.transform.types import TransformFile
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DAGNode:
+    """@classdesc DAG 节点"""
+
+    id: str
+    node_type: str  # "schema" | "transform"
+    data: Any = None  # TransformFile 或 schema 标识
+    incoming: list[str] = field(default_factory=list)
+    outgoing: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ExecutionDAG:
+    """@classdesc 执行 DAG"""
+
+    nodes: dict[str, DAGNode] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+def build_execution_dag(
+    transform_files: dict[str, TransformFile],
+    schema_ids: set[str],
+    regex_files: dict[str, RegexNodeFile] | None = None,
+) -> ExecutionDAG:
+    """@methoddesc 从 Transform 和 Regex 文件构建执行 DAG
+
+    参数:
+        transform_files: {transform_id: TransformFile}
+        schema_ids: 所有 schema 表 ID 集合
+        regex_files: {regex_id: RegexNodeFile}，仅 match_mode="extract" 的节点会被加入 DAG
+
+    返回:
+        ExecutionDAG 实例
+    """
+    dag = ExecutionDAG()
+
+    # 1. 注册所有 transform 节点
+    for tid, tfile in transform_files.items():
+        if not tfile.enabled:
+            continue
+        dag.nodes[tid] = DAGNode(
+            id=tid,
+            node_type="transform",
+            data=tfile,
+        )
+
+    # 2. 注册所有 schema 数据源节点（虚拟节点，用于连接）
+    for sid in schema_ids:
+        dag.nodes[sid] = DAGNode(
+            id=sid,
+            node_type="schema",
+            data=None,
+        )
+
+    # 3. 注册 extract 模式的 regex 节点
+    if regex_files:
+        for rid, rfile in regex_files.items():
+            if not rfile.enabled or rfile.match_mode != "extract":
+                continue
+            dag.nodes[rid] = DAGNode(
+                id=rid,
+                node_type="regex",
+                data=rfile,
+            )
+
+    # 4. 建立边（input_from_node → node）
+    dangling_nodes: list[str] = []
+    for tid, tfile in transform_files.items():
+        if not tfile.enabled:
+            continue
+        input_node = tfile.input_from_node
+        if input_node and input_node in dag.nodes:
+            dag.nodes[tid].incoming.append(input_node)
+            dag.nodes[input_node].outgoing.append(tid)
+        elif input_node and input_node not in dag.nodes:
+            logger.warning("[DAG] Transform '%s' 的上游节点 '%s' 不存在（悬空依赖）", tid, input_node)
+            dangling_nodes.append(f"{tid} -> {input_node}")
+
+    if regex_files:
+        for rid, rfile in regex_files.items():
+            if not rfile.enabled or rfile.match_mode != "extract":
+                continue
+            input_node = rfile.input_from_node
+            if not input_node and rfile.source_ref:
+                input_node = rfile.source_ref.table_id
+            if input_node and input_node in dag.nodes:
+                dag.nodes[rid].incoming.append(input_node)
+                dag.nodes[input_node].outgoing.append(rid)
+            elif input_node and input_node not in dag.nodes:
+                logger.warning("[DAG] Regex '%s' 的上游节点 '%s' 不存在（悬空依赖）", rid, input_node)
+                dangling_nodes.append(f"{rid} -> {input_node}")
+
+    if dangling_nodes:
+        dag.metadata["dangling_nodes"] = dangling_nodes
+
+    return dag
+
+
+# 向后兼容别名
+build_transform_dag = build_execution_dag