precis-cli 0.1.3__py3-none-any.whl

app/shared/services/validation/executor.py

@@ -0,0 +1,1030 @@
+# 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.
+# backend/app/shared/services/validation/executor.py
+"""
+@fileoverview 全量校验执行器
+
+功能概述:
+- 提供 CLI 和前端共享的核心校验编排逻辑
+- 编排加载→格式解析→约束校验→结果后处理全流程
+- 支持超时控制、设置覆盖、表过滤等执行选项
+- 提供 ValidationOptions 配置类和 create_executor 工厂函数
+
+架构设计:
+- 组合模式: ValidationExecutor 组合使用 DataSourceResolver + DataLoader
+- 职责分离: 自身仅负责流程编排，路径解析和数据加载委托给子模块
+- 调用方: CLI 的 DataValidator 和前端 API 的 validate_v2_full
+
+输入示例:
+    executor = create_executor("project.precis.yaml")
+    options = ValidationOptions(timeout_seconds=30, strict_mode=False)
+    result = executor.execute(data_directory="./data", options=options)
+
+输出示例:
+    result = {
+        "success": True,
+        "errors": [...],
+        "parsed_datasets": {...}
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from collections.abc import Callable
+from typing import Any
+
+import pandas as pd
+
+from app.shared.core.project.loader import LoadedProject, load_project
+from app.shared.core.project.schema.types import TableSchemaFile
+from app.shared.domain.dataset_schema import DataSetSchema
+
+from .chunked_loader import ChunkedDataLoader
+from .data_loader import DataLoader
+from .engine import execute_dag_if_needed, validate_constraints, validate_full_dataset
+from .memory_monitor import DEFAULT_CHUNK_THRESHOLD_MB, MemoryMonitor
+from .postprocess import (
+    attach_source_info,
+    build_id_to_name_map,
+    build_table_source_map,
+    map_table_id,
+    postprocess_result,
+)
+from .progress import ProgressEvent
+from .resolver import DataSourceResolver
+
+logger = logging.getLogger(__name__)
+
+# 进度回调类型：接收 ProgressEvent，无返回值
+ProgressCallback = Callable[[ProgressEvent], None]
+
+
+class ValidationOptions:
+    """
+    @classdesc 校验执行选项
+
+    用于配置校验执行的可选参数，支持前端覆盖配置。
+    包含超时控制、错误处理策略、严格模式、表过滤等设置。
+
+    属性:
+        timeout_seconds: 超时时间（秒），默认 30 秒
+        error_handling: 错误处理策略，"continue" 表示遇到错误继续执行
+        strict_mode: 严格模式，True 时任何错误都视为校验失败
+        allow_unsafe_eval: 是否允许不安全脚本执行，None 表示使用项目配置
+        table_filter: 表过滤列表，只校验指定表相关的约束
+    """
+
+    def __init__(
+        self,
+        timeout_seconds: int = 30,
+        error_handling: str = "continue",
+        strict_mode: bool = False,
+        allow_unsafe_eval: bool | None = None,
+        table_filter: str | list[str] | None = None,
+        chunk_threshold_mb: float = DEFAULT_CHUNK_THRESHOLD_MB,
+        chunk_rows: int = 100_000,
+    ):
+        self.timeout_seconds = timeout_seconds
+        self.error_handling = error_handling
+        self.strict_mode = strict_mode
+        self.allow_unsafe_eval = allow_unsafe_eval
+        self.table_filter = table_filter
+        self.chunk_threshold_mb = chunk_threshold_mb
+        self.chunk_rows = chunk_rows
+
+
+class ValidationExecutor:
+    """
+    @classdesc 全量校验执行器
+
+    负责：
+    - 加载项目配置和 Schema 定义
+    - 委托 DataSourceResolver 解析数据源路径
+    - 委托 DataLoader 批量加载数据文件
+    - 编排格式解析和约束校验
+    - 结果后处理（ID→Name 映射）
+    - 超时控制
+    """
+
+    def __init__(
+        self,
+        manifest_path: str,
+        settings_override: Any = None,
+        allow_unsafe_eval: bool | None = None,
+    ):
+        # 校验清单文件存在性
+        # 【防御性编程】在初始化阶段即检查文件是否存在，避免后续操作失败
+        if not os.path.exists(manifest_path):
+            raise FileNotFoundError(f"项目配置文件未找到: {manifest_path}")
+
+        # 解析项目根目录并加载项目配置
+        # 【数据流】manifest_path → project_root → load_project → LoadedProject
+        # 通过依赖注入把 build_dataset_schema 传入 core 的 load_project，
+        # 避免 core 层反向依赖 services（见 loader_parts/main.py 的 schema_builder 参数）。
+        self.project_root = os.path.dirname(manifest_path)
+        from app.shared.services.project_loader import build_dataset_schema
+
+        self.loaded_project: LoadedProject = load_project(manifest_path, schema_builder=build_dataset_schema)
+        self.dataset_schema: DataSetSchema = self.loaded_project.dataset_schema
+        self.settings = self.loaded_project.manifest.settings
+        self.manifest = self.loaded_project.manifest
+
+        # P0-3: 为每个运行时约束附加其来源约束文件路径（相对 manifest 目录）。
+        # 独立约束文件为其 YAML 路径，schema 内嵌约束为 schema 文件路径；
+        # 模板展开产物与无来源约束保持无该属性（校验错误中 constraint_file 为 null）。
+        # getattr 防御：load_project 被 mock 的测试边界可能不带该新字段
+        _source_map = getattr(self.loaded_project, "constraint_source_files", None) or {}
+        for _constraint in getattr(self.dataset_schema, "constraints", None) or []:
+            _cid = getattr(_constraint, "constraint_id", None)
+            if _cid is not None and _cid in _source_map:
+                _constraint.constraint_file = _source_map[_cid]  # type: ignore[attr-defined]
+
+        # 执行器级别的脚本执行权限覆盖，优先级高于项目配置
+        self.allow_unsafe_eval = allow_unsafe_eval
+
+        # 应用前端或 CLI 传入的设置覆盖值
+        # 【配置优先级】settings_override > 项目配置 > 默认值
+        if settings_override:
+            self._apply_settings_override(settings_override)
+
+        # 构建表 ID 到 Schema 文件的映射，便于快速查找
+        self._schema_by_id: dict[str, TableSchemaFile] = dict(self.loaded_project.schema_files)
+
+        # 初始化数据源解析器，负责将相对路径解析为绝对路径
+        self._resolver = DataSourceResolver(
+            project_root=self.project_root,
+            manifest=self.manifest,
+            schema_by_id=self._schema_by_id,
+        )
+        # 初始化数据加载器，负责批量加载数据文件
+        self._data_loader = DataLoader(
+            resolver=self._resolver,
+            dataset_schema=self.dataset_schema,
+            schema_by_id=self._schema_by_id,
+            settings=self.settings,
+        )
+        # 初始化内存监控器
+        self._memory_monitor = MemoryMonitor()
+        # 初始化分块数据加载器（惰性创建，仅在需要时使用）
+        self._chunked_loader: ChunkedDataLoader | None = None
+
+    def _get_chunked_loader(self, options: ValidationOptions) -> ChunkedDataLoader:
+        """获取或创建分块数据加载器。"""
+        if self._chunked_loader is None:
+            self._memory_monitor.chunk_threshold_mb = options.chunk_threshold_mb
+            self._memory_monitor.chunk_rows = options.chunk_rows
+            self._chunked_loader = ChunkedDataLoader(
+                resolver=self._resolver,
+                dataset_schema=self.dataset_schema,
+                schema_by_id=self._schema_by_id,
+                settings=self.settings,
+                memory_monitor=self._memory_monitor,
+            )
+        return self._chunked_loader
+
+    def _apply_settings_override(self, override: Any) -> None:
+        """
+        @methoddesc 应用设置覆盖
+
+        将前端或 CLI 传入的设置覆盖值应用到项目配置中。
+        支持 Pydantic 模型和字典两种格式的覆盖值。
+
+        参数:
+            override: 设置覆盖值，可以是 Pydantic 模型或字典
+
+        异常:
+            TypeError: override 类型不支持（非 dict 非 Pydantic 模型）
+            ValueError: 覆盖值包含未知字段
+        """
+        if override is None:
+            return
+
+        # 统一转换为字典格式
+        if hasattr(override, "model_dump"):
+            override_dict = override.model_dump(exclude_none=True)
+        elif isinstance(override, dict):
+            override_dict = override
+        else:
+            raise TypeError("settings_override 必须为 dict 或 Pydantic 模型")
+
+        # 校验根级别字段是否合法
+        allowed_root = {"validation", "file_processing", "script_security"}
+        unknown_root = set(override_dict.keys()) - allowed_root
+        if unknown_root:
+            raise ValueError(f"settings_override 包含未知字段: {sorted(unknown_root)}")
+
+        # 逐组应用覆盖值
+        for group_name in ("validation", "file_processing", "script_security"):
+            group_override = override_dict.get(group_name)
+            if not group_override:
+                continue
+            if not isinstance(group_override, dict):
+                raise ValueError(f"settings_override.{group_name} 必须为对象")
+            target = getattr(self.settings, group_name, None)
+            if target is None:
+                continue
+            for key, value in group_override.items():
+                if not hasattr(target, key):
+                    raise ValueError(f"settings_override.{group_name} 包含未知字段: {key}")
+                setattr(target, key, value)
+
+    def _resolve_allow_unsafe_eval(self, options: ValidationOptions) -> bool:
+        """
+        @methoddesc 解析本次校验是否允许不安全脚本执行
+
+        优先级（高到低）：
+        1. 请求级选项 options.allow_unsafe_eval
+        2. 执行器实例级 self.allow_unsafe_eval
+        3. 项目配置：settings.script_security.allow_eval 且非沙箱模式
+
+        参数:
+            options: 当前校验执行选项
+
+        返回:
+            True 表示允许执行使用 eval 的脚本化约束
+        """
+        if options.allow_unsafe_eval is not None:
+            return options.allow_unsafe_eval
+        if self.allow_unsafe_eval is not None:
+            return self.allow_unsafe_eval
+        script_security = getattr(self.settings, "script_security", None)
+        if script_security is None:
+            return False
+        allow_eval = getattr(script_security, "allow_eval", False)
+        sandbox_mode = getattr(script_security, "sandbox_mode", True)
+        return bool(allow_eval and not sandbox_mode)
+
+    def _build_table_source_map(self) -> dict[str, dict[str, str | None]]:
+        """构建表 ID 到数据源信息的映射（委托 postprocess.build_table_source_map）。"""
+        return build_table_source_map(self._schema_by_id)
+
+    @staticmethod
+    def _attach_source_info(item: dict[str, Any], table_source_map: dict[str, dict[str, str | None]]) -> None:
+        """将数据源信息附加到条目字典（委托 postprocess.attach_source_info）。"""
+        attach_source_info(item, table_source_map)
+
+    @staticmethod
+    def _build_id_to_name_map(dataset_schema: DataSetSchema) -> dict[str, str]:
+        """构建表 ID 到显示名称的映射（委托 postprocess.build_id_to_name_map）。"""
+        return build_id_to_name_map(dataset_schema)
+
+    def _postprocess_result(self, result: dict[str, Any]) -> None:
+        """结果统一后处理（委托 postprocess.postprocess_result）。"""
+        postprocess_result(result, self.dataset_schema, self._schema_by_id)
+
+    def _finalize_result(self, result: dict[str, Any], started: float) -> None:
+        result["duration_ms"] = int((time.monotonic() - started) * 1000)
+        result["memory_info"] = self._memory_monitor.get_progress_info()
+
+    @staticmethod
+    def _emit_progress(
+        callback: ProgressCallback | None,
+        started: float,
+        stage: str,
+        table: str | None = None,
+        chunk_index: int = 0,
+        chunk_total: int = 0,
+        rows_done: int = 0,
+        rows_total: int = 0,
+        errors_so_far: int = 0,
+    ) -> None:
+        """安全地触发进度回调。
+
+        callback 为 None 时直接返回（零开销）；callback 抛异常时仅记日志、不抛出，
+        确保进度通道的故障不影响校验主流程。所有字段口径与 ProgressEvent 文档一致。
+
+        参数:
+            callback: 调用方传入的进度回调，可为 None。
+            started: 校验开始时间（time.monotonic() 返回值），用于计算 elapsed_ms。
+            stage/table/chunk_index/...: 见 ProgressEvent 字段说明。
+        """
+        if callback is None:
+            return
+        try:
+            callback(
+                ProgressEvent(
+                    stage=stage,
+                    table=table,
+                    chunk_index=chunk_index,
+                    chunk_total=chunk_total,
+                    rows_done=rows_done,
+                    rows_total=rows_total,
+                    errors_so_far=errors_so_far,
+                    elapsed_ms=int((time.monotonic() - started) * 1000),
+                )
+            )
+        except Exception:  # noqa: BLE001 — 进度通道异常不得影响校验
+            logger.exception("progress_callback 抛出异常，已忽略")
+
+    @staticmethod
+    def _map_table_id(item: dict[str, Any], id_to_name: dict[str, str]) -> None:
+        """将条目中的表 ID 替换为表显示名称（委托 postprocess.map_table_id）。"""
+        map_table_id(item, id_to_name)
+
+    def execute(
+        self,
+        data_directory: str,
+        options: ValidationOptions | None = None,
+        progress_callback: ProgressCallback | None = None,
+    ) -> dict[str, Any]:
+        """
+        @methoddesc 执行完整校验流程
+
+        编排数据加载、格式解析、约束校验和结果后处理的完整流程。
+        采用分阶段执行策略，每个阶段后检查超时条件。
+        当检测到大文件时自动切换到分块处理模式。
+
+        执行流程:
+            Step 1: 检测文件大小，决定使用标准模式还是分块模式
+            Step 2: 加载数据源（标准 DataLoader 或 ChunkedDataLoader）
+            Step 3: 检查加载阶段超时
+            Step 4: 检查数据加载成功
+            Step 5: 确定脚本安全执行策略
+            Step 6: 执行格式解析和约束校验
+            Step 7: 结果后处理（ID→Name 映射 + 数据源信息附加）
+            Step 8: 检查校验阶段超时
+
+        参数:
+            data_directory: 数据文件所在目录
+            options: 校验执行选项，包含超时、过滤等配置
+            progress_callback: 可选的进度回调，校验过程中在阶段切换/分块边界
+                触发。callback 异常不影响校验（仅记日志）。不传时行为完全不变。
+
+        返回:
+            包含以下字段的字典:
+                - raw_datasets: 原始数据集
+                - parsed_datasets: 解析后的数据集
+                - errors: 校验错误列表
+                - loading_errors: 数据加载错误列表
+                - duration_ms: 执行耗时（毫秒）
+                - timeout_occurred: 是否发生超时
+                - validation_details: 校验详情
+                - chunked_mode: 是否使用了分块模式
+                - memory_info: 内存监控信息
+        """
+        if options is None:
+            options = ValidationOptions()
+
+        # 更新内存监控器配置
+        self._memory_monitor.chunk_threshold_mb = options.chunk_threshold_mb
+        self._memory_monitor.chunk_rows = options.chunk_rows
+
+        # 记录开始时间，用于计算总耗时和超时检查
+        started = time.monotonic()
+        result: dict[str, Any] = {
+            "raw_datasets": {},
+            "parsed_datasets": {},
+            "errors": [],
+            "loading_errors": [],
+            "duration_ms": 0,
+            "timeout_occurred": False,
+            "interrupted": False,  # C6 遇错即停:是否因 error_handling=stop 提前终止
+            "validation_details": {"format_checks": [], "constraint_checks": []},
+            "chunked_mode": False,
+            "memory_info": {},
+        }
+
+        # Step 1: 检测是否需要分块模式
+        use_chunked = self._should_use_chunked_mode(data_directory, options)
+        if use_chunked:
+            result["chunked_mode"] = True
+            logger.info("检测到大文件，启用分块处理模式")
+            return self._execute_chunked(data_directory, options, started, result, progress_callback)
+
+        # Step 2-8: 标准模式流水线（加载→校验→后处理→超时检查）
+        return self._execute_standard(data_directory, options, started, result, progress_callback)
+
+    def _execute_standard(
+        self,
+        data_directory: str,
+        options: ValidationOptions,
+        started: float,
+        result: dict[str, Any],
+        progress_callback: ProgressCallback | None = None,
+    ) -> dict[str, Any]:
+        """
+        @methoddesc 执行标准（非分块）模式校验流水线
+
+        承接 execute 的 Step 2-8：数据加载、加载阶段超时与空数据检查、
+        格式解析与约束校验、结果后处理、校验阶段超时检查。
+
+        参数:
+            data_directory: 数据文件所在目录
+            options: 校验执行选项
+            started: 开始时间（time.monotonic()）
+            result: 已初始化的结果字典（chunked_mode=False）
+            progress_callback: 可选进度回调
+
+        返回:
+            完整的校验结果字典
+        """
+        # Step 2: 加载数据源（标准模式）
+        raw_datasets, loading_errors = self._data_loader.load_data_sources(
+            data_directory, table_filter=options.table_filter
+        )
+        result["raw_datasets"] = raw_datasets
+        result["loading_errors"] = loading_errors
+
+        # 追加项目加载阶段的错误
+        if self.loaded_project.loading_errors:
+            for err in self.loaded_project.loading_errors:
+                result["loading_errors"].append(err.to_dict())
+
+        result["warnings"] = self.loaded_project.warnings
+
+        # 进度：数据加载完成（标准模式一锤子加载，rows_total 为各表行数之和）
+        self._emit_progress(
+            progress_callback,
+            started,
+            stage="loading",
+            table=None,
+            rows_done=0,
+            rows_total=sum(len(df) for df in raw_datasets.values()),
+            errors_so_far=len(result["loading_errors"]),
+        )
+
+        # Step 3: 检查加载阶段是否超时
+        if (time.monotonic() - started) > options.timeout_seconds:
+            result["errors"].append(
+                {"error_type": "Timeout", "message": f"数据加载阶段超时（>{options.timeout_seconds}s）"}
+            )
+            result["timeout_occurred"] = True
+            self._emit_progress(
+                progress_callback,
+                started,
+                stage="done",
+                errors_so_far=len(result["errors"]),
+            )
+            self._finalize_result(result, started)
+            return result
+
+        # Step 4: 检查数据是否加载成功
+        if not raw_datasets:
+            result["errors"].append(
+                {"error_type": "DataLoadingError", "message": "未能从数据目录加载任何数据表，校验中止。"}
+            )
+            self._emit_progress(
+                progress_callback,
+                started,
+                stage="done",
+                errors_so_far=len(result["errors"]),
+            )
+            self._finalize_result(result, started)
+            return result
+
+        # 标准模式总行数（用于进度事件）
+        std_rows_total = sum(len(df) for df in raw_datasets.values())
+
+        # Step 5: 确定脚本安全执行策略
+        allow_unsafe_eval = self._resolve_allow_unsafe_eval(options)
+
+        logger.debug(f"Starting validate_full_dataset with {len(raw_datasets)} datasets")
+
+        # 计算校验阶段的超时截止时间
+        deadline = started + options.timeout_seconds
+
+        # 进度：进入校验阶段（标准模式 validate_full_dataset 为一锤子调用，粗粒度）
+        self._emit_progress(
+            progress_callback,
+            started,
+            stage="validating",
+            table=None,
+            rows_done=0,
+            rows_total=std_rows_total,
+            errors_so_far=len(result["errors"]),
+        )
+
+        # Step 6: 执行格式解析和约束校验
+        # C6 遇错即停:error_handling="stop" 时,发现首个错误即停止剩余校验
+        stop_on_first_error = options.error_handling == "stop"
+        try:
+            parsed_datasets, validation_errors, validation_details = validate_full_dataset(
+                raw_datasets,
+                self.dataset_schema,
+                allow_unsafe_eval=allow_unsafe_eval,
+                table_filter=options.table_filter,
+                transform_files=getattr(self.loaded_project, "transform_files", None) if self.loaded_project else None,
+                regex_files=getattr(self.loaded_project, "regex_node_files", None) if self.loaded_project else None,
+                deadline=deadline,
+                stop_on_first_error=stop_on_first_error,
+            )
+        except Exception as e:
+            logger.exception(f"Error during validate_full_dataset: {e}")
+            raise
+        result["parsed_datasets"] = parsed_datasets
+        result["errors"].extend(validation_errors)
+        result["validation_details"] = validation_details
+        # C6: 若校验因 stop 提前终止(返回了 ValidationInterrupted 标记),记录中断状态
+        if stop_on_first_error and any(e.get("error_type") == "ValidationInterrupted" for e in validation_errors):
+            result["interrupted"] = True
+
+        # 进度：校验执行完成（更新累计错误数）
+        self._emit_progress(
+            progress_callback,
+            started,
+            stage="validating",
+            table=None,
+            rows_done=std_rows_total,
+            rows_total=std_rows_total,
+            errors_so_far=len(result["errors"]),
+        )
+
+        # Step 7: 结果后处理
+        self._postprocess_result(result)
+
+        # Step 8: 检查校验阶段是否超时
+        if (time.monotonic() - started) > options.timeout_seconds:
+            result["errors"].append(
+                {"error_type": "Timeout", "message": f"数据校验阶段超时（>{options.timeout_seconds}s）"}
+            )
+            result["timeout_occurred"] = True
+
+        # 进度：全部完成
+        self._emit_progress(
+            progress_callback,
+            started,
+            stage="done",
+            table=None,
+            rows_done=std_rows_total,
+            rows_total=std_rows_total,
+            errors_so_far=len(result["errors"]),
+        )
+
+        self._finalize_result(result, started)
+        return result
+
+    def _should_use_chunked_mode(self, data_directory: str, options: ValidationOptions) -> bool:
+        """
+        @methoddesc 检测数据目录中是否有需要分块处理的大文件
+
+        参数:
+            data_directory: 数据文件目录
+            options: 校验选项
+
+        返回:
+            True 表示存在需要分块处理的大文件
+        """
+        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):
+            return False
+
+        for table_id, schema_file in self._schema_by_id.items():
+            source_path, _ = self._resolver.resolve_source_path(data_directory, schema_file)
+            if source_path and self._memory_monitor.should_chunk(source_path):
+                return True
+
+        return False
+
+    def _execute_chunked(
+        self,
+        data_directory: str,
+        options: ValidationOptions,
+        started: float,
+        result: dict[str, Any],
+        progress_callback: ProgressCallback | None = None,
+    ) -> dict[str, Any]:
+        """
+        @methoddesc 执行分块校验流程
+
+        使用 ChunkedDataLoader 分块加载数据，逐块执行格式解析和约束校验，
+        最终合并所有分块的结果。分块循环内按块边界触发进度回调（sparkline 主数据源）。
+
+        参数:
+            data_directory: 数据文件目录
+            options: 校验选项
+            started: 开始时间
+            result: 结果字典（已初始化）
+            progress_callback: 可选进度回调；不传时行为完全不变。
+
+        返回:
+            完整的校验结果字典
+        """
+        chunked_loader = self._get_chunked_loader(options)
+
+        # 分块加载数据源
+        try:
+            chunked_datasets, chunked_loading_errors = chunked_loader.load_chunked_sources(
+                data_directory, table_filter=options.table_filter
+            )
+        except Exception as e:
+            logger.exception(f"分块加载失败: {e}")
+            result["errors"].append({"error_type": "ChunkedLoadError", "message": f"分块加载失败: {e}"})
+            self._emit_progress(progress_callback, started, stage="done", errors_so_far=len(result["errors"]))
+            self._finalize_result(result, started)
+            return result
+
+        # 追加项目加载阶段的错误
+        if self.loaded_project.loading_errors:
+            for proj_err in self.loaded_project.loading_errors:
+                result["loading_errors"].append(proj_err.to_dict())
+        # 回归 #5: 追加分块加载阶段单表级别的错误(源找不到/加载异常),否则损坏表静默消失、
+        # 报告显示"全部通过"。这与标准模式 data_loader 返回 loading_errors 的语义对齐。
+        for chunk_err in chunked_loading_errors:
+            result["loading_errors"].append(chunk_err)
+        result["warnings"] = self.loaded_project.warnings
+
+        if not chunked_datasets:
+            result["errors"].append(
+                {"error_type": "DataLoadingError", "message": "未能从数据目录加载任何数据表，校验中止。"}
+            )
+            self._emit_progress(progress_callback, started, stage="done", errors_so_far=len(result["errors"]))
+            self._finalize_result(result, started)
+            return result
+
+        # 统计总行数和分块数
+        total_rows = 0
+        total_chunks = 0
+        for table_id, chunks in chunked_datasets.items():
+            for chunk in chunks:
+                total_rows += len(chunk)
+            total_chunks += len(chunks)
+
+        logger.info(f"分块加载完成: {len(chunked_datasets)} 个表, {total_chunks} 个分块, {total_rows} 总行数")
+
+        # 记录原始数据集信息（用于响应）
+        for table_id, chunks in chunked_datasets.items():
+            result["raw_datasets"][table_id] = {"chunk_count": len(chunks), "row_count": sum(len(c) for c in chunks)}
+
+        # 进度：分块加载完成（loading 阶段汇总）
+        self._emit_progress(
+            progress_callback,
+            started,
+            stage="loading",
+            table=None,
+            chunk_total=total_chunks,
+            rows_total=total_rows,
+            errors_so_far=len(result["loading_errors"]),
+        )
+
+        # 检查加载阶段超时
+        if (time.monotonic() - started) > options.timeout_seconds:
+            result["errors"].append(
+                {"error_type": "Timeout", "message": f"数据加载阶段超时（>{options.timeout_seconds}s）"}
+            )
+            result["timeout_occurred"] = True
+            self._emit_progress(progress_callback, started, stage="done", errors_so_far=len(result["errors"]))
+            self._finalize_result(result, started)
+            return result
+
+        # 确定脚本安全策略
+        allow_unsafe_eval = self._resolve_allow_unsafe_eval(options)
+        deadline = started + options.timeout_seconds
+        # C6 遇错即停:error_handling="stop" 时,分块格式校验发现首个错误即停止后续分块
+        stop_on_first_error = options.error_handling == "stop"
+
+        # 逐块执行格式解析（跳过约束），聚合各块结果
+        all_parsed_datasets, all_errors, all_validation_details, chunk_interrupted = self._parse_chunks_loop(
+            chunked_datasets,
+            options=options,
+            started=started,
+            total_rows=total_rows,
+            total_chunks=total_chunks,
+            allow_unsafe_eval=allow_unsafe_eval,
+            deadline=deadline,
+            stop_on_first_error=stop_on_first_error,
+            progress_callback=progress_callback,
+        )
+
+        # 合并分块解析结果并对全量数据执行 Transform DAG 与约束校验
+        self._apply_chunked_global_validation(
+            all_parsed_datasets,
+            all_errors,
+            all_validation_details,
+            result=result,
+            options=options,
+            allow_unsafe_eval=allow_unsafe_eval,
+            deadline=deadline,
+            stop_on_first_error=stop_on_first_error,
+            chunk_interrupted=chunk_interrupted,
+        )
+
+        # 结果后处理
+        self._postprocess_result(result)
+
+        # 检查总超时
+        if (time.monotonic() - started) > options.timeout_seconds:
+            result["timeout_occurred"] = True
+
+        # 进度：分块模式全部完成
+        self._emit_progress(
+            progress_callback,
+            started,
+            stage="done",
+            table=None,
+            chunk_total=total_chunks,
+            rows_done=total_rows,
+            rows_total=total_rows,
+            errors_so_far=len(result["errors"]),
+        )
+
+        self._finalize_result(result, started)
+        return result
+
+    def _parse_chunks_loop(
+        self,
+        chunked_datasets: dict[str, list[pd.DataFrame]],
+        options: ValidationOptions,
+        started: float,
+        total_rows: int,
+        total_chunks: int,
+        allow_unsafe_eval: bool,
+        deadline: float | None,
+        stop_on_first_error: bool,
+        progress_callback: ProgressCallback | None = None,
+    ) -> tuple[dict[str, list[pd.DataFrame]], list[dict], dict[str, list[dict]], bool]:
+        """
+        @methoddesc 逐块执行格式解析（跳过约束校验），聚合各块结果
+
+        【分块解析】每块只跑格式解析+派生列，跳过 Transform DAG 和约束校验；
+        行变 transform 与跨表/跨块约束都需要全局数据，由
+        _apply_chunked_global_validation 在 concat 全量后统一执行。
+        分块循环内按块边界触发进度回调（sparkline 主数据源）。
+
+        参数:
+            chunked_datasets: 表 ID → 分块 DataFrame 列表
+            options: 校验选项
+            started: 开始时间（time.monotonic()）
+            total_rows/total_chunks: 总行数与总分块数（进度事件用）
+            allow_unsafe_eval: 脚本执行权限
+            deadline: 校验阶段超时截止时间
+            stop_on_first_error: C6 遇错即停
+            progress_callback: 可选进度回调
+
+        返回:
+            (按表聚合的解析结果, 聚合错误列表, 聚合校验详情, 是否因 stop 中断)
+        """
+        all_parsed_datasets: dict[str, list[pd.DataFrame]] = {}
+        all_errors: list[dict] = []
+        all_validation_details: dict[str, list[dict]] = {
+            "format_checks": [],
+            "constraint_checks": [],
+        }
+        # C6: 跟踪是否因 stop 在分块阶段中断(中断后跳过全局约束校验)
+        chunk_interrupted = False
+        # §1.31: 超时只上报一次并终止整个分块循环（超时后剩余表本就不会再跑，
+        # 每表追加一条 Timeout 是对同一事件的重复描述）
+        timeout_hit = False
+
+        # 累计已处理行数（跨表累加，用于进度事件）
+        rows_done_so_far = 0
+
+        for table_id, chunks in chunked_datasets.items():
+            if timeout_hit:
+                break
+            all_parsed_datasets[table_id] = []
+
+            for chunk_idx, chunk_df in enumerate(chunks):
+                # 进度：开始处理当前分块（1-based chunk_index，sparkline 主要数据源）
+                self._emit_progress(
+                    progress_callback,
+                    started,
+                    stage="validating",
+                    table=table_id,
+                    chunk_index=chunk_idx + 1,
+                    chunk_total=total_chunks,
+                    rows_done=rows_done_so_far,
+                    rows_total=total_rows,
+                    errors_so_far=len(all_errors),
+                )
+
+                # 超时检查
+                if deadline is not None and time.monotonic() > deadline:
+                    if not timeout_hit:
+                        logger.warning(f"分块校验超时: 表 {table_id} 分块 {chunk_idx + 1}/{len(chunks)}")
+                        all_errors.append(
+                            {
+                                "error_type": "Timeout",
+                                "stage": "constraint",
+                                "check_type": "Timeout",
+                                "message": "分块校验超时，剩余分块未执行",
+                                "table": table_id,
+                            }
+                        )
+                        timeout_hit = True
+                    # §1.31: 中断块行数计入进度——started 进度已发出，补计保持单调，
+                    # 并补发一条中断点进度事件（前端进度条跳到中断点，不回跳）
+                    rows_done_so_far += len(chunk_df)
+                    self._emit_progress(
+                        progress_callback,
+                        started,
+                        stage="validating",
+                        table=table_id,
+                        chunk_index=chunk_idx + 1,
+                        chunk_total=total_chunks,
+                        rows_done=rows_done_so_far,
+                        rows_total=total_rows,
+                        errors_so_far=len(all_errors),
+                    )
+                    break
+
+                try:
+                    parsed_datasets: dict[str, pd.DataFrame]
+                    validation_errors: list[dict]
+                    validation_details: dict[str, list[dict]]
+                    # 【分块解析】每块只跑格式解析+派生列，跳过 Transform DAG 和约束校验。
+                    # 行变 transform（FilterRows/DropDuplicates）与跨表/跨块约束都需要全局数据，
+                    # 在 concat 全量 parsed 后统一执行（execute_dag_if_needed + validate_constraints），
+                    # 以避免分块模式下的结果错误（行变 transform 块内失效、FK 假阳性、Unique 假阴性）。
+                    parsed_datasets, validation_errors, validation_details = validate_full_dataset(
+                        {table_id: chunk_df},
+                        self.dataset_schema,
+                        allow_unsafe_eval=allow_unsafe_eval,
+                        table_filter=options.table_filter,
+                        # 分块解析阶段不传 transform/regex 文件，跳过 DAG
+                        transform_files=None,
+                        regex_files=None,
+                        deadline=deadline,
+                        skip_constraints=True,
+                    )
+
+                    # 收集解析后的数据
+                    for tid, parsed_df in parsed_datasets.items():
+                        all_parsed_datasets[tid].append(parsed_df)
+
+                    # 聚合错误（添加分块信息）
+                    for chunk_err in validation_errors:
+                        chunk_err["chunk_index"] = chunk_idx
+                        all_errors.append(chunk_err)
+
+                    # 聚合校验详情
+                    for check in validation_details.get("format_checks", []):
+                        all_validation_details["format_checks"].append(check)
+                    for check in validation_details.get("constraint_checks", []):
+                        all_validation_details["constraint_checks"].append(check)
+
+                    # C6 遇错即停:分块模式下,当前块格式校验发现错误即停止后续分块(块间中断,
+                    # 避免半块数据)。块内已跑完,数据完整。
+                    if stop_on_first_error and validation_errors:
+                        all_errors.append(
+                            {
+                                "error_type": "ValidationInterrupted",
+                                "stage": "format",
+                                "check_type": "ValidationInterrupted",
+                                "table": table_id,
+                                "message": (
+                                    f"已按项目设置『遇错即停』停止：表 '{table_id}' 分块 {chunk_idx + 1} "
+                                    f"格式校验发现错误,剩余分块及约束校验未执行。"
+                                ),
+                            }
+                        )
+                        chunk_interrupted = True
+                        # §1.31: 中断块行数计入进度（该块已完整处理，只是不再继续后续块），
+                        # 并补发中断点进度事件
+                        rows_done_so_far += len(chunk_df)
+                        self._emit_progress(
+                            progress_callback,
+                            started,
+                            stage="validating",
+                            table=table_id,
+                            chunk_index=chunk_idx + 1,
+                            chunk_total=total_chunks,
+                            rows_done=rows_done_so_far,
+                            rows_total=total_rows,
+                            errors_so_far=len(all_errors),
+                        )
+                        break
+
+                except Exception as e:
+                    logger.exception(f"分块校验异常: 表 {table_id} 分块 {chunk_idx}: {e}")
+                    all_errors.append(
+                        {
+                            "error_type": "ChunkValidationError",
+                            "stage": "constraint",
+                            "message": f"分块校验异常: {e}",
+                            "table": table_id,
+                            "chunk_index": chunk_idx,
+                        }
+                    )
+
+                # 累计当前分块行数（无论成功失败都已"处理"过）
+                rows_done_so_far += len(chunk_df)
+
+                # 进度：当前分块处理完成（更新 rows_done / errors_so_far）
+                self._emit_progress(
+                    progress_callback,
+                    started,
+                    stage="validating",
+                    table=table_id,
+                    chunk_index=chunk_idx + 1,
+                    chunk_total=total_chunks,
+                    rows_done=rows_done_so_far,
+                    rows_total=total_rows,
+                    errors_so_far=len(all_errors),
+                )
+
+        return all_parsed_datasets, all_errors, all_validation_details, chunk_interrupted
+
+    def _apply_chunked_global_validation(
+        self,
+        all_parsed_datasets: dict[str, list[pd.DataFrame]],
+        all_errors: list[dict],
+        all_validation_details: dict[str, list[dict]],
+        result: dict[str, Any],
+        options: ValidationOptions,
+        allow_unsafe_eval: bool,
+        deadline: float | None,
+        stop_on_first_error: bool,
+        chunk_interrupted: bool,
+    ) -> None:
+        """
+        @methoddesc 合并分块解析结果并执行全量 DAG 与约束校验（就地写入 result）
+
+        【设计意图】分块仅用于"加载与格式解析省内存"；Transform DAG 与约束校验
+        都需要全局数据，因此在所有块解析完成后 concat 为全量 parsed，再统一执行。
+        行变 transform 在分块下逐块执行会导致结果与全量不一致，故 DAG 移到
+        concat 后统一执行；必须在约束校验之前，因约束可能依赖 transform 产生的
+        派生列。全量约束校验修复跨表 ForeignKey（不再缺目标表）与跨块 Unique
+        （整列去重）的正确性。
+
+        参数:
+            all_parsed_datasets/all_errors/all_validation_details: _parse_chunks_loop 的聚合输出
+            result: 校验结果字典（就地写入 parsed_datasets/errors/validation_details/interrupted）
+            options: 校验选项
+            allow_unsafe_eval: 脚本执行权限
+            deadline: 校验阶段超时截止时间
+            stop_on_first_error: C6 遇错即停
+            chunk_interrupted: 分块阶段是否已因 stop 中断（中断则跳过约束校验）
+        """
+        merged_parsed: dict[str, pd.DataFrame] = {}
+        for table_id, dfs in all_parsed_datasets.items():
+            if dfs:
+                merged_parsed[table_id] = pd.concat(dfs, ignore_index=True)
+
+        merged_parsed, dag_errors = execute_dag_if_needed(
+            merged_parsed,
+            transform_files=getattr(self.loaded_project, "transform_files", None) if self.loaded_project else None,
+            regex_files=getattr(self.loaded_project, "regex_node_files", None) if self.loaded_project else None,
+        )
+        result["parsed_datasets"] = merged_parsed
+        # 回归 #6: 分块路径的 DAG 失败同样需上报(与标准路径 engine 行为一致)。
+        # 必须并入 all_errors——下方 result["errors"] = all_errors 整体重绑会覆盖
+        # 直接 append 进 result["errors"] 的内容，DAG 错误须在重绑前进入 all_errors。
+        for dag_err in dag_errors:
+            all_errors.append({"stage": "loading", **dag_err})
+
+        # C6: 若分块阶段已因 stop 中断,跳过约束校验(已停在前面的格式错误)。
+        if merged_parsed and not chunk_interrupted:
+            constraint_errors, constraint_details = validate_constraints(
+                merged_parsed,
+                self.dataset_schema,
+                all_errors=[],  # 约束阶段独立计错误，避免与分块格式错误混排
+                validation_details={
+                    "format_checks": [],  # 占位，下方合并时只取 constraint_checks
+                    "constraint_checks": [],
+                },
+                allow_unsafe_eval=allow_unsafe_eval,
+                table_filter=options.table_filter,
+                deadline=deadline,
+                stop_on_first_error=stop_on_first_error,
+            )
+            all_errors.extend(constraint_errors)
+            # 用全量约束结果替换分块阶段（分块循环 skip 了约束，constraint_checks 原本为空）
+            all_validation_details["constraint_checks"] = constraint_details.get("constraint_checks", [])
+
+        result["errors"] = all_errors
+        result["validation_details"] = all_validation_details
+        # C6: 分块阶段因 stop 中断,或约束阶段因 stop 中断,均标记 interrupted
+        if chunk_interrupted or (
+            stop_on_first_error and any(e.get("error_type") == "ValidationInterrupted" for e in all_errors)
+        ):
+            result["interrupted"] = True
+
+
+def create_executor(manifest_path: str, settings_override: dict[str, Any] | None = None) -> ValidationExecutor:
+    """
+    @methoddesc 创建校验执行器工厂函数
+
+    便捷函数，用于快速创建 ValidationExecutor 实例。
+
+    参数:
+        manifest_path: 项目清单文件路径
+        settings_override: 可选的设置覆盖值
+
+    返回:
+        ValidationExecutor 实例
+
+    示例:
+        >>> executor = create_executor("project.precis.yaml")
+        >>> result = executor.execute("./data")
+    """
+    return ValidationExecutor(manifest_path, settings_override)