precis-cli 0.1.3__py3-none-any.whl

app/api/routers/preview/path_mode.py

@@ -0,0 +1,440 @@
+# 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 文件路径预览路由模块（基于文件路径访问）
+
+功能概述:
+- 提供基于文件路径的数据预览接口（非上传模式）
+- 支持 Excel（.xlsx/.xls）、CSV 和 JSON 文件格式
+- JSON 文件支持 JSONPath 提取、多种格式解析和 record_path 规范化
+- 集成路径安全校验，限制只允许访问允许的目录范围
+- 支持工作表切换预览（Excel）
+
+架构设计:
+- 基于 FastAPI APIRouter 组织路由，挂载到 /preview 前缀下
+- 使用 pandas 读取 Excel/CSV，使用策略模式解析 JSON
+- 依赖 JSONPathExtractor 和 parser 策略实现灵活的 JSON 数据处理
+- 通过 validate_file_access 实现统一的路径安全控制
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import pandas as pd
+from fastapi import HTTPException
+
+from app.api.routers.preview.models import FilePathPreviewRequest, FilePreviewResponse, SheetSwitchRequest
+from app.shared.core.data_source.loaders.excel_loader import get_excel_sheet_names
+from app.shared.core.data_source.loaders.extractor import JSONPathExtractor
+from app.shared.core.data_source.loaders.strategies import get_parser
+from app.shared.services.preview.loader import load_preview_data
+from app.shared.services.preview.path_validation import validate_file_access
+
+from .router import router
+
+logger = logging.getLogger(__name__)
+
+
+def _infer_json_type(value: Any) -> str:
+    """推断 JSON 值的类型（用于前端类型标记展示）。"""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int) or isinstance(value, float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return "string"
+
+
+@router.post(
+    "/file/path",
+    response_model=FilePreviewResponse,
+    summary="基于文件路径预览文件内容",
+    responses={
+        400: {"description": "不支持的文件类型"},
+        404: {"description": "工作表不存在"},
+        500: {"description": "读取文件失败"},
+    },
+)
+def preview_file_by_path(request: FilePathPreviewRequest) -> FilePreviewResponse:
+    """
+    @methoddesc 基于文件路径预览文件内容
+
+    业务用途:
+    - 接收前端给定的绝对文件路径，校验访问权限后解析数据
+    - 支持 Excel 多 Sheet 切换（通过 sheet_name 字段）
+
+    参数:
+        request: 包含 file_path / max_rows / max_cols / sheet_name 的请求体
+
+    返回:
+        FilePreviewResponse: 包含解析数据、Sheet 列表、文件类型等的响应
+
+    异常:
+        HTTPException: 文件不可访问(403) / 工作表不存在(404) / 读取失败(500)
+    """
+    logger.info("=" * 50)
+    logger.info(f"[PREVIEW] 收到路径预览请求: {request.file_path}")
+    logger.info(f"[PREVIEW] max_rows: {request.max_rows}, max_cols: {request.max_cols}")
+    if request.sheet_name:
+        logger.info(f"[PREVIEW] 指定工作表: {request.sheet_name}")
+    logger.info("=" * 50)
+
+    try:
+        file_path = request.file_path
+        max_rows = request.max_rows
+        max_cols = request.max_cols
+        sheet_name = request.sheet_name
+
+        validate_file_access(file_path)
+
+        file_ext = os.path.splitext(file_path)[1].lower()
+        file_name = os.path.basename(file_path)
+
+        if file_ext in [".xlsx", ".xls"]:
+            file_type = "excel"
+        elif file_ext == ".csv":
+            file_type = "csv"
+        elif file_ext in [".json", ".jsonl", ".ndjson"]:
+            file_type = "json"
+        else:
+            raise HTTPException(status_code=400, detail=f"不支持的文件类型: {file_ext}")
+
+        if file_type == "excel":
+            try:
+                # 工作表列表读取：引擎按扩展名自适应（.xls→xlrd）、句柄确保关闭。
+                # 原实现硬编码 openpyxl 且从不 close——.xls 必然 500、Windows 下数据文件被锁。
+                sheet_names = get_excel_sheet_names(file_path)
+
+                if sheet_name:
+                    if sheet_name in sheet_names:
+                        current_sheet = sheet_name
+                    else:
+                        raise HTTPException(
+                            status_code=404,
+                            detail=f"工作表 '{sheet_name}' 不存在，可用工作表: {sheet_names}",
+                        )
+                else:
+                    current_sheet = sheet_names[0] if sheet_names else "Sheet1"
+
+                logger.info(f"[PREVIEW] 工作表列表: {sheet_names}, 当前工作表: {current_sheet}")
+
+                df, loaded_sheet_names = load_preview_data(
+                    file_path=file_path,
+                    file_type="excel",
+                    max_rows=max_rows,
+                    sheet_name=current_sheet,
+                )
+
+                data = []
+                for _, row in df.iterrows():
+                    row_data = [str(cell) for cell in row.tolist()[:max_cols]]
+                    data.append(row_data)
+
+                logger.info(
+                    f"[PREVIEW] Excel 文件读取成功: {file_name}, 行数: {len(df)}, 列数: {len(data[0]) if data else 0}"
+                )
+
+                return FilePreviewResponse(
+                    success=True,
+                    data=data,
+                    file_type=file_type,
+                    file_name=file_name,
+                    total_rows=len(df),
+                    total_cols=len(data[0]) if data else 0,
+                    sheets=loaded_sheet_names,
+                    current_sheet=current_sheet,
+                )
+
+            except Exception as e:
+                logger.info(f"[PREVIEW] 读取 Excel 文件失败: {e}")
+                import traceback
+
+                traceback.print_exc()
+                raise HTTPException(status_code=500, detail=f"读取Excel文件失败: {str(e)}") from e
+
+        if file_type == "csv":
+            try:
+                df, _ = load_preview_data(
+                    file_path=file_path,
+                    file_type="csv",
+                    max_rows=max_rows,
+                )
+
+                data = []
+                for _, row in df.iterrows():
+                    row_data = [str(cell) for cell in row.tolist()[:max_cols]]
+                    data.append(row_data)
+
+                logger.info(
+                    f"[PREVIEW] CSV 文件读取成功: {file_name}, 行数: {len(df)}, 列数: {len(data[0]) if data else 0}"
+                )
+
+                return FilePreviewResponse(
+                    success=True,
+                    data=data,
+                    file_type=file_type,
+                    file_name=file_name,
+                    total_rows=len(df),
+                    total_cols=len(data[0]) if data else 0,
+                    sheets=None,
+                    current_sheet=None,
+                )
+
+            except Exception as e:
+                logger.info(f"[PREVIEW] 读取 CSV 文件失败: {e}")
+                import traceback
+
+                traceback.print_exc()
+                raise HTTPException(status_code=500, detail=f"读取CSV文件失败: {str(e)}") from e
+
+        if file_type == "json":
+            try:
+                import json as json_module
+
+                with open(file_path, encoding="utf-8") as f:
+                    content = f.read()
+
+                # 1. 如果指定了 json_path，先使用 JSONPath 提取数据
+                if request.json_path:
+                    try:
+                        raw_data = json_module.loads(content)
+                        extractor = JSONPathExtractor()
+                        extracted = extractor.extract(raw_data, request.json_path)
+                        if not extracted:
+                            raise HTTPException(
+                                status_code=400, detail=f"JSONPath '{request.json_path}' 未匹配到任何数据"
+                            )
+                        # 提取后的数据作为 records 使用
+                        records = extracted if isinstance(extracted, list) else [extracted]
+                    except json_module.JSONDecodeError as e:
+                        raise HTTPException(status_code=400, detail=f"JSON 解析失败: {e.msg}") from e
+                else:
+                    # 2. 根据 json_format 选择合适的 parser（前端已统一为后端格式，直接透传）
+                    # D8: format 必填(auto 已废弃),默认 array(顶层数组)
+                    format_type = request.json_format or "array"
+
+                    try:
+                        parser = get_parser(format_type)
+                    except ValueError as e:
+                        raise HTTPException(status_code=400, detail=str(e)) from e
+
+                    records = parser.parse(content)
+
+                # 3. 应用 record_path 参数（如果指定）
+                if request.record_path and records:
+                    try:
+                        records = pd.json_normalize(records, record_path=request.record_path).to_dict("records")
+                    except (KeyError, TypeError) as e:
+                        raise HTTPException(
+                            status_code=400,
+                            detail=f"提取路径「{request.record_path}」在文件中不存在，请检查预览设置中的路径写法（{str(e)}）",
+                        ) from e
+
+                # 限制返回的记录数
+                limited_records = records[:max_rows] if records else []
+
+                # JSON 类型推断和结构统计
+                type_inference: dict[str, str] | None = None
+                field_count: int | None = None
+                nest_depth: int | None = None
+
+                if records and isinstance(records, list) and len(records) > 0:
+                    first_record = records[0]
+                    if isinstance(first_record, dict):
+                        # 推断每个字段的类型（遍历所有记录取最精确类型）
+                        type_inference = {}
+                        for key in first_record.keys():
+                            types_found: set[str] = set()
+                            for record in records:
+                                if isinstance(record, dict) and key in record:
+                                    val = record[key]
+                                    types_found.add(_infer_json_type(val))
+                            # 如果只有一种类型，直接使用；多种类型时优先 object > array > string
+                            if len(types_found) == 1:
+                                type_inference[key] = types_found.pop()
+                            elif "object" in types_found:
+                                type_inference[key] = "object"
+                            elif "array" in types_found:
+                                type_inference[key] = "array"
+                            else:
+                                type_inference[key] = "string"
+
+                        field_count = len(first_record)
+
+                        # 计算最大嵌套深度
+                        def _calc_depth(obj: Any, depth: int = 0) -> int:
+                            if not isinstance(obj, (dict, list)):
+                                return depth
+                            if isinstance(obj, list):
+                                if not obj:
+                                    return depth
+                                return max(_calc_depth(item, depth + 1) for item in obj)
+                            # dict
+                            values = list(obj.values())
+                            if not values:
+                                return depth
+                            return max(_calc_depth(v, depth + 1) for v in values)
+
+                        nest_depth = _calc_depth(first_record, 0)
+
+                logger.info(f"[PREVIEW] JSON 文件读取成功: {file_name}, 记录数: {len(limited_records)}")
+                if request.json_path:
+                    logger.info(f"[PREVIEW] 使用 JSONPath: {request.json_path}")
+                if request.json_format:
+                    logger.info(f"[PREVIEW] 使用格式: {request.json_format}")
+                if request.record_path:
+                    logger.info(f"[PREVIEW] 使用 record_path: {request.record_path}")
+
+                return FilePreviewResponse(
+                    success=True,
+                    data=None,  # JSON 不使用表格数据
+                    raw_data=limited_records,  # 返回原始 JSON 数据用于树状显示
+                    file_type=file_type,
+                    file_name=file_name,
+                    total_rows=len(records) if records else 0,
+                    total_cols=None,  # JSON 没有固定列数概念
+                    sheets=None,
+                    current_sheet=None,
+                    type_inference=type_inference,
+                    field_count=field_count,
+                    nest_depth=nest_depth,
+                )
+
+            except HTTPException:
+                raise
+            except Exception as e:
+                logger.info(f"[PREVIEW] 读取 JSON 文件失败: {e}")
+                import traceback
+
+                traceback.print_exc()
+                raise HTTPException(status_code=500, detail=f"读取JSON文件失败: {str(e)}") from e
+
+        raise HTTPException(status_code=400, detail=f"不支持的文件类型: {file_type}")
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.info(f"[PREVIEW] 未知错误: {str(e)}")
+        import traceback
+
+        traceback.print_exc()
+        return FilePreviewResponse(
+            success=False,
+            data=None,
+            file_type="unknown",
+            file_name="",
+            error=f"预览文件时发生错误: {str(e)}",
+        )
+
+
+@router.post(
+    "/switch-sheet/path",
+    response_model=FilePreviewResponse,
+    summary="基于文件路径切换 Excel 工作表",
+    responses={
+        400: {"description": "切换工作表只支持 Excel 文件"},
+        404: {"description": "工作表不存在"},
+        500: {"description": "读取文件失败"},
+    },
+)
+def switch_sheet_by_path(request: SheetSwitchRequest) -> FilePreviewResponse:
+    """
+    @methoddesc 基于文件路径切换 Excel 工作表预览
+
+    业务用途:
+    - 用户在预览界面点击其他 Sheet 时调用
+    - 仅支持 .xlsx / .xls；非 Excel 文件返回 400
+
+    参数:
+        request: 包含 file_path / sheet_name / max_rows / max_cols 的请求体
+
+    返回:
+        FilePreviewResponse: 新工作表的预览数据
+
+    异常:
+        HTTPException: 非 Excel 文件(400) / 工作表不存在(404) / 读取失败(500)
+    """
+    try:
+        file_path = request.file_path
+        sheet_name = request.sheet_name
+        max_rows = request.max_rows
+        max_cols = request.max_cols
+
+        validate_file_access(file_path)
+
+        file_name = os.path.basename(file_path)
+        file_ext = os.path.splitext(file_path)[1].lower()
+
+        if file_ext not in [".xlsx", ".xls"]:
+            raise HTTPException(status_code=400, detail="切换工作表只支持 Excel 文件")
+
+        try:
+            df, sheet_names = load_preview_data(
+                file_path=file_path,
+                file_type="excel",
+                max_rows=max_rows,
+                sheet_name=sheet_name,
+            )
+
+            data = []
+            for _, row in df.iterrows():
+                row_data = [str(cell) for cell in row.tolist()[:max_cols]]
+                data.append(row_data)
+
+            logger.info(f"[PREVIEW] 切换工作表成功: {file_name} -> {sheet_name}, 行数: {len(df)}")
+
+            return FilePreviewResponse(
+                success=True,
+                data=data,
+                file_type="excel",
+                file_name=file_name,
+                total_rows=len(df),
+                total_cols=len(data[0]) if data else 0,
+                sheets=sheet_names,
+                current_sheet=sheet_name,
+            )
+
+        except ValueError as e:
+            if "Worksheet" in str(e):
+                raise HTTPException(status_code=404, detail=f"工作表 '{sheet_name}' 不存在") from e
+            raise HTTPException(status_code=500, detail=f"读取工作表失败: {str(e)}") from e
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"读取Excel文件失败: {str(e)}") from e
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.info(f"[PREVIEW] 切换工作表错误: {str(e)}")
+        import traceback
+
+        traceback.print_exc()
+        return FilePreviewResponse(
+            success=False,
+            data=None,
+            file_type="excel",
+            file_name="",
+            error=f"切换工作表时发生错误: {str(e)}",
+        )

