precis-cli 0.1.3__py3-none-any.whl

app/api/routers/validation/inline_mode.py

@@ -0,0 +1,196 @@
+# 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 数据校验路由模块（基于行内数据）
+
+功能概述:
+- 提供基于行内数据（TransformOutput / ManualData 节点）的校验接口
+- 直接接收二维数组行数据，无需文件路径
+- 支持多种校验类型（唯一性、非空、允许值、区间、字符集、脚本、外键等）
+- 通过 UnifiedValidationService 统一调度各类校验逻辑
+
+架构设计:
+- 基于 FastAPI APIRouter 组织路由，挂载到 /validation 前缀下
+- 将行数据转为 pandas DataFrame，复用 execute_dataframe_validation 流水线
+- 统一返回 ValidationResponse 标准化响应结构
+
+输入示例:
+    POST /validate/inline
+    Body:
+    {
+      "validation_type": "not_null",
+      "target_column_name": "name",
+      "rows": [["name", "age"], ["Alice", "25"], ["", "30"], ["Bob", ""]]
+    }
+
+输出示例:
+    {
+      "success": true,
+      "validation_type": "not_null",
+      "data": {
+        "is_valid": false,
+        "error_count": 1,
+        "total_rows": 3,
+        "error_rows": [{"row_index": 1, "cell_value": "", "error_message": null}],
+        "validation_time": "0.001s"
+      },
+      "error": null
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pandas as pd
+
+from app.api.models import InlineValidationRequest, ValidationResponse
+from app.api.routers.validation.common import execute_dataframe_validation
+
+from .router import router
+
+logger = logging.getLogger(__name__)
+
+
+def _infer_column_type(series: pd.Series) -> str | None:
+    """推断行内数据列的类型，无 Schema 声明时辅助数值比较等场景。
+
+    规则:
+    - 所有非空值均为整数格式时返回 "integer"
+    - 所有非空值均为数值格式（含小数）时返回 "decimal"
+    - 已经是 pandas 数值类型时直接返回对应类型
+    - 其他情况返回 None，保持原始字符串类型
+    """
+    if series.empty:
+        return None
+
+    non_null = series.dropna()
+    if non_null.empty:
+        return None
+
+    # 已经是 pandas 数值类型
+    if pd.api.types.is_numeric_dtype(non_null):
+        return "integer" if pd.api.types.is_integer_dtype(non_null) else "decimal"
+
+    str_values = non_null.astype(str)
+
+    # 整数格式
+    if str_values.str.fullmatch(r"^-?\d+$").all():
+        return "integer"
+
+    # 数值格式（含小数）
+    numeric = pd.to_numeric(str_values, errors="coerce")
+    if numeric.notna().all():
+        return "decimal"
+
+    return None
+
+
+@router.post(
+    "/validate/inline",
+    response_model=ValidationResponse,
+    summary="基于行内数据的校验（Inline 模式）",
+    # 行为约定：本端点永远返回 200，业务失败以 success=false + error 字段表达，不产生 500
+    responses={
+        200: {
+            "description": "校验已执行；业务失败（行数据为空、列不存在、校验异常等）同样返回 200，以 success=false + error 字段表达",
+        },
+    },
+)
+def validate_data_inline(request: InlineValidationRequest) -> ValidationResponse:
+    """
+    基于行内数据的校验接口（Inline 模式）。
+
+    专为前端纯数据节点（TransformOutput / ManualData）设计，
+    直接接收二维行数据数组，转换为 DataFrame 后复用统一校验流水线。
+
+    参数:
+        request (InlineValidationRequest): 校验请求体，包含行数据、校验类型、目标列、配置等
+
+    返回值:
+        ValidationResponse: 标准化校验响应
+
+    业务逻辑:
+        1. 验证 rows 数据不为空
+        2. 根据是否提供 column_names，决定表头来源（第一行 or column_names）
+        3. 构建 pandas DataFrame
+        4. 对目标列做类型推断（与文件加载行为保持一致）
+        5. 调用 execute_dataframe_validation 执行校验
+        6. 捕获异常并返回友好错误信息
+
+    错误语义:
+        所有业务失败与意外异常（行数据为空、列不存在、校验出错等）均在本端点内
+        捕获并转为 success=false + error 字段随 HTTP 200 返回，不抛出 500。
+    """
+    try:
+        # 验证行数据不为空
+        if not request.rows:
+            return ValidationResponse(
+                success=False,
+                validation_type=request.validation_type,
+                data=None,
+                error="行数据不能为空",
+            )
+
+        # 构建 DataFrame：根据 column_names 决定表头来源
+        if request.column_names:
+            # column_names 已提供：所有 rows 均为数据行
+            df = pd.DataFrame(request.rows, columns=request.column_names)
+        else:
+            # 默认：第一行为表头，其余为数据行
+            if len(request.rows) < 2:
+                return ValidationResponse(
+                    success=False,
+                    validation_type=request.validation_type,
+                    data=None,
+                    error="行数据至少需要包含表头行和一行数据",
+                )
+            header = [str(col) for col in request.rows[0]]
+            df = pd.DataFrame(request.rows[1:], columns=header)
+
+        logger.info(
+            f"[INLINE] 收到行内校验请求: type={request.validation_type}, "
+            f"column={request.target_column_name}, rows={len(df)}"
+        )
+
+        # 委托给共享流水线执行校验
+        # 传递 column_data_type 让后端按 Schema 类型转换，保持与全量校验一致
+        # 若请求未提供类型，则根据目标列内容自动推断数值类型，避免行内数字字符串
+        # 在脚本/区间等数值比较场景下因类型错误而失败
+        column_data_type = request.column_data_type
+        if not column_data_type and request.target_column_name in df.columns:
+            column_data_type = _infer_column_type(df[request.target_column_name])
+
+        return execute_dataframe_validation(
+            df=df,
+            validation_type=request.validation_type,
+            target_column_name=request.target_column_name,
+            validation_config=request.validation_config,
+            allow_unsafe_eval=request.allow_unsafe_eval,
+            column_data_type=column_data_type,
+        )
+
+    except Exception as e:
+        logger.error(f"[INLINE] 行内校验异常: {str(e)}")
+        import traceback
+
+        traceback.print_exc()
+        return ValidationResponse(
+            success=False,
+            validation_type=request.validation_type,
+            data=None,
+            error=f"行内校验过程中发生错误: {str(e)}",
+        )

app/api/routers/validation/path_mode.py

@@ -0,0 +1,314 @@
+# 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 数据校验路由模块（基于文件路径访问）
+
+功能概述:
+- 提供基于文件路径的数据校验接口
+- 支持多种校验类型（唯一性、非空、允许值、外键、正则等）
+- 支持正则表达式校验（含匹配模式、大小写敏感等参数）
+- 支持批量校验请求处理
+- 通过 UnifiedValidationService 统一调度各类校验逻辑
+
+架构设计:
+- 基于 FastAPI APIRouter 组织路由，挂载到 /validation 前缀下
+- 直接通过文件路径加载数据，无需上传文件
+- 统一返回 ValidationResponse / RegexValidationResponse 标准化响应结构
+
+输入示例:
+    POST /validate/path
+    Body:
+    {
+      "source_file_path": "/data/users.xlsx",
+      "validation_type": "Unique",
+      "target_column_name": "email",
+      "sheet_name": "Sheet1",
+      "header_row": 0,
+      "validation_config": {"case_sensitive": true}
+    }
+
+输出示例:
+    {
+      "success": true,
+      "validation_type": "Unique",
+      "data": {
+        "is_valid": false,
+        "error_count": 3,
+        "total_rows": 100,
+        "match_count": null,
+        "error_rows": [{"row_index": 5, "cell_value": "dup@example.com", "error_message": "重复值"}],
+        "validation_time": 0.12
+      },
+      "error": null
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import HTTPException
+
+from app.api.models import (
+    RegexValidationRequest,
+    RegexValidationResponse,
+    ValidationRequest,
+    ValidationResponse,
+)
+from app.api.routers.validation.common import (
+    convert_validation_result_to_regex,
+    execute_standard_validation,
+)
+from app.shared.services.preview.path_validation import validate_file_access
+from app.shared.services.validation import UnifiedValidationService, ValidationType, load_file_data
+
+from .router import router
+
+logger = logging.getLogger(__name__)
+
+
+@router.post(
+    "/validate/path",
+    response_model=ValidationResponse,
+    summary="基于文件路径的单条数据校验（Path 模式）",
+    # 行为约定：本端点永远返回 200，业务失败以 success=false + error 字段表达，不产生 404/500
+    responses={
+        200: {
+            "description": "校验已执行；业务失败（文件未找到、路径非法、校验异常等）同样返回 200，以 success=false + error 字段表达",
+        },
+    },
+)
+def validate_data_with_path(request: ValidationRequest) -> ValidationResponse:
+    """
+    基于文件路径的单条数据校验接口（Path 模式）。
+
+    参数:
+        request (ValidationRequest): 校验请求体，包含文件路径、校验类型、目标列、配置等
+
+    返回值:
+        ValidationResponse: 标准化校验响应
+
+    业务逻辑:
+        1. 记录基本信息日志
+        2. 校验文件路径是否为空
+        3. 调用 validate_file_path 校验路径格式合法性
+        4. 检查文件是否在磁盘上真实存在
+        5. 确定表头行号并加载数据文件
+        6. 检查目标列是否存在
+        7. 调用 UnifiedValidationService.validate 执行具体校验
+        8. 转换错误行数据并组装响应
+        9. 记录校验完成状态，捕获并处理异常
+
+    错误语义:
+        所有业务失败与意外异常（文件未找到、路径非法、校验出错等）均在本端点内
+        捕获并转为 success=false + error 字段随 HTTP 200 返回，不抛出 404/500。
+    """
+    try:
+        # 记录收到的路径校验请求信息，便于排查问题
+        logger.info(f"[VALIDATION] 收到路径校验请求: {request.source_file_path}")
+        logger.info(f"[VALIDATION] 校验类型: {request.validation_type}, 目标列: {request.target_column_name}")
+
+        source_file_path = request.source_file_path
+
+        # 检查文件路径是否为空，为空则直接返回错误
+        if not source_file_path:
+            return ValidationResponse(
+                success=False, validation_type=request.validation_type, data=None, error="文件路径不能为空"
+            )
+
+        # 校验文件路径格式是否合法（如防止路径遍历攻击）
+        validate_file_access(source_file_path)
+
+        response = execute_standard_validation(
+            source_file_path=source_file_path,
+            sheet_name=request.sheet_name,
+            header_row=request.header_row,
+            validation_type=request.validation_type,
+            target_column_name=request.target_column_name,
+            validation_config=request.validation_config,
+            column_data_type=request.column_data_type,
+            source_config=request.to_source_config(),
+            # B14 修复：透传 allow_unsafe_eval，过去遗漏导致 Path 模式下脚本约束恒为 False
+            allow_unsafe_eval=request.allow_unsafe_eval,
+        )
+
+        # 记录校验完成状态
+        if response.success and response.data:
+            logger.info(f"[VALIDATION] 路径校验完成: 成功={response.data.is_valid}, 错误数={response.data.error_count}")
+
+        return response
+
+    except FileNotFoundError as e:
+        return ValidationResponse(success=False, validation_type=request.validation_type, data=None, error=str(e))
+    except HTTPException as e:
+        return ValidationResponse(success=False, validation_type=request.validation_type, data=None, error=e.detail)
+    except Exception as e:
+        # 捕获所有未预期异常，记录详细堆栈并返回友好错误信息
+        logger.error(f"[VALIDATION] 路径校验异常: {str(e)}")
+        import traceback
+
+        traceback.print_exc()
+        return ValidationResponse(
+            success=False,
+            validation_type=request.validation_type,
+            data=None,
+            error=f"校验过程中发生错误: {str(e)}",
+        )
+
+
+@router.post(
+    "/regex/path",
+    response_model=RegexValidationResponse,
+    summary="基于文件路径的正则表达式校验（Path 模式）",
+    # 行为约定：本端点永远返回 200，业务失败以 success=false + error 字段表达，不产生 404/500
+    responses={
+        200: {
+            "description": "校验已执行；业务失败（文件未找到、路径非法、校验异常等）同样返回 200，以 success=false + error 字段表达",
+        },
+    },
+)
+def validate_regex_with_path(request: RegexValidationRequest) -> RegexValidationResponse:
+    """
+    基于文件路径的正则表达式校验接口（Path 模式）。
+
+    参数:
+        request (RegexValidationRequest): 正则校验请求体，包含文件路径、正则模式、
+                                         匹配模式、大小写敏感设置、目标列等
+
+    返回值:
+        RegexValidationResponse: 正则校验专用响应模型
+
+    业务逻辑:
+        1. 记录基本信息日志
+        2. 校验文件路径是否为空
+        3. 调用 validate_file_path 校验路径格式合法性
+        4. 检查文件是否在磁盘上真实存在
+        5. 加载数据文件，支持自定义表头配置
+        6. 检查目标列是否存在
+        7. 调用 UnifiedValidationService.validate 执行 REGEX 类型校验
+        8. 使用 convert_validation_result_to_regex 转换结果
+        9. 记录校验完成状态，返回响应
+
+    错误语义:
+        所有业务失败与意外异常（文件未找到、路径非法、校验出错等）均在本端点内
+        捕获并转为 success=false + error 字段随 HTTP 200 返回，不抛出 404/500。
+    """
+    try:
+        # 记录收到的路径正则校验请求信息
+        logger.info(f"[REGEX] 收到路径正则校验请求: {request.source_file_path}")
+        logger.info(f"[REGEX] 正则模式: {request.regex_pattern}, 目标列: {request.target_column_name}")
+
+        source_file_path = request.source_file_path
+
+        # 检查文件路径是否为空
+        if not source_file_path:
+            return RegexValidationResponse(success=False, data=None, error="文件路径不能为空")
+
+        # 校验文件路径格式合法性
+        validate_file_access(source_file_path)
+
+        # 加载数据文件，支持自定义表头
+        df = load_file_data(
+            source_file_path=source_file_path,
+            sheet_name=request.sheet_name,
+        )
+
+        # 检查目标列是否存在于数据中
+        if request.target_column_name not in df.columns:
+            return RegexValidationResponse(success=False, data=None, error=f"未找到列: {request.target_column_name}")
+
+        # 调用统一校验服务执行正则校验
+        result = UnifiedValidationService.validate(
+            validation_type=ValidationType.REGEX,
+            df=df,
+            column=request.target_column_name,
+            regex_pattern=request.regex_pattern,
+            regex_flags=request.regex_flags or "",
+            match_mode=request.match_mode,
+            case_sensitive=request.case_sensitive,
+        )
+
+        # 将通用校验结果转换为正则专用响应模型
+        regex_result = convert_validation_result_to_regex(result)
+
+        # 记录正则校验完成状态
+        logger.info(f"[REGEX] 路径正则校验完成: 成功={result.is_valid}, 匹配数={result.match_count}")
+
+        return RegexValidationResponse(success=True, data=regex_result, error=None)
+
+    except FileNotFoundError as e:
+        return RegexValidationResponse(success=False, data=None, error=str(e))
+    except HTTPException as e:
+        return RegexValidationResponse(success=False, data=None, error=e.detail)
+    except Exception as e:
+        logger.error(f"[REGEX] 路径正则校验异常: {str(e)}")
+        import traceback
+
+        traceback.print_exc()
+        return RegexValidationResponse(success=False, data=None, error=f"校验过程中发生错误: {str(e)}")
+
+
+@router.post(
+    "/validate/path/batch",
+    response_model=dict,
+    summary="批量数据校验（Path 模式）",
+    # 行为约定：单条校验的失败已被 validate_data_with_path 逐条捕获，整体仍返回 200
+    responses={
+        200: {
+            "description": "批量校验已执行；单条失败不改变整体状态码，失败体现在该条目的 success=false 与 error 字段",
+        },
+    },
+)
+def validate_batch_with_path(requests: list[ValidationRequest]) -> dict[str, Any]:
+    """
+    批量数据校验接口（基于文件路径）。
+
+    参数:
+        requests (list[ValidationRequest]): 校验请求对象列表，每个元素包含文件路径和校验配置
+
+    返回值:
+        dict: 包含 results 键的字典，值为所有单条校验结果的列表
+
+    业务逻辑:
+        1. 遍历传入的请求列表
+        2. 对每个请求调用 validate_data_with_path 执行单条路径模式校验
+        3. 收集每条请求的校验类型、目标列、成功状态、结果数据和错误信息
+        4. 将所有结果组装为统一字典返回
+
+    错误语义:
+        单条请求的失败由 validate_data_with_path 捕获并写入对应条目的
+        success=false 与 error 字段，批量接口本身始终返回 200。
+    """
+    # 存储所有批量校验结果的列表
+    results = []
+    # 逐条处理每个校验请求
+    for request in requests:
+        # 复用路径模式单条校验接口的逻辑
+        response = validate_data_with_path(request)
+        # 提取关键信息组装为简洁的结果字典
+        results.append(
+            {
+                "validation_type": request.validation_type,
+                "target_column": request.target_column_name,
+                "success": response.success,
+                # 如果校验成功且有数据，将结果对象转为字典；否则为 None
+                "result": response.data.model_dump() if response.data else None,
+                "error": response.error,
+            }
+        )
+    # 返回包含所有结果的响应字典
+    return {"results": results}

app/api/routers/validation/router.py

@@ -0,0 +1,51 @@
+# 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 数据校验路由入口模块
+
+功能概述:
+- 创建并导出数据校验模块的 FastAPI APIRouter 实例
+- 作为数据校验相关路由的注册入口，供上层应用统一挂载
+
+架构设计:
+- 使用 FastAPI 的 APIRouter 创建路由实例
+- 设置 tags=["Data Validation"] 便于 Swagger/OpenAPI 文档分类展示
+- prefix 由上层应用通过 include_router 时指定，本模块保持为空
+
+输入示例:
+    from app.api.routers.validation.router import router
+    app.include_router(router, prefix="/validation")
+
+输出示例:
+    无直接输出，提供配置好的 APIRouter 实例
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+# 创建数据校验模块的路由实例，tags 用于在 API 文档中分组展示
+router = APIRouter(prefix="/api/latest", tags=["Data Validation"])
+
+# 导入子模块以注册其路由（content_mode、inline_mode 和 path_mode 通过 from .router import router 装饰本实例）
+from . import content_mode, inline_mode, path_mode  # noqa: E402, F401
+
+# history 模块使用独立 router（含 prefix），需要 include_router 注册
+from .history import router as history_router  # noqa: E402
+
+router.include_router(history_router)
+
+__all__ = ["router"]