precis-cli 0.1.3__py3-none-any.whl

app/api/routers/validation/content_mode.py

@@ -0,0 +1,401 @@
+# 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 前缀下
+- 使用 UploadFile/Form 接收前端上传的文件和表单参数
+- 统一返回 ValidationResponse / RegexValidationResponse 标准化响应结构
+- 调用 UnifiedValidationService 和 load_file_data 完成数据加载与校验
+
+输入示例:
+    POST /validate/content
+    FormData:
+      - file: users.xlsx (上传文件)
+      - validation_type: Unique
+      - target_column_name: email
+      - sheet_name: Sheet1
+      - header_row: 0
+      - validation_config: {"case_sensitive": true}
+      - allow_unsafe_eval: false
+
+输出示例:
+    {
+      "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 asyncio
+import logging
+import os
+import tempfile
+from typing import Any
+
+from fastapi import File, Form, HTTPException, UploadFile
+
+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",
+    response_model=ValidationResponse,
+    summary="基于 JSON 请求体的单条数据校验",
+    # 行为约定：本端点永远返回 200，业务失败以 success=false + error 字段表达，不产生 500
+    responses={
+        200: {
+            "description": "校验已执行；业务失败（文件未找到、路径非法、校验异常等）同样返回 200，以 success=false + error 字段表达",
+        },
+    },
+)
+def validate_data(request: ValidationRequest) -> ValidationResponse:
+    """
+    基于 JSON 请求体的单条数据校验接口。
+
+    参数:
+        request (ValidationRequest): 校验请求体，包含文件路径、校验类型、目标列、配置等
+
+    返回值:
+        ValidationResponse: 标准化校验响应，包含校验结果、错误信息、统计数据等
+
+    业务逻辑:
+        1. 确定表头行号（默认第 0 行）
+        2. 调用 load_file_data 加载数据文件为 DataFrame
+        3. 检查目标列是否存在于 DataFrame 中
+        4. 调用 UnifiedValidationService.validate 执行具体校验逻辑
+        5. 将错误行数据转换为 ValidationErrorRow 列表
+        6. 组装 ValidationResult 并包装为 ValidationResponse 返回
+        7. 捕获文件未找到和通用异常，返回友好的错误响应
+
+    错误语义:
+        所有业务失败与意外异常（文件未找到、路径非法、校验出错等）均在本端点内
+        捕获并转为 success=false + error 字段随 HTTP 200 返回，不抛出 500。
+    """
+    try:
+        # 校验文件路径格式合法性（防止路径遍历攻击）
+        if request.source_file_path:
+            validate_file_access(request.source_file_path)
+
+        return execute_standard_validation(
+            source_file_path=request.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,
+            allow_unsafe_eval=request.allow_unsafe_eval,
+            column_data_type=request.column_data_type,
+            source_config=request.to_source_config(),
+        )
+
+    except FileNotFoundError as e:
+        # 文件未找到时返回明确的错误提示
+        return ValidationResponse(success=False, validation_type=request.validation_type, data=None, error=str(e))
+    except Exception as e:
+        # 捕获所有未预期异常，防止服务端崩溃，返回通用错误信息
+        return ValidationResponse(
+            success=False,
+            validation_type=request.validation_type,
+            data=None,
+            error=f"校验过程中发生错误: {str(e)}",
+        )
+
+
+@router.post(
+    "/validate/content",
+    response_model=ValidationResponse,
+    summary="基于文件上传的单条数据校验（Content 模式）",
+    # 行为约定：仅"文件内容为空"返回 400（HTTPException 显式抛出并透传），
+    # 其余业务失败一律被捕获并以 success=false + error 字段随 200 返回
+    responses={
+        200: {
+            "description": "校验已执行；除文件内容为空（400）外的业务失败同样返回 200，以 success=false + error 字段表达",
+        },
+        400: {"description": "文件内容为空"},
+    },
+)
+async def validate_data_with_file(
+    file: UploadFile = File(...),
+    validation_type: str = Form(...),
+    target_column_name: str = Form(...),
+    sheet_name: str = Form(None),
+    header_row: int = Form(0),
+    validation_config: str = Form(None),
+    allow_unsafe_eval: bool = Form(False),
+) -> ValidationResponse:
+    """
+    基于文件上传的单条数据校验接口（Content 模式）。
+
+    参数:
+        file (UploadFile): 上传的数据文件（Excel/CSV 等），必填
+        validation_type (str): 校验类型，如 Unique、NotNull、Regex 等，必填
+        target_column_name (str): 需要校验的目标列名，必填
+        sheet_name (str): Excel 工作表名称，可选，默认为 None
+        header_row (int): 表头所在行号，可选，默认为 0
+        validation_config (str): JSON 格式的校验配置字符串，可选
+        allow_unsafe_eval (bool): 是否允许不安全的表达式求值，可选，默认为 False
+
+    返回值:
+        ValidationResponse: 标准化校验响应
+
+    业务逻辑:
+        1. 接收上传的文件和表单参数
+        2. 读取文件内容并写入系统临时文件（带原文件扩展名）
+        3. 调用 load_file_data 从临时文件加载数据
+        4. 检查目标列是否存在
+        5. 解析 validation_config JSON 字符串为字典
+        6. 调用 UnifiedValidationService.validate 执行校验
+        7. 转换错误行数据并组装响应
+        8. 在 finally 块中清理临时文件，避免磁盘泄漏
+        9. 记录校验完成日志，捕获并处理所有异常
+
+    错误语义:
+        上传文件内容为空时抛出 HTTP 400（由框架直接处理）；
+        其余业务失败与意外异常均被捕获并转为 success=false + error 字段随 HTTP 200 返回。
+    """
+    tmp_path = None
+    try:
+        # 记录收到的校验请求基本信息，便于后续排查问题
+        logger.info(f"[VALIDATION] 收到FormData校验请求: {file.filename}")
+        logger.info(f"[VALIDATION] 校验类型: {validation_type}, 目标列: {target_column_name}")
+
+        # 获取上传文件的原始名称和扩展名，用于创建临时文件时保留格式
+        file_name = file.filename or "unknown"
+        file_ext = os.path.splitext(file_name)[1].lower()
+        # 异步读取上传文件的二进制内容
+        content = await file.read()
+
+        # 如果文件内容为空，直接返回 400 错误
+        if len(content) == 0:
+            raise HTTPException(status_code=400, detail="文件内容为空")
+
+        # 创建带原扩展名的临时文件，delete=False 确保我们可以手动控制删除时机
+        with tempfile.NamedTemporaryFile(suffix=file_ext, delete=False) as tmp:
+            tmp.write(content)
+            tmp_path = tmp.name
+
+        try:
+            # 解析前端传来的 JSON 配置字符串，解析失败则使用空配置并记录错误日志
+            config = {}
+            if validation_config:
+                import json
+
+                try:
+                    config = json.loads(validation_config)
+                except json.JSONDecodeError:
+                    logger.error("[VALIDATION] validation_config 解析失败，使用空配置")
+
+            # B-async: 将阻塞的 pandas I/O 与校验逻辑 offload 到线程池，避免阻塞事件循环。
+            # execute_standard_validation 内部调用 pd.read_csv/read_excel + 全量校验，是纯同步阻塞操作。
+            # agent 工具（apply_actions.py）已采用同样的 asyncio.to_thread 模式。
+            response = await asyncio.to_thread(
+                execute_standard_validation,
+                source_file_path=tmp_path,
+                sheet_name=sheet_name,
+                header_row=header_row,
+                validation_type=validation_type,
+                target_column_name=target_column_name,
+                validation_config=config,
+                allow_unsafe_eval=allow_unsafe_eval,
+            )
+
+            if response.success and response.data:
+                logger.info(f"[VALIDATION] 校验完成: 成功={response.data.is_valid}, 错误数={response.data.error_count}")
+
+            return response
+
+        finally:
+            # 无论校验成功与否，都尝试删除临时文件，防止磁盘空间泄漏
+            if tmp_path and os.path.exists(tmp_path):
+                try:
+                    os.unlink(tmp_path)
+                except Exception as e:
+                    logger.error(f"[VALIDATION] 删除临时文件失败: {e}")
+
+    except HTTPException:
+        # FastAPI 的 HTTPException 直接抛出，由框架处理响应
+        raise
+    except Exception as e:
+        # 捕获所有未预期异常，记录详细错误堆栈并返回友好错误信息
+        logger.error(f"[VALIDATION] 校验异常: {str(e)}")
+        import traceback
+
+        traceback.print_exc()
+        return ValidationResponse(
+            success=False,
+            validation_type=validation_type,
+            data=None,
+            error=f"校验过程中发生错误: {str(e)}",
+        )
+
+
+@router.post(
+    "/regex",
+    response_model=RegexValidationResponse,
+    summary="基于 JSON 请求体的正则表达式校验",
+    # 行为约定：本端点永远返回 200，业务失败以 success=false + error 字段表达，不产生 500
+    responses={
+        200: {
+            "description": "校验已执行；业务失败（文件未找到、路径非法、校验异常等）同样返回 200，以 success=false + error 字段表达",
+        },
+    },
+)
+def validate_regex(request: RegexValidationRequest) -> RegexValidationResponse:
+    """
+    基于 JSON 请求体的正则表达式校验接口。
+
+    参数:
+        request (RegexValidationRequest): 正则校验请求体，包含文件路径、正则模式、
+                                         匹配模式、大小写敏感设置、目标列等
+
+    返回值:
+        RegexValidationResponse: 正则校验专用响应模型，包含匹配统计和错误行信息
+
+    业务逻辑:
+        1. 调用 load_file_data 加载数据文件，支持自定义表头
+        2. 检查目标列是否存在
+        3. 调用 UnifiedValidationService.validate 执行 REGEX 类型校验
+        4. 使用 convert_validation_result_to_regex 转换结果为正则响应模型
+        5. 返回标准化响应，捕获文件未找到和通用异常
+
+    错误语义:
+        所有业务失败与意外异常（文件未找到、路径非法、校验出错等）均在本端点内
+        捕获并转为 success=false + error 字段随 HTTP 200 返回，不抛出 500。
+    """
+    try:
+        # 校验文件路径格式合法性（防止路径遍历攻击）
+        if request.source_file_path:
+            validate_file_access(request.source_file_path)
+
+        # 加载数据文件，支持自定义表头配置
+        df = load_file_data(
+            source_file_path=request.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)
+
+        return RegexValidationResponse(success=True, data=regex_result, error=None)
+
+    except FileNotFoundError as e:
+        # 文件未找到时返回错误响应
+        return RegexValidationResponse(success=False, data=None, error=str(e))
+    except Exception as e:
+        # 通用异常处理，防止服务端崩溃
+        return RegexValidationResponse(success=False, data=None, error=f"校验过程中发生错误: {str(e)}")
+
+
+@router.post(
+    "/validate/batch",
+    response_model=dict,
+    summary="批量数据校验",
+    # 行为约定：单条校验的失败已被 validate_data 逐条捕获，整体仍返回 200
+    responses={
+        200: {
+            "description": "批量校验已执行；单条失败不改变整体状态码，失败体现在该条目的 success=false 与 error 字段",
+        },
+    },
+)
+def validate_batch(requests: list[ValidationRequest]) -> dict[str, Any]:
+    """
+    批量数据校验接口（基于 JSON 请求体列表）。
+
+    参数:
+        requests (list[ValidationRequest]): 校验请求对象列表，每个元素为独立的校验请求
+
+    返回值:
+        dict: 包含 results 键的字典，值为所有单条校验结果的列表
+
+    业务逻辑:
+        1. 遍历传入的请求列表
+        2. 对每个请求调用 validate_data 执行单条校验
+        3. 收集每条请求的校验类型、目标列、成功状态、结果数据和错误信息
+        4. 将所有结果组装为统一字典返回
+
+    错误语义:
+        单条请求的失败由 validate_data 捕获并写入对应条目的
+        success=false 与 error 字段，批量接口本身始终返回 200。
+    """
+    # 存储所有批量校验结果的列表
+    results = []
+    # 逐条处理每个校验请求
+    for request in requests:
+        # 复用单条校验接口的逻辑
+        response = validate_data(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/history.py

@@ -0,0 +1,235 @@
+# 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 校验历史 API 端点
+
+提供校验结果的持久化存储和查询接口。
+
+安全约定:
+- 项目路径统一从 `X-Project-Config-Path` Header 获取（经 get_project_config_path 校验），
+  不再从请求体/Query 接受 project_path，避免任意目录读写。
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel, Field
+
+from app.api.dependencies import get_project_config_path
+from app.shared.services.validation.history import (
+    ValidationHistoryStore,
+    ValidationRunRecord,
+    generate_run_id,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/validation/history", tags=["validation-history"])
+
+
+def _get_store(project_path: str) -> ValidationHistoryStore:
+    """
+    @methoddesc 获取项目对应的校验历史存储实例
+
+    每次请求重新创建实例，确保数据最新（本地文件读取开销极小）
+
+    参数:
+        project_path: 项目配置根目录（已由 get_project_config_path 校验为存在的绝对路径）
+
+    返回:
+        ValidationHistoryStore 实例
+    """
+    return ValidationHistoryStore(project_path)
+
+
+class SaveRunRequest(BaseModel):
+    """保存校验运行记录请求（项目路径从 Header 注入，不在 body 中）"""
+
+    duration_ms: int = Field(..., description="校验耗时（毫秒）")
+    scope: str = Field(default="full", description="校验范围（full/incremental）")
+    summary: dict[str, Any] = Field(..., description="汇总统计")
+    by_type: dict[str, dict[str, int]] = Field(default_factory=dict, description="按校验类型统计")
+    by_table: dict[str, dict[str, int]] = Field(default_factory=dict, description="按表统计")
+    errors: list[dict[str, Any]] = Field(default_factory=list, description="错误列表")
+    warnings: list[str] = Field(default_factory=list, description="警告信息")
+
+
+@router.post(
+    "",
+    summary="保存校验运行记录",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def save_run(req: SaveRunRequest, project_path: str = Depends(get_project_config_path)) -> dict[str, Any]:
+    """
+    @methoddesc 保存一次校验运行的完整记录
+
+    业务用途:
+    - 由前端在执行全量/单条校验后调用，将结果落地到项目本地
+    - 自动生成 run_id 与时间戳，供后续查询/统计/历史面板展示
+
+    参数:
+        req: 包含运行汇总、按类型/表分组统计、错误列表等的请求
+        project_path: 项目配置根目录（Header 注入）
+
+    返回:
+        {"success": True, "run_id": str} 字典
+    """
+    store = _get_store(project_path)
+    record = ValidationRunRecord(
+        id=generate_run_id(),
+        timestamp=datetime.datetime.now().isoformat(),
+        duration_ms=req.duration_ms,
+        scope=req.scope,
+        summary=req.summary,
+        by_type=req.by_type,
+        by_table=req.by_table,
+        errors=req.errors,
+        warnings=req.warnings,
+    )
+    run_id = store.add_run(record)
+    return {"success": True, "run_id": run_id}
+
+
+@router.get(
+    "",
+    summary="获取校验运行记录列表",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def list_runs(
+    project_path: str = Depends(get_project_config_path),
+    limit: int = Query(20, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+) -> dict[str, Any]:
+    """
+    @methoddesc 分页获取校验运行记录列表
+
+    业务用途:
+    - 为前端历史记录面板提供数据
+    - 按时间倒序返回，limit 限制最大 100，offset 用于分页
+
+    参数:
+        project_path: 项目路径（Header 注入）
+        limit: 每页大小，1-100
+        offset: 偏移量
+
+    返回:
+        包含 runs/items/total 字段的字典
+    """
+    store = _get_store(project_path)
+    return store.get_runs(limit=limit, offset=offset)
+
+
+@router.get(
+    "/stats",
+    summary="获取校验运行统计信息",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def get_stats(
+    project_path: str = Depends(get_project_config_path),
+    last_n: int = Query(10, ge=1, le=50),
+) -> dict[str, Any]:
+    """
+    @methoddesc 获取最近 N 次校验运行的统计信息
+
+    业务用途:
+    - 用于前端仪表盘展示趋势、平均耗时、通过率等指标
+
+    参数:
+        project_path: 项目路径（Header 注入）
+        last_n: 统计最近 N 条记录，1-50
+
+    返回:
+        统计信息字典
+    """
+    store = _get_store(project_path)
+    return store.get_stats(last_n=last_n)
+
+
+@router.get(
+    "/{run_id}",
+    summary="获取单条校验运行记录",
+    responses={
+        404: {"description": "记录不存在"},
+    },
+)
+def get_run(
+    run_id: str,
+    project_path: str = Depends(get_project_config_path),
+) -> dict[str, Any]:
+    """
+    @methoddesc 获取指定 run_id 的完整校验运行记录
+
+    业务用途:
+    - 用户在历史面板点击某条记录时展示完整错误详情
+
+    参数:
+        run_id: 运行记录唯一标识
+        project_path: 项目路径（Header 注入）
+
+    返回:
+        完整运行记录字典
+
+    异常:
+        HTTPException: 记录不存在(404)
+    """
+    store = _get_store(project_path)
+    run = store.get_run(run_id)
+    if not run:
+        raise HTTPException(status_code=404, detail=f"记录不存在: {run_id}")
+    return run
+
+
+@router.delete(
+    "/{run_id}",
+    summary="删除校验运行记录",
+    responses={
+        404: {"description": "记录不存在"},
+    },
+)
+def delete_run(
+    run_id: str,
+    project_path: str = Depends(get_project_config_path),
+) -> dict[str, Any]:
+    """
+    @methoddesc 删除指定 run_id 的校验运行记录
+
+    业务用途:
+    - 用户在历史面板点击"删除"按钮时调用
+
+    参数:
+        run_id: 运行记录唯一标识
+        project_path: 项目路径（Header 注入）
+
+    返回:
+        {"success": True} 字典
+
+    异常:
+        HTTPException: 记录不存在(404)
+    """
+    store = _get_store(project_path)
+    deleted = store.delete_run(run_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"记录不存在: {run_id}")
+    return {"success": True}