precis-cli 0.1.3__py3-none-any.whl

app/shared/services/validation/loader.py

@@ -0,0 +1,152 @@
+# 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.
+r"""
+@fileoverview 校验加载器模块
+
+功能概述:
+- 提供数据文件加载功能,支持 Excel、CSV、JSON、JSON Lines 格式
+- 提供数据文件加载(load_file_data)，支持 FileProcessingSettings 配置
+- 支持编码自动检测、CSV 自定义分隔符
+- 支持 JSONPath 提取和嵌套 JSON 扁平化
+
+架构设计:
+- 文件加载层处理格式和编码,校验层(UnifiedValidationService/校验流水线)专注业务逻辑
+- 编码检测采用优先级策略: UTF-8 -> GBK -> GB2312 -> GB18030 -> Big5 -> Latin1
+
+输入示例:
+    # 加载 Excel 文件
+    df = load_file_data(
+        source_file_path="data/users.xlsx",
+        sheet_name="Sheet1",
+        header_row=0
+    )
+
+    # 带配置加载 CSV
+    settings = FileProcessingSettings(default_encoding="utf-8", csv_delimiter=",")
+    df = load_file_data("data/products.csv", settings=settings)
+
+输出示例:
+    # 返回 pandas DataFrame
+    #    id  name  email
+    # 0   1  张三  zhangsan@example.com
+"""
+
+import logging
+import os
+from typing import TYPE_CHECKING, Any, Optional
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from app.shared.core.project.manifest.types_parts.settings_file_processing import FileProcessingSettings
+
+
+def load_file_data(
+    source_file_path: str,
+    sheet_name: str | None = None,
+    header_row: int = 0,
+    settings: Optional["FileProcessingSettings"] = None,
+    source_config: dict[str, Any] | None = None,
+) -> pd.DataFrame:
+    """
+    @methoddesc 加载数据文件为基础 DataFrame
+
+    读取指定路径的数据文件（Excel、CSV 或 JSON），并转换为 pandas DataFrame 进行处理。
+    支持通过 source_config 传递高级配置（如 JSON 的 json_path、format 等），
+    或通过 settings 对象传递编码/分隔符配置。
+
+    支持的文件格式：
+    - Excel (.xlsx, .xls): 使用 openpyxl 引擎，支持多 sheet
+    - CSV (.csv): 默认 UTF-8 编码
+    - JSON (.json): 支持对象数组和嵌套对象（自动扁平化）
+    - JSON Lines (.jsonl, .ndjson): 每行一个 JSON 对象，适合大文件
+
+    参数:
+        source_file_path: 源文件路径
+        sheet_name: Excel 工作表名称（可选）
+        header_row: 用作列名的行索引，默认为 0
+        settings: 文件处理配置对象（可选），优先级高于 source_config
+        source_config: 数据源配置字典（可选）
+
+    返回:
+        转换后的 pandas DataFrame 对象，空值被统一处理为 None
+    """
+    if not os.path.exists(source_file_path):
+        raise FileNotFoundError(f"文件不存在: {source_file_path}")
+
+    from app.shared.core.data_source.loaders import load_source_data
+    from app.shared.core.data_source.specs.base import DataSourceSpec
+    from app.shared.core.data_source.specs.csv_source import CSVSourceSpec
+    from app.shared.core.data_source.specs.excel_source import ExcelSourceSpec
+    from app.shared.core.data_source.specs.json_source import JSONSourceSpec
+
+    spec: DataSourceSpec
+
+    file_ext = os.path.splitext(source_file_path)[1].lower()
+    sc = source_config or {}
+
+    encoding = "utf-8"
+    delimiter = ","
+    if settings:
+        encoding = settings.default_encoding if settings.default_encoding != "auto" else "utf-8"
+        delimiter = settings.csv_delimiter if settings.csv_delimiter != "auto" else ","
+
+    header_enabled = header_row >= 0
+    effective_header_row = header_row if header_row >= 0 else 0
+
+    if file_ext in [".xlsx", ".xls"]:
+        spec = ExcelSourceSpec(
+            path=source_file_path,
+            sheet=sheet_name,
+            header_row=effective_header_row,
+            header_enabled=header_enabled,
+        )
+    elif file_ext == ".csv":
+        spec = CSVSourceSpec(
+            path=source_file_path,
+            header_row=effective_header_row,
+            header_enabled=header_enabled,
+            encoding=sc.get("encoding", encoding),
+            delimiter=sc.get("delimiter", delimiter),
+        )
+    elif file_ext in [".json", ".jsonl", ".ndjson"]:
+        # 前端使用 json_format 字段透传 JSON 解析格式，兼容 format 别名
+        # D8: format 必填(auto 已废弃);.jsonl/.ndjson 强制 lines;其余由配置显式指定
+        fmt = sc.get("format") or sc.get("json_format") or "array"
+        if file_ext in [".jsonl", ".ndjson"]:
+            fmt = "lines"
+        spec = JSONSourceSpec(
+            path=source_file_path,
+            header_row=effective_header_row,
+            header_enabled=header_enabled,
+            format=fmt,
+            json_path=sc.get("json_path"),
+            record_path=sc.get("record_path"),
+            meta_prefix=sc.get("meta_prefix", "meta."),
+            sep=sc.get("sep", "."),
+            dtype=sc.get("dtype"),
+            flatten=sc.get("flatten", True),
+        )
+    else:
+        raise ValueError(f"不支持的文件类型: {file_ext}")
+
+    df = load_source_data(spec)
+    df = df.where(pd.notnull(df), None)
+    df = df.replace("", None)
+
+    return df

