precis-cli 0.1.3__py3-none-any.whl

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

@@ -0,0 +1,225 @@
+# 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 执行器
+
+功能概述:
+- 按拓扑顺序执行 DAG 中的 transform 节点
+- 管理每个节点的输出 DataFrame
+- 将 transform 结果写回 parsed_datasets
+
+数据流:
+    schema 数据源 → [transform] → [transform] → ...
+    每个节点的输出 DataFrame 存储在 node_outputs 中
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+import pandas as pd
+
+from app.shared.core.project.regex.types import RegexNodeFile
+from app.shared.core.project.transform.types import TransformFile
+from app.shared.domain.regex_flags import parse_regex_flags
+from app.shared.domain.transforms import create_runner
+
+from .builder import ExecutionDAG
+from .sorter import topological_sort
+
+logger = logging.getLogger(__name__)
+
+
+def execute_transform_dag(
+    dag: ExecutionDAG,
+    parsed_datasets: dict[str, pd.DataFrame],
+) -> tuple[dict[str, pd.DataFrame], list[dict]]:
+    """@methoddesc 执行 Transform DAG
+
+    参数:
+        dag: 执行 DAG（包含 transform 和 schema 节点）
+        parsed_datasets: 已解析的 DataFrame 字典（键为 schema 表 ID）
+
+    返回:
+        二元组 (parsed_datasets, dag_errors):
+        - parsed_datasets: 更新后的 DataFrame 字典（包含 transform 产生的新列）
+        - dag_errors: 节点执行失败产生的错误列表（含节点 ID、类型、原因）。
+          回归 #6: 原实现 transform/regex 节点执行异常仅 logger.exception 后把未转换的
+          输入复制为输出继续,execute_transform_dag 无错误返回通道,engine 无从感知 →
+          下游约束在未转换数据上"假通过"。现在把失败上报给调用方。
+    """
+    if not dag.nodes:
+        return parsed_datasets, []
+
+    order = topological_sort(dag)
+    dag_errors: list[dict] = []
+
+    # 使用单一数据源：node_outputs 既是下游输入也是最终结果
+    # schema 节点直接引用 parsed_datasets 中的 DataFrame（延迟 copy，按需隔离）
+    node_outputs: dict[str, pd.DataFrame] = {}
+    schema_ids_in_dag: set[str] = set()
+
+    for sid, df in parsed_datasets.items():
+        if sid in dag.nodes:
+            node_outputs[sid] = df
+            schema_ids_in_dag.add(sid)
+
+    for node_id in order:
+        node = dag.nodes[node_id]
+        if node.node_type == "schema":
+            continue
+
+        if node.node_type == "transform":
+            tfile: TransformFile = node.data
+            if not tfile or not tfile.enabled:
+                continue
+
+            input_node_id = tfile.input_from_node or node_id
+            input_df = node_outputs.get(input_node_id)
+
+            if input_df is None:
+                logger.warning(f"Transform '{node_id}' 的输入节点 '{input_node_id}' 无可用数据，跳过")
+                continue
+
+            input_column = tfile.input_column
+            if input_column and input_column not in input_df.columns:
+                logger.warning(f"Transform '{node_id}' 的输入列 '{input_column}' 不存在，跳过")
+                continue
+
+            try:
+                runner = create_runner(tfile.type)
+                output_df = runner.execute(
+                    input_df.copy(),
+                    input_column or input_df.columns[0],
+                    tfile.params,
+                    tfile.output_columns,
+                )
+                node_outputs[node_id] = output_df
+
+                # 将 transform 结果合并回输入节点的输出
+                # 统一通过 node_outputs 操作，消除双数据源同步问题
+                if input_node_id in node_outputs:
+                    existing_df = node_outputs[input_node_id]
+                    if len(output_df) != len(existing_df):
+                        # 行数改变（如 FilterRows/DropDuplicates/Aggregate）：整体替换
+                        node_outputs[input_node_id] = output_df.copy()
+                    elif list(output_df.columns) == list(existing_df.columns):
+                        # 回归 #7: output_df 列与输入完全一致 → 这是行级整表操作(如 SortRows
+                        # 重排行、不产生新列)。原实现按 output_columns 循环贴回:
+                        #   - output_columns 为空(SortRows 正确用法)→ 循环不执行 → 排序结果
+                        #     永远写不回,校验的是未排序数据;
+                        #   - output_columns 误填 → output_df[col].values 按位置贴回未排序行 →
+                        #     行数据错配(id 与 val 对不上)。
+                        # 行顺序已变的整表操作必须整体替换,不能按列贴回。
+                        node_outputs[input_node_id] = output_df.copy()
+                    else:
+                        # 行数不变且产出新列（如 StringSplit/MathExpr 派生列）：按列贴回
+                        # 如果 existing_df 与 parsed_datasets 共享引用，先隔离再修改
+                        if input_node_id in schema_ids_in_dag:
+                            existing_df = existing_df.copy()
+                            node_outputs[input_node_id] = existing_df
+                            schema_ids_in_dag.discard(input_node_id)
+                        for col in tfile.output_columns:
+                            if col in output_df.columns:
+                                existing_df[col] = output_df[col].values
+            except Exception as e:
+                logger.exception(f"Transform '{node_id}' 执行失败: {e}")
+                node_outputs[node_id] = input_df.copy()
+                dag_errors.append(
+                    {
+                        "error_type": "TransformExecutionError",
+                        "node_id": node_id,
+                        "node_type": "transform",
+                        "message": f"Transform '{node_id}' 执行失败: {e}",
+                    }
+                )
+
+        elif node.node_type == "regex":
+            rfile: RegexNodeFile = node.data
+            if not rfile or not rfile.enabled:
+                continue
+
+            input_node_id = rfile.input_from_node or ""
+            if not input_node_id and rfile.source_ref:
+                input_node_id = rfile.source_ref.table_id
+
+            input_df = node_outputs.get(input_node_id) if input_node_id else None
+            if input_df is None:
+                logger.warning(f"Regex '{node_id}' 的输入节点无可用数据，跳过")
+                continue
+
+            input_column = rfile.input_column or rfile.source_column_name
+            if not input_column or input_column not in input_df.columns:
+                logger.warning(f"Regex '{node_id}' 的输入列 '{input_column}' 不存在，跳过")
+                continue
+
+            pattern_str = rfile.pattern
+            if not pattern_str:
+                logger.warning(f"Regex '{node_id}' 未配置直接模式 pattern（uses_pattern 暂不支持 DAG 执行），跳过")
+                continue
+
+            try:
+                # 透传 rfile.flags / case_sensitive（过去完全忽略，导致大小写等配置在 DAG 提取时失效）
+                re_flags = parse_regex_flags(getattr(rfile, "flags", "") or "")
+                if getattr(rfile, "case_sensitive", True) is False:
+                    re_flags |= re.IGNORECASE
+
+                compiled = re.compile(pattern_str, re_flags)
+                extracted = input_df[input_column].astype(str).str.extract(compiled)
+                output_df = input_df.copy()
+                # 按位置映射 output_columns 到 extracted 列（支持无名捕获组）
+                for i, col in enumerate(rfile.output_columns or []):
+                    if i < len(extracted.columns):
+                        output_df[col] = extracted.iloc[:, i].values
+                node_outputs[node_id] = output_df
+
+                # 将提取的列合并回输入节点的输出
+                if input_node_id in node_outputs:
+                    existing_df = node_outputs[input_node_id]
+                    # 如果与 parsed_datasets 共享引用，先隔离再修改
+                    if input_node_id in schema_ids_in_dag:
+                        existing_df = existing_df.copy()
+                        node_outputs[input_node_id] = existing_df
+                        schema_ids_in_dag.discard(input_node_id)
+                    for col in rfile.output_columns or []:
+                        if col in output_df.columns:
+                            existing_df[col] = output_df[col].values
+            except Exception as e:
+                # 提示面向用户：用节点名而非 UUID 定位，并给出人话成因与修法，
+                # Python 原始报错保留在 cause 位置供高级用户排查
+                regex_display = getattr(rfile, "name", "") or node_id
+                logger.exception(f"Regex '{node_id}' 执行失败: {e}")
+                node_outputs[node_id] = input_df.copy()
+                dag_errors.append(
+                    {
+                        "error_type": "RegexExecutionError",
+                        "node_id": node_id,
+                        "node_type": "regex",
+                        "message": (
+                            f"正则「{regex_display}」执行失败：{e}。"
+                            "通常是它的匹配规则写法有误（例如命名分组的名字不能是纯数字），"
+                            "请修改该正则的匹配规则后重新校验"
+                        ),
+                    }
+                )
+
+    # 最终：将 node_outputs 中 schema 节点的结果写回 parsed_datasets
+    for sid in parsed_datasets:
+        if sid in node_outputs:
+            parsed_datasets[sid] = node_outputs[sid]
+
+    return parsed_datasets, dag_errors

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

