precis-cli 0.1.3__py3-none-any.whl

app/shared/services/validation/engine.py

@@ -0,0 +1,446 @@
+# 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 数据校验服务层
+
+功能概述:
+- 执行完整的数据验证流程，包括格式解析和约束校验
+- 支持两阶段验证：格式解析验证 + 逻辑约束验证
+- 为前端可视化校验和命令行校验提供统一的校验入口
+- 聚合格式错误和约束错误后统一返回
+
+架构设计:
+- 阶段一（格式解析）：逐表解析原始数据，应用字段类型转换和格式验证
+- 阶段二（逻辑约束）：对解析后的数据进行跨表约束校验（外键、唯一性、条件、脚本化约束）
+- 错误聚合：将两阶段的错误合并后统一返回
+
+输入示例:
+    raw_datasets = {
+        "users": pd.DataFrame({
+            "id": ["1", "2", "3"],
+            "age": ["25", "30", "abc"]
+        })
+    }
+    schema = DataSetSchema(tables={...}, constraints=[...])
+    parsed, errors, details = validate_full_dataset(raw_datasets, schema)
+
+输出示例:
+    parsed_datasets: 解析后的 DataFrame 字典
+    all_errors: 格式错误 + 约束错误列表
+    validation_details: 详细校验信息
+"""
+
+import logging
+import time
+
+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.data_engine import process_dataframe
+from app.shared.domain.dataset_schema import DataSetSchema
+
+logger = logging.getLogger(__name__)
+
+from .dag import build_transform_dag, execute_transform_dag
+from .extractors import _extract_derived_columns
+
+
+def execute_dag_if_needed(
+    parsed_datasets: dict[str, pd.DataFrame],
+    *,
+    transform_files: dict[str, TransformFile] | None = None,
+    regex_files: dict[str, RegexNodeFile] | None = None,
+) -> tuple[dict[str, pd.DataFrame], list[dict]]:
+    """
+    @methoddesc 按需构建并执行 Transform DAG，返回更新后的 parsed_datasets 与 DAG 错误
+
+    抽离此函数是为了让分块加载路径能在 concat 全量 parsed 后单独执行 DAG，
+    修复分块模式下行变 transform（FilterRows/DropDuplicates/Aggregate 等）
+    只在块内生效、结果与全量不一致的正确性问题。
+
+    参数:
+        parsed_datasets: 已解析的 DataFrame 字典
+        transform_files: transform 配置文件字典
+        regex_files: regex 节点配置文件字典
+
+    返回:
+        二元组 (parsed_datasets, dag_errors):
+        - parsed_datasets: 经 DAG 处理后的 DataFrame 字典
+        - dag_errors: transform/regex 节点执行失败的错误列表（回归 #6）
+    """
+    if not (transform_files or regex_files):
+        return parsed_datasets, []
+    logger.debug("执行 Transform DAG")
+    dag = build_transform_dag(
+        transform_files or {},
+        set(parsed_datasets.keys()),
+        regex_files,
+    )
+    return execute_transform_dag(dag, parsed_datasets)
+
+
+def validate_full_dataset(
+    raw_datasets: dict[str, pd.DataFrame],
+    schema: DataSetSchema,
+    allow_unsafe_eval: bool = False,
+    table_filter: str | list[str] | None = None,
+    transform_files: dict[str, TransformFile] | None = None,
+    regex_files: dict[str, RegexNodeFile] | None = None,
+    deadline: float | None = None,
+    skip_constraints: bool = False,
+    stop_on_first_error: bool = False,
+) -> tuple[dict[str, pd.DataFrame], list[dict], dict[str, list[dict]]]:
+    """
+    @methoddesc 执行完整的验证流程，包括格式解析和约束校验
+
+    这是数据校验的主入口函数，执行两阶段验证：
+    1. 阶段一：格式解析验证 - 对每个表的原始数据进行类型转换和格式检查
+    2. 阶段二：逻辑约束验证 - 对解析后的数据进行业务规则校验
+
+    参数:
+        raw_datasets: 包含原始 DataFrame 的字典，键为表名，值为 pandas DataFrame
+        schema: 完整的数据集 Schema 定义，包含表结构和约束配置
+        allow_unsafe_eval: 是否允许执行不安全的脚本化约束。默认为 False（安全模式）
+        table_filter: 只验证与这些表相关的约束
+        deadline: 超时截止时间（time.monotonic 绝对时间），超过此时间后跳过剩余约束
+        skip_constraints: 仅执行阶段一（格式解析+派生列+Transform DAG），跳过阶段二约束校验。
+            供分块加载路径使用——分块时每块只解析格式，约束在 concat 全量 parsed 后统一执行
+            （见 validate_constraints），以避免跨表 ForeignKey 假阳性与跨块 Unique 假阴性。
+
+    返回:
+        元组 (parsed_datasets, all_errors, validation_details)
+        - parsed_datasets: 解析后的 DataFrame 字典
+        - all_errors: 所有格式错误和逻辑错误的聚合列表
+        - validation_details: 校验详情，包含 format_checks 和 constraint_checks
+
+    使用示例:
+        >>> from app.shared.domain.dataset_schema import DataSetSchema
+        >>> raw_data = {'users': pd.DataFrame({'id': [1, 2], 'name': ['Alice', 'Bob']})}
+        >>> schema = DataSetSchema(...)
+        >>> parsed, errors, details = validate_full_dataset(raw_data, schema)
+    """
+    # 初始化错误列表和解析结果字典
+    # all_errors: 用于存储两阶段产生的所有错误
+    # parsed_datasets: 用于存储解析后的DataFrame，供阶段二使用
+    all_errors = []
+    parsed_datasets: dict[str, pd.DataFrame] = {}
+
+    # 初始化校验详情
+    # validation_details: 用于存储所有校验过程的详细信息
+    validation_details: dict[str, list[dict]] = {
+        "format_checks": [],  # 格式校验信息
+        "constraint_checks": [],  # 约束校验信息
+    }
+
+    # ========================
+    # 阶段一：格式解析验证
+    # ========================
+    # 逐表遍历原始数据，应用字段类型转换和格式验证
+    # process_dataframe 会根据 table_schema 中的字段定义进行：
+    # - 类型转换（字符串转日期、数字等）
+    # - 格式验证（正则匹配、范围检查等）
+    #
+    # 【派生列处理说明】
+    # 对于 regex 提取的派生列（ColumnSpec.derived_from 不为 None）：
+    # - 当前版本：从原始数据文件加载时，这些列的数据不存在
+    # - 未来版本：需要从缓存文件或通过重新执行 regex 提取来获取派生列数据
+    # - 实现思路：
+    #   1. 识别 schema 中的派生列（使用 is_derived_column 函数）
+    #   2. 从缓存文件或内存中加载派生列数据
+    #   3. 将派生列数据合并到 parsed_df 中
+    logger.debug("开始阶段一: 格式解析验证")
+    for table_id, raw_df in raw_datasets.items():
+        # 跳过未在Schema中定义的表（允许数据集包含额外表）
+        if table_id not in schema.tables:
+            logger.warning(f"数据集中存在未在Schema中定义的表 '{table_id}', 将跳过。")
+            continue
+
+        # 获取表的Schema定义，进行格式解析
+        table_schema = schema.tables[table_id]
+        # process_dataframe 返回：(解析后的DataFrame, 错误字典列表)
+        parsed_df, parsing_errors = process_dataframe(raw_df, table_schema)
+
+        # 存储解析后的数据，供阶段二约束校验使用（使用 table_id 作为键）
+        parsed_datasets[table_id] = parsed_df
+        # 将解析错误聚合到总错误列表
+        if parsing_errors:
+            for item in parsing_errors:
+                all_errors.append(
+                    {
+                        **item,
+                        "stage": "format",
+                        "table": table_id,
+                        "table_id": table_id,
+                        "check_type": "FormatValidation",
+                        "message": item.get("error_message"),
+                    }
+                )
+
+        # 记录格式校验信息
+        validation_details["format_checks"].append(
+            {"table": table_id, "error_count": len(parsing_errors), "passed": len(parsing_errors) == 0}
+        )
+
+        logger.debug(f"表 '{table_id}' 解析完成。发现 {len(parsing_errors)} 个格式错误。")
+
+        # C6 遇错即停:格式校验阶段发现错误即停,不处理剩余表、不进入约束阶段。
+        if stop_on_first_error and parsing_errors:
+            remaining_tables = len(raw_datasets) - (list(raw_datasets.keys()).index(table_id) + 1)
+            all_errors.append(
+                {
+                    "stage": "format",
+                    "check_type": "ValidationInterrupted",
+                    "table": table_id,
+                    "error_type": "ValidationInterrupted",
+                    "message": (
+                        f"已按项目设置『遇错即停』停止：表 '{table_id}' 的格式校验发现首个错误,"
+                        f"剩余 {remaining_tables} 个表及约束校验未执行。"
+                    ),
+                }
+            )
+            logger.info(f"遇错即停:格式阶段在表 '{table_id}' 停止,跳过剩余表与约束校验")
+            return parsed_datasets, all_errors, validation_details
+
+    # ========================
+    # 阶段一续：提取派生列
+    # ========================
+    # 派生列是通过正则表达式等规则从原始列中提取的新列
+    # 例如：从邮箱列中提取域名作为派生列
+    # 【数据流】在格式解析后、约束校验前执行，确保派生列可用于后续约束
+    logger.debug("开始阶段一续: 提取派生列")
+    _extract_derived_columns(parsed_datasets, schema, raw_datasets, all_errors)
+
+    # ========================
+    # 阶段一续二：执行 Transform DAG
+    # ========================
+    # Transform DAG 是有向无环图，用于编排多个 transform 规则的执行顺序
+    # 【拓扑排序】根据依赖关系确定执行顺序，确保前置 transform 先执行
+    # 只有当存在 transform_files 或 regex_files 时才需要执行
+    if transform_files or regex_files:
+        logger.debug("开始阶段一续二: 执行 Transform DAG")
+        parsed_datasets, dag_errors = execute_dag_if_needed(
+            parsed_datasets,
+            transform_files=transform_files,
+            regex_files=regex_files,
+        )
+        # 回归 #6: DAG 节点(transform/regex)执行失败必须上报,否则下游约束在未转换数据上
+        # "假通过"。把 dag_errors 归入 all_errors(stage="loading",属数据预处理阶段失败)。
+        for err in dag_errors:
+            err_with_stage = {"stage": "loading", **err}
+            all_errors.append(err_with_stage)
+
+    # ========================
+    # 阶段二：逻辑约束验证
+    # ========================
+    # 对解析后的数据进行业务规则校验
+    # 支持的约束类型：
+    # - ForeignKeyConstraints: 外键约束（跨表引用完整性）
+    # - UniqueConstraint: 唯一性约束（列值不重复）
+    # - AllowedValuesConstraint: 允许值约束（枚举值检查）
+    # - ConditionalConstraint: 条件约束（基于条件的规则）
+    # - ScriptedConstraint: 脚本化约束（自定义脚本逻辑）
+    logger.debug("开始阶段二: 逻辑约束验证")
+    if skip_constraints:
+        # 分块加载路径：每块只解析格式，约束校验在 concat 全量 parsed 后由调用方统一执行
+        logger.debug("skip_constraints=True，跳过阶段二约束校验（分块解析模式）")
+        return parsed_datasets, all_errors, validation_details
+    all_errors, validation_details = validate_constraints(
+        parsed_datasets,
+        schema,
+        all_errors=all_errors,
+        validation_details=validation_details,
+        allow_unsafe_eval=allow_unsafe_eval,
+        table_filter=table_filter,
+        deadline=deadline,
+        stop_on_first_error=stop_on_first_error,
+    )
+
+    # 返回解析后的数据集、所有错误和校验详情
+    # 【结果说明】前端可以根据 is_empty(all_errors) 判断验证是否通过
+    # validation_details 用于展示所有校验过程的详细信息
+    return parsed_datasets, all_errors, validation_details
+
+
+def validate_constraints(
+    parsed_datasets: dict[str, pd.DataFrame],
+    schema: DataSetSchema,
+    *,
+    all_errors: list[dict] | None = None,
+    validation_details: dict[str, list[dict]] | None = None,
+    allow_unsafe_eval: bool = False,
+    table_filter: str | list[str] | None = None,
+    deadline: float | None = None,
+    stop_on_first_error: bool = False,
+) -> tuple[list[dict], dict[str, list[dict]]]:
+    """
+    @methoddesc 仅执行阶段二（逻辑约束验证），对已解析数据跑所有约束
+
+    抽离此函数是为了让分块加载路径能在 concat 全量 parsed 后单独重跑约束，
+    修复分块模式下跨表 ForeignKey（假阳性）与跨块 Unique（假阴性）的正确性问题。
+
+    参数:
+        parsed_datasets: 已解析的 DataFrame 字典（键为 table_id）
+        schema: 完整的数据集 Schema 定义
+        all_errors: 已有错误列表（会在此基础上追加），默认新建
+        validation_details: 已有校验详情（会在此基础上追加），默认新建
+        allow_unsafe_eval: 是否允许执行不安全的脚本化约束
+        table_filter: 只验证与这些表相关的约束
+        deadline: 超时截止时间
+        stop_on_first_error: C6 遇错即停。True 时发现第一个约束错误即停止剩余约束校验,
+            追加一条 ValidationInterrupted 标记(供调用方感知中断)。
+
+    返回:
+        元组 (all_errors, validation_details)
+    """
+    if all_errors is None:
+        all_errors = []
+    if validation_details is None:
+        validation_details = {"format_checks": [], "constraint_checks": []}
+
+    # 如果所有表都为空，跳过约束验证以避免无意义计算和边界错误（M3）
+    # 【防御性编程】空数据集无需执行约束校验，直接返回
+    has_any_data = any(not df.empty for df in parsed_datasets.values())
+    if not has_any_data:
+        logger.debug("所有解析后的表均为空，跳过阶段二约束验证")
+        return all_errors, validation_details
+
+    # 处理 table_filter 参数（只接受表ID）
+    # 【类型适配】支持字符串或列表形式，统一转换为集合便于成员检查
+    filter_tables: set | None = None
+    if table_filter:
+        if isinstance(table_filter, str):
+            filter_tables = {table_filter}
+        else:
+            filter_tables = set(table_filter)
+
+    # 遍历所有注册的约束，逐个执行校验
+    # 【容错设计】单个约束异常不中断整个管线，继续执行后续约束
+    for i, constraint in enumerate(schema.constraints):
+        # 【超时中断】在每个约束执行前检查是否已超过截止时间
+        if deadline is not None and time.monotonic() > deadline:
+            logger.warning(f"超时中断：跳过剩余 {len(schema.constraints) - i} 个约束（含约束 {i + 1}）")
+            all_errors.append(
+                {
+                    "stage": "constraint",
+                    "check_type": "Timeout",
+                    "table": None,
+                    "error_type": "Timeout",
+                    "message": f"校验超时，剩余 {len(schema.constraints) - i} 个约束未执行",
+                }
+            )
+            break
+
+        # 获取约束信息，判断是否需要跳过
+        try:
+            constraint_info = constraint.get_constraint_info()
+        except Exception as e:
+            # 【异常处理】约束信息获取失败时记录错误并跳过该约束
+            logger.error(f"约束 {i + 1} 获取信息失败: {e}")
+            validation_details["constraint_checks"].append(
+                {
+                    "constraint_type": constraint.__class__.__name__,
+                    "table": None,
+                    "description": "",
+                    "error_count": 1,
+                    "passed": False,
+                    "error": str(e),
+                }
+            )
+            continue
+
+        constraint_table = constraint_info.get("table")
+
+        # 如果指定了 table_filter，只验证相关表的约束
+        # 【过滤逻辑】当 filter_tables 存在且当前约束的表不在过滤列表中时跳过
+        if filter_tables and constraint_table not in filter_tables:
+            logger.debug(f"跳过约束 {i + 1} ({constraint.__class__.__name__}): 表 '{constraint_table}' 不在过滤列表中")
+            continue
+
+        # 传递 allow_unsafe_eval 参数以控制脚本约束的执行
+        # 【安全策略】当 allow_unsafe_eval=False 时，脚本约束会在安全沙箱中运行
+        # 单个约束异常不中断整个管线，继续执行后续约束
+        # D6: 透传 deadline,让逐行慢约束(Scripted/Conditional)在循环内部检查超时、提前中断,
+        # 而非跑到约束返回后才在循环顶部(:319)检查——否则单个慢约束会让 timeout_seconds 形同虚设。
+        try:
+            result = constraint.validate(parsed_datasets, allow_unsafe_eval=allow_unsafe_eval, deadline=deadline)
+        except Exception as e:
+            # 【异常处理】约束执行异常时构造错误结果，不中断后续约束校验
+            logger.error(f"约束 {i + 1} ({constraint.__class__.__name__}) 执行异常: {e}")
+            result = {
+                "errors": [
+                    {
+                        "error_type": "ConstraintExecutionError",
+                        "table": constraint_table,
+                        "message": f"约束执行异常: {e}",
+                    }
+                ],
+                "info": constraint_info,
+            }
+
+        # 获取约束错误和约束信息
+        constraint_errors = result.get("errors", [])
+        constraint_info = result.get("info", {})
+
+        # 聚合错误
+        # 【数据标准化】统一错误字段格式，确保前端能够正确解析
+        if constraint_errors:
+            for item in constraint_errors:
+                all_errors.append(
+                    {
+                        **item,
+                        "stage": item.get("stage") or "constraint",
+                        "check_type": item.get("check_type")
+                        or constraint_info.get("constraint_type", constraint.__class__.__name__),
+                        "table": item.get("table") or constraint_info.get("table"),
+                        # P0-3: 透出来源约束文件路径（executor 已按 constraint_id 挂载）；
+                        # 格式校验/超时等非约束错误不走此分支，JSON 输出中为 null
+                        "constraint_file": getattr(constraint, "constraint_file", None),
+                    }
+                )
+
+        # 记录约束校验信息
+        validation_details["constraint_checks"].append(
+            {
+                "constraint_type": constraint_info.get("constraint_type", constraint.__class__.__name__),
+                "table": constraint_info.get("table"),
+                "description": constraint_info.get("description", ""),
+                "error_count": len(constraint_errors),
+                "passed": len(constraint_errors) == 0,
+            }
+        )
+
+        logger.debug(
+            f"约束 {i + 1} ({constraint.__class__.__name__}) 验证完成。发现 {len(constraint_errors)} 个逻辑错误。"
+        )
+
+        # C6 遇错即停:发现第一个约束错误后立即停止剩余约束(快速失败),追加中断标记。
+        # 仿上方 deadline 超时中断模式(:296-307)。constraint_checks 已记录当前约束,故在此 break。
+        if stop_on_first_error and constraint_errors:
+            remaining = len(schema.constraints) - i - 1
+            all_errors.append(
+                {
+                    "stage": "constraint",
+                    "check_type": "ValidationInterrupted",
+                    "table": None,
+                    "error_type": "ValidationInterrupted",
+                    "message": (f"已按项目设置『遇错即停』停止：发现首个错误，剩余 {remaining} 个约束未执行。"),
+                }
+            )
+            logger.info(f"遇错即停:跳过剩余 {remaining} 个约束(含约束 {i + 2} 起)")
+            break
+
+    return all_errors, validation_details