app/api/routers/preview/router.py

@@ -0,0 +1,30 @@
+# 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 实例
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/api/latest/preview", tags=["File Preview"])
+
+
+__all__ = ["router"]

app/api/routers/project/__init__.py

@@ -0,0 +1,61 @@
+# 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 Project API Router 聚合模块
+
+功能概述:
+- 聚合 project 子模块的所有 FastAPI router
+- 统一设置 prefix="/project" 和 tags=["Project"]
+
+架构设计:
+- 各子模块 router 通过 include_router 合并到主 router
+- 子模块本身使用空 prefix，由主 router 统一添加前缀
+"""
+
+from fastapi import APIRouter
+
+from . import (
+    constraint,
+    full_config,
+    inspection_fix,
+    manifest,
+    pattern,
+    regex,
+    schema,
+    settings,
+    template,
+    validation,
+    view,
+    workspaces,
+)
+
+router = APIRouter(
+    prefix="/api/latest/project",
+    tags=["Project"],
+)
+
+router.include_router(view.router)
+router.include_router(workspaces.router)
+router.include_router(manifest.router)
+router.include_router(schema.router)
+router.include_router(constraint.router)
+router.include_router(regex.router)
+router.include_router(pattern.router)
+router.include_router(template.router)
+router.include_router(full_config.router)
+router.include_router(settings.router)
+router.include_router(validation.router)
+router.include_router(inspection_fix.router)

app/api/routers/project/base.py

@@ -0,0 +1,111 @@
+# 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 Project API 基础模块
+
+功能概述:
+- 作为 project API 子模块的公共基础设施，集中管理共享导入
+- 提供跨文件共享的辅助函数（如 YAML 加载、文件扫描）
+- 暴露公共 Pydantic 模型定义与 V2 项目相关常量
+
+架构设计:
+- 将共享内容集中到 base.py 以避免循环导入和重复定义
+- 辅助函数使用纯 Python 实现，不依赖 FastAPI 框架，便于单元测试
+- 通过 __all__ 显式控制对外暴露的符号
+
+输入示例:
+    from app.api.routers.project.base import ProjectManifestV2, _load_yaml_file
+
+输出示例:
+    可直接使用导入的类型、函数与常量构建 project 相关 API
+"""
+
+from app.api.models.project import StandardResponse
+from app.api.routers.project.helpers import (
+    V2_MANIFEST_FILENAME,
+    V2_VIEW_FILENAME,
+    V2_WORKSPACES_FILENAME,
+    _load_yaml_file,
+    _v2_manifest_path,
+    _v2_view_path,
+    _v2_workspaces_path,
+)
+from app.api.routers.project.models import (
+    DisplayNameUpdateRequest,
+    FullConfigV2Request,
+    ProjectViewV2Model,
+    WorkspacesV2Model,
+    WorkspaceV2Item,
+)
+from app.api.routers.project.scanner import (
+    _scan_constraint_file,
+    _scan_regex_node_file,
+    _scan_schema_file,
+)
+from app.shared.core.project.constraint.types import ConstraintFileV2
+
+# 从 shared 模块导入项目相关类型
+from app.shared.core.project.manifest.types import (
+    ConstraintRefV2,
+    FileProcessingSettingsV2,
+    ProjectManifestV2,
+    ProjectSettingsV2,
+    RegexNodeRefV2,
+    SchemaRefV2,
+    ScriptSecuritySettingsV2,
+    TransformRefV2,
+    ValidationSettingsV2,
+)
+from app.shared.core.project.regex.types import RegexNodeFileV2
+from app.shared.core.project.schema.types import TableSchemaFileV2
+from app.shared.core.project.transform.types import TransformFileV2
+
+__all__ = [
+    # helpers
+    "V2_MANIFEST_FILENAME",
+    "V2_VIEW_FILENAME",
+    "V2_WORKSPACES_FILENAME",
+    "_load_yaml_file",
+    "_v2_manifest_path",
+    "_v2_view_path",
+    "_v2_workspaces_path",
+    # scanner
+    "_scan_constraint_file",
+    "_scan_schema_file",
+    "_scan_regex_node_file",
+    # models
+    "ProjectViewV2Model",
+    "FullConfigV2Request",
+    "DisplayNameUpdateRequest",
+    "StandardResponse",
+    "WorkspaceV2Item",
+    "WorkspacesV2Model",
+    # manifest types
+    "ProjectManifestV2",
+    "SchemaRefV2",
+    "ConstraintRefV2",
+    "RegexNodeRefV2",
+    "TransformRefV2",
+    "ProjectSettingsV2",
+    "ValidationSettingsV2",
+    "FileProcessingSettingsV2",
+    "ScriptSecuritySettingsV2",
+    # schema/constraint/regex types
+    "TableSchemaFileV2",
+    "ConstraintFileV2",
+    "RegexNodeFileV2",
+    "TransformFileV2",
+]