@@ -0,0 +1,77 @@
+# 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 进行拓扑排序
+- 使用 Kahn 算法（基于入度）
+- 检测循环依赖
+
+使用示例:
+    order = topological_sort(dag)
+    # order = ["schema_1", "transform_a", "transform_b", "transform_c"]
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+from .builder import ExecutionDAG
+
+
+def topological_sort(dag: ExecutionDAG) -> list[str]:
+    """@methoddesc 对 DAG 进行拓扑排序
+
+    使用 Kahn 算法，按入度为零的顺序输出节点。
+
+    参数:
+        dag: 执行 DAG
+
+    返回:
+        节点 ID 的拓扑排序列表
+
+    异常:
+        ValueError: 存在循环依赖时抛出
+    """
+    # 计算每个节点的入度
+    in_degree: dict[str, int] = {}
+    for node_id, node in dag.nodes.items():
+        in_degree[node_id] = len(node.incoming)
+
+    # 初始化队列，放入所有入度为 0 的节点
+    queue: deque[str] = deque()
+    for node_id, degree in in_degree.items():
+        if degree == 0:
+            queue.append(node_id)
+
+    result: list[str] = []
+
+    while queue:
+        current = queue.popleft()
+        result.append(current)
+
+        for neighbor in dag.nodes[current].outgoing:
+            in_degree[neighbor] -= 1
+            if in_degree[neighbor] == 0:
+                queue.append(neighbor)
+
+    if len(result) != len(dag.nodes):
+        # 存在循环依赖
+        unresolved = [nid for nid in dag.nodes if nid not in result]
+        raise ValueError(f"Transform DAG 存在循环依赖，无法完成拓扑排序。未解决节点: {unresolved}")
+
+    return result