app/shared/services/validation/memory_monitor.py

@@ -0,0 +1,179 @@
+# 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 内存监控工具模块
+
+功能概述:
+- 提供文件大小检测和内存使用监控
+- 支持自动判断是否需要分块处理
+- 记录校验过程中的内存使用情况
+
+架构设计:
+- 纯工具模块，无外部依赖（仅使用标准库 + psutil 可选）
+- 由 ValidationExecutor 调用，决定是否启用分块模式
+
+使用示例:
+    monitor = MemoryMonitor(chunk_threshold_mb=500)
+    if monitor.should_chunk(file_path):
+        # 使用分块加载
+        pass
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+# 默认分块阈值（MB）
+DEFAULT_CHUNK_THRESHOLD_MB = 500
+
+# 每个分块的目标行数（CSV 分块读取用）
+DEFAULT_CHUNK_ROWS = 100_000
+
+
+def _get_psutil_memory() -> dict[str, float] | None:
+    """尝试使用 psutil 获取系统内存信息，不可用时返回 None。"""
+    try:
+        import psutil
+
+        mem = psutil.virtual_memory()
+        return {
+            "total_mb": mem.total / (1024 * 1024),
+            "available_mb": mem.available / (1024 * 1024),
+            "used_mb": mem.used / (1024 * 1024),
+            "percent": mem.percent,
+        }
+    except ImportError:
+        return None
+
+
+@dataclass
+class MemorySnapshot:
+    """内存快照，记录某个时间点的内存使用情况。"""
+
+    file_path: str
+    file_size_mb: float
+    system_memory: dict[str, float] | None = None
+    timestamp: float = 0.0
+
+    def to_dict(self) -> dict:
+        result = {
+            "file_path": self.file_path,
+            "file_size_mb": round(self.file_size_mb, 2),
+        }
+        if self.system_memory:
+            result["system_memory"] = {k: round(v, 2) for k, v in self.system_memory.items()}
+        return result
+
+
+@dataclass
+class MemoryMonitor:
+    """
+    @classdesc 内存监控器
+
+    负责：
+    - 检测文件大小，判断是否需要分块处理
+    - 记录内存使用快照
+    - 提供分块建议（chunk_size 行数）
+
+    属性:
+        chunk_threshold_mb: 触发分块模式的文件大小阈值（MB），默认 500MB
+        chunk_rows: 每个分块的默认行数，默认 100,000
+        snapshots: 记录的内存快照列表
+    """
+
+    chunk_threshold_mb: float = DEFAULT_CHUNK_THRESHOLD_MB
+    chunk_rows: int = DEFAULT_CHUNK_ROWS
+    snapshots: list[MemorySnapshot] = field(default_factory=list)
+
+    def get_file_size_mb(self, file_path: str) -> float:
+        """获取文件大小（MB）。"""
+        try:
+            size_bytes = os.path.getsize(file_path)
+            return size_bytes / (1024 * 1024)
+        except OSError:
+            return 0.0
+
+    def should_chunk(self, file_path: str) -> bool:
+        """
+        @methoddesc 判断指定文件是否需要分块处理
+
+        基于文件大小阈值判断。当文件大于 chunk_threshold_mb 时返回 True。
+
+        参数:
+            file_path: 文件路径
+
+        返回:
+            True 表示需要分块处理
+        """
+        size_mb = self.get_file_size_mb(file_path)
+        return size_mb > self.chunk_threshold_mb
+
+    def take_snapshot(self, file_path: str) -> MemorySnapshot:
+        """
+        @methoddesc 记录内存快照
+
+        拍摄当前内存使用快照并追加到 snapshots 列表。
+
+        参数:
+            file_path: 正在处理的文件路径
+
+        返回:
+            MemorySnapshot 实例
+        """
+        snapshot = MemorySnapshot(
+            file_path=file_path,
+            file_size_mb=self.get_file_size_mb(file_path),
+            system_memory=_get_psutil_memory(),
+        )
+        self.snapshots.append(snapshot)
+        logger.info(
+            f"内存快照: 文件={os.path.basename(file_path)}, "
+            f"大小={snapshot.file_size_mb:.1f}MB"
+            + (f", 可用内存={snapshot.system_memory['available_mb']:.0f}MB" if snapshot.system_memory else "")
+        )
+        return snapshot
+
+    def get_chunk_count(self, total_rows: int) -> int:
+        """
+        @methoddesc 计算给定总行数需要多少个分块
+
+        参数:
+            total_rows: 总行数
+
+        返回:
+            分块数量（至少为 1）
+        """
+        if total_rows <= 0:
+            return 1
+        return max(1, (total_rows + self.chunk_rows - 1) // self.chunk_rows)
+
+    def get_progress_info(self) -> dict:
+        """
+        @methoddesc 获取内存监控摘要信息
+
+        返回:
+            包含快照数量和最新快照信息的字典
+        """
+        return {
+            "snapshot_count": len(self.snapshots),
+            "latest_snapshot": self.snapshots[-1].to_dict() if self.snapshots else None,
+            "chunk_threshold_mb": self.chunk_threshold_mb,
+            "chunk_rows": self.chunk_rows,
+        }

app/shared/services/validation/postprocess.py

@@ -0,0 +1,208 @@
+# 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 校验结果后处理
+
+对校验结果字典做用户可读化加工：内部表 ID 替换为显示名称、附加
+数据源文件与 Sheet 信息。纯字典变换，无 I/O 依赖；标准模式与分块
+模式共用（ValidationExecutor._postprocess_result 委托至此）。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from app.shared.core.project.schema.types import TableSchemaFile
+from app.shared.domain.dataset_schema import DataSetSchema
+
+# UUID 形态（任意版本）：8-4-4-4-12 十六进制。表 ID 均为该形态，而真实
+# 表名/列名/文件名不可能撞上该格式，用正则做文本内 ID→名称替换零误伤。
+_UUID_TOKEN_RE = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
+
+# 条目中可能内嵌表 ID 的文本字段（message 为域约束/格式错误主文本，
+# description 为 constraint_checks 描述，suggestion 为加载错误修复建议）
+_ID_TEXT_FIELDS = ("message", "error_message", "description", "suggestion")
+
+
+def build_table_source_map(schema_by_id: dict[str, TableSchemaFile]) -> dict[str, dict[str, str | None]]:
+    """构建表 ID 到数据源信息的映射字典。
+
+    用于在校验结果中附加数据源文件名和 Sheet 名，
+    使前端能够显示"配置文件内定义的文件名+Sheet名"格式的位置信息。
+
+    参数:
+        schema_by_id: 表 ID 到 Schema 文件的映射
+
+    返回:
+        映射字典，键为表 ID，值为 {"source_file": ..., "source_sheet": ...}
+    """
+    result: dict[str, dict[str, str | None]] = {}
+    for table_id, schema_file in schema_by_id.items():
+        source_file = None
+        source_sheet = None
+        if schema_file.source:
+            source_file = schema_file.source.path
+            source_sheet = schema_file.source.sheet
+        if not source_sheet and schema_file.sheet:
+            source_sheet = schema_file.sheet
+        result[table_id] = {"source_file": source_file, "source_sheet": source_sheet}
+    return result
+
+
+def attach_source_info(
+    item: dict[str, Any],
+    table_source_map: dict[str, dict[str, str | None]],
+    name_to_id: dict[str, str] | None = None,
+) -> None:
+    """将数据源信息附加到错误/通过项字典中。
+
+    根据 item 中的 table 或 table_id 查找对应的数据源配置，
+    并将 source_file 和 source_sheet 写入 item。
+
+    §1.30: postprocess_result 先 map_table_id（把 table 换成显示名）再 attach——
+    约束错误条目只有 table 键（无 table_id），被换成显示名后直查恒 miss。
+    这里按 name_to_id 反查回退，约束错误与格式错误同样获得 source_file 定位。
+
+    参数:
+        item: 包含 table/table_id 的字典（会被就地修改）
+        table_source_map: 表 ID → 数据源信息的映射
+        name_to_id: 显示名 → 表 ID 的反查映射（可选）
+    """
+    table_id = item.get("table_id") or item.get("table")
+    if table_id not in table_source_map and name_to_id and table_id in name_to_id:
+        table_id = name_to_id[table_id]
+    if table_id and table_id in table_source_map:
+        item["source_file"] = table_source_map[table_id]["source_file"]
+        item["source_sheet"] = table_source_map[table_id]["source_sheet"]
+
+
+def build_id_to_name_map(dataset_schema: DataSetSchema) -> dict[str, str]:
+    """构建表 ID 到显示名称的映射字典。
+
+    用于在校验结果中将内部表 ID 替换为用户友好的表名称。
+
+    参数:
+        dataset_schema: 数据集 Schema 定义
+
+    返回:
+        映射字典，键为表 ID，值为表显示名称
+    """
+    id_to_name: dict[str, str] = {}
+    if dataset_schema and dataset_schema.tables:
+        for tid, schema in dataset_schema.tables.items():
+            target_name = schema.name or tid
+            if schema.id:
+                id_to_name[schema.id] = target_name
+            id_to_name[tid] = target_name
+    return id_to_name
+
+
+def map_table_id(item: dict[str, Any], id_to_name: dict[str, str]) -> None:
+    """将错误信息中的表 ID 替换为表显示名称。
+
+    就地修改传入的字典，将 table/from_table/to_table 字段中的
+    内部 ID 替换为用户可读的名称。
+
+    参数:
+        item: 包含表相关字段的错误信息字典
+        id_to_name: ID 到名称的映射字典
+    """
+    for key in ("table", "from_table", "to_table"):
+        if key in item and item[key] in id_to_name:
+            # 重写为显示名前保留原 ID 到 {key}_id（不覆盖已有键）：下游按 ID
+            # 定位的消费方（json_payload 的 tables 行数查 raw_datasets、
+            # attach_source_info 直查）不因显示名化而失联
+            id_key = f"{key}_id"
+            if id_key not in item:
+                item[id_key] = item[key]
+            item[key] = id_to_name[item[key]]
+
+
+def rewrite_id_tokens(text: Any, id_to_name: dict[str, str]) -> Any:
+    """将文本中 UUID 形态的表 ID 替换为显示名称（查不到映射时原样保留）。
+
+    域约束构造时注入的 from_table/to_table 等字段是数据集查表键（表 ID），
+    错误消息/描述里直接插值导致用户看到 UUID 而非表名。map_table_id 只
+    重写条目顶层字段，不碰文本，这里补齐文本侧。悬空引用（表已不存在，
+    无名称可映射）保留原 ID——那是用户在配置里定位它的唯一线索。
+
+    参数:
+        text: 任意取值（非字符串原样返回）
+        id_to_name: 表 ID 到显示名称的映射
+
+    返回:
+        重写后的文本（或原值）
+    """
+    if not isinstance(text, str) or not id_to_name:
+        return text
+
+    def _replace(match: re.Match[str]) -> str:
+        token = match.group(0)
+        # 映射键为存储原值（通常小写）；正则大小写不敏感，双口径查一次
+        return id_to_name.get(token, id_to_name.get(token.lower(), token))
+
+    return _UUID_TOKEN_RE.sub(_replace, text)
+
+
+def humanize_item_texts(item: dict[str, Any], id_to_name: dict[str, str]) -> None:
+    """就地重写条目文本字段中 UUID 形态的表 ID 为显示名称。
+
+    参数:
+        item: 错误/检查条目字典（会被就地修改）
+        id_to_name: 表 ID 到显示名称的映射
+    """
+    for key in _ID_TEXT_FIELDS:
+        if key in item:
+            item[key] = rewrite_id_tokens(item[key], id_to_name)
+
+
+def postprocess_result(
+    result: dict[str, Any], dataset_schema: DataSetSchema, schema_by_id: dict[str, TableSchemaFile]
+) -> None:
+    """对校验结果做统一后处理（ID→名称映射 + 数据源信息附加，就地修改）。
+
+    遍历 errors / loading_errors / validation_details 中的全部条目，
+    逐项应用 map_table_id 与 attach_source_info。
+
+    参数:
+        result: 校验结果字典（会被就地修改）
+        dataset_schema: 数据集 Schema 定义
+        schema_by_id: 表 ID 到 Schema 文件的映射
+    """
+    id_to_name = build_id_to_name_map(dataset_schema)
+    table_source_map = build_table_source_map(schema_by_id)
+    # 显示名 → 表 ID 反查（§1.30: map_table_id 先行把约束错误的 table 换成显示名，
+    # attach 需要反查才能命中；同名的多表取后者，展示层容错）
+    name_to_id = {name: tid for tid, name in id_to_name.items()}
+
+    for error in result["errors"]:
+        map_table_id(error, id_to_name)
+        humanize_item_texts(error, id_to_name)
+        attach_source_info(error, table_source_map, name_to_id)
+    for error in result["loading_errors"]:
+        map_table_id(error, id_to_name)
+        humanize_item_texts(error, id_to_name)
+        attach_source_info(error, table_source_map, name_to_id)
+    if "format_checks" in result["validation_details"]:
+        for item in result["validation_details"]["format_checks"]:
+            map_table_id(item, id_to_name)
+            humanize_item_texts(item, id_to_name)
+            attach_source_info(item, table_source_map, name_to_id)
+    if "constraint_checks" in result["validation_details"]:
+        for item in result["validation_details"]["constraint_checks"]:
+            map_table_id(item, id_to_name)
+            humanize_item_texts(item, id_to_name)
+            attach_source_info(item, table_source_map, name_to_id)

app/shared/services/validation/progress.py

@@ -0,0 +1,64 @@
+# 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/progress.py
+"""
+@fileoverview 校验进度事件
+
+功能概述:
+- 定义 ProgressEvent 数据类，用于校验执行器向调用方（TUI/API）上抛进度。
+- 作为旁路通道：不影响 ValidationResult，仅用于实时展示（sparkline/进度条）。
+- 校验执行器在阶段切换/分块边界构造事件并回调 progress_callback。
+
+设计要点:
+- 纯数据 dataclass，无逻辑依赖，便于跨层传递与单测。
+- rows_total 为预估值（无法预估时为 0），调用方需容忍 0。
+- chunk_index 为 1-based（非分块模式恒为 0），与日志/错误中的 chunk_index 口径一致。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ProgressEvent:
+    """校验进度事件（上抛给调用方用于实时展示）。
+
+    Attributes:
+        stage: 当前阶段，取值 "loading" | "validating" | "done"。
+            - loading: 数据加载阶段（表粒度或加载完成）
+            - validating: 校验执行阶段（分块粒度或整体前后）
+            - done: 校验完成（含后处理）
+        table: 当前处理的表名；loading 阶段未确定时可为 None。
+        chunk_index: 当前分块序号（1-based）；非分块模式恒为 0。
+        chunk_total: 总分块数；非分块模式恒为 0。
+        rows_done: 累计已处理行数。
+        rows_total: 总行数（预估，无法预估时为 0）。
+        errors_so_far: 累计错误数。
+        elapsed_ms: 已耗时（毫秒）。
+    """
+
+    stage: str
+    table: str | None
+    chunk_index: int
+    chunk_total: int
+    rows_done: int
+    rows_total: int
+    errors_so_far: int
+    elapsed_ms: int
+
+
+__all__ = ["ProgressEvent"]