app/shared/services/validation/data_loader.py

@@ -0,0 +1,231 @@
+# 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 数据加载器
+
+功能概述:
+- 按解析后的文件路径分组 Schema，支持同一 Excel 多 sheet 加载
+- 支持表过滤（table_filter）及外键关联表自动收集
+- 批量加载数据文件并返回原始 DataFrame 字典
+- 收集加载过程中的错误（如目录不存在、数据源未找到）
+
+架构设计:
+- 单一职责模式: 只做数据加载，不涉及校验逻辑
+- 组合依赖 DataSourceResolver 做路径解析
+- 从 ValidationExecutor 中提取，独立为可复用组件
+
+输入示例:
+    loader = DataLoader(resolver, dataset_schema, schema_by_id, settings)
+    raw_datasets, errors = loader.load_data_sources("./data", table_filter=["users"])
+
+输出示例:
+    raw_datasets = {"users": pd.DataFrame(...), "orders": pd.DataFrame(...)}
+    errors = [{"error_type": "SourceNotFound", "message": "...", "table": "..."}]
+"""
+
+import logging
+import os
+from collections import defaultdict
+from typing import Any
+
+import pandas as pd
+
+from app.shared.core.data_source.loader import load_grouped_sources
+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
+
+from .resolver import DataSourceResolver
+
+logger = logging.getLogger(__name__)
+
+
+def collect_foreign_key_tables(dataset_schema: DataSetSchema, filter_set: set) -> set:
+    """@methoddesc 收集外键关联表（标准/分块两条加载路径共用，A3）
+
+    当指定了 table_filter 时，除了过滤表本身，
+    还需要加载这些表引用的外键目标表，否则外键约束无法校验。
+
+    参数:
+        dataset_schema: 数据集 schema（读取 constraints 列表）
+        filter_set: 用户指定的过滤表集合
+
+    返回:
+        扩展后的表集合（包含外键引用的目标表）
+    """
+    tables_to_load = set(filter_set)
+    for constraint in dataset_schema.constraints:
+        # ForeignKeyConstraints 使用 from_table 而非 table 属性
+        constraint_table = getattr(constraint, "from_table", None)
+        if constraint_table and constraint_table in filter_set:
+            if hasattr(constraint, "to_table") and constraint.to_table:
+                tables_to_load.add(constraint.to_table)
+            if hasattr(constraint, "reference_table") and constraint.reference_table:
+                tables_to_load.add(constraint.reference_table)
+    return tables_to_load
+
+
+class DataLoader:
+    """
+    @classdesc 数据加载器
+
+    负责：
+    - 按解析后的文件路径分组 Schema（支持同一 Excel 多 sheet）
+    - 表过滤（table_filter）及外键关联表自动收集
+    - 批量加载数据文件并返回原始 DataFrame 字典
+
+    设计决策：
+    - 从 ValidationExecutor 中提取，单一职责：只做数据加载，不涉及校验
+    - 通过组合依赖 DataSourceResolver 做路径解析
+    """
+
+    def __init__(
+        self,
+        resolver: DataSourceResolver,
+        dataset_schema: DataSetSchema,
+        schema_by_id: dict[str, TableSchemaFile],
+        settings: Any,
+    ):
+        self._resolver = resolver
+        self.dataset_schema = dataset_schema
+        self._schema_by_id = schema_by_id
+        self.settings = settings
+
+    def _resolve_search_directory(self, data_directory: str) -> str:
+        """
+        @methoddesc 解析实际的数据搜索目录
+
+        如果 manifest 中配置了数据源目录，优先使用配置目录；
+        否则使用传入的数据目录。
+
+        参数:
+            data_directory: 默认数据目录
+
+        返回:
+            实际用于搜索数据文件的目录路径
+        """
+        search_directory = data_directory
+        first_data_source = self._resolver.resolve_first_data_source()
+        if first_data_source:
+            search_directory = first_data_source
+        return search_directory
+
+    def _collect_foreign_key_tables(self, filter_set: set) -> set:
+        """@methoddesc 收集外键关联表（委托给模块级 collect_foreign_key_tables，
+        分块加载路径共用同一逻辑）。"""
+        return collect_foreign_key_tables(self.dataset_schema, filter_set)
+
+    def load_data_sources(
+        self,
+        data_directory: str,
+        table_filter: str | list[str] | None = None,
+    ) -> tuple[dict[str, pd.DataFrame], list[dict]]:
+        """
+        @methoddesc 批量加载数据文件
+
+        按照 Schema 定义，解析并加载所有需要的数据文件。
+        支持同一 Excel 文件多 Sheet 的批量加载优化。
+
+        参数:
+            data_directory: 数据文件所在目录
+            table_filter: 表过滤条件，只加载指定表及其外键关联表
+
+        返回:
+            (原始数据集字典, 加载错误列表) 元组
+        """
+        raw_datasets: dict[str, pd.DataFrame] = {}
+        loading_errors: list[dict] = []
+
+        # Step 1: 解析实际搜索目录
+        search_directory = self._resolve_search_directory(data_directory)
+
+        # 检查目录是否存在
+        if not os.path.isdir(search_directory):
+            loading_errors.append(
+                {
+                    "error_type": "DirectoryNotFound",
+                    "message": f"数据目录不存在: {data_directory}",
+                    "source_path": data_directory,
+                }
+            )
+            return {}, loading_errors
+
+        # Step 2: 处理表过滤条件
+        filter_set: set | None = None
+        if table_filter:
+            if isinstance(table_filter, str):
+                filter_set = {table_filter}
+            else:
+                filter_set = set(table_filter)
+
+        # 收集需要加载的表（含外键关联表）
+        tables_to_load: set | None = None
+        if filter_set:
+            tables_to_load = self._collect_foreign_key_tables(filter_set)
+
+        # Step 3: 按文件路径分组 Schema（同一文件多个 Sheet 合并加载）
+        file_to_schemas: dict[str, list[DataSourceInfo]] = defaultdict(list)
+        file_to_sheet_names: dict[str, str] = {}
+
+        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
+
+            # 解析数据源路径
+            source_path, sheet_name = self._resolver.resolve_source_path(data_directory, schema_file)
+            if not source_path:
+                loading_errors.append(
+                    {
+                        "error_type": "SourceNotFound",
+                        "message": f"表 '{table_schema.name}' 未找到数据源（已查找目录: {search_directory}）",
+                        "table": table_schema.name,
+                    }
+                )
+                continue
+
+            # 按文件路径分组，同一文件的不同 Sheet 放在一起加载
+            # 使用 DataSourceInfo DTO 将 domain TableSchema 转换为 core 层可用的最小信息
+            # 使用 getattr 以兼容测试中的 MockTableSchema 等不完整对象
+            file_to_schemas[source_path].append(
+                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 {},
+                )
+            )
+            if sheet_name:
+                file_to_sheet_names[source_path] = sheet_name
+
+        # Step 4: 批量加载分组后的数据文件
+        loaded_data, load_errors = 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 if file_to_sheet_names else None,
+        )
+        raw_datasets.update(loaded_data)
+        loading_errors.extend(load_errors)
+
+        return raw_datasets, loading_errors