precis-cli 0.1.3__py3-none-any.whl

app/api/routers/preview/content_mode.py

@@ -0,0 +1,264 @@
+# 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 文件的内容解析与预览
+- 支持工作表切换预览
+- 使用临时文件存储上传内容，处理完成后自动清理
+- 限制返回的最大行数和列数，防止内存溢出
+
+架构设计:
+- 基于 FastAPI APIRouter 组织路由
+- 具体预览逻辑委托给 preview_service.py
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from fastapi import File, Form, HTTPException, UploadFile
+
+from app.api.routers.preview.models import FilePreviewRequest, FilePreviewResponse, SheetSwitchRequest
+from app.api.services.preview_service import (
+    preview_from_content,
+    preview_from_path,
+)
+from app.shared.services.preview.path_validation import validate_file_access
+
+from .router import router
+
+logger = logging.getLogger(__name__)
+
+
+@router.post(
+    "/file",
+    response_model=FilePreviewResponse,
+    summary="基于文件路径预览文件内容",
+    responses={
+        500: {"description": "预览文件时发生错误"},
+    },
+)
+def preview_file(request: FilePreviewRequest) -> FilePreviewResponse:
+    """基于文件路径预览文件内容
+
+    根据请求中的文件路径读取 Excel 或 CSV 文件，
+    返回指定行数和列数的预览数据。
+    """
+    logger.info("=" * 50)
+    logger.info(f"[PREVIEW] 收到文件预览请求: {request.file_path}")
+    logger.info(f"[PREVIEW] max_rows: {request.max_rows}, max_cols: {request.max_cols}")
+    logger.info("=" * 50)
+
+    # B-sec: 路径校验(与姊妹端点 /file/path、/switch-sheet 对齐)。
+    # 此前该端点连 `..`/相对路径都不拦截,是约束最弱的文件读取口。
+    request.file_path = validate_file_access(request.file_path)
+
+    try:
+        data, file_type, total_rows, sheets, current_sheet = preview_from_path(
+            request.file_path,
+            request.max_rows,
+            request.max_cols,
+        )
+        return FilePreviewResponse(
+            success=True,
+            data=data,
+            file_type=file_type,
+            file_name=os.path.basename(request.file_path),
+            total_rows=total_rows,
+            total_cols=len(data[0]) if data else 0,
+            sheets=sheets,
+            current_sheet=current_sheet,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"[PREVIEW] 未知错误: {e}")
+        return FilePreviewResponse(
+            success=False,
+            data=None,
+            file_type="unknown",
+            file_name="",
+            error=f"预览文件时发生错误: {e}",
+        )
+
+
+@router.post(
+    "/file/content",
+    response_model=FilePreviewResponse,
+    summary="基于文件上传预览文件内容",
+    responses={
+        500: {"description": "预览文件时发生错误"},
+    },
+)
+async def preview_file_content(
+    file: UploadFile = File(...),
+    max_rows: int = Form(65535),
+    max_cols: int = Form(65535),
+) -> FilePreviewResponse:
+    """
+    @methoddesc 基于文件上传预览文件内容
+
+    业务用途:
+    - 接收前端通过 multipart 上传的文件流
+    - 内部读取字节流并复用 preview_from_content 服务进行解析
+
+    参数:
+        file: 上传的文件对象
+        max_rows: 最大返回行数，默认 65535
+        max_cols: 最大返回列数，默认 65535
+
+    返回:
+        FilePreviewResponse: 包含解析数据、文件类型、Sheet 列表的响应
+    """
+    logger.info("=" * 50)
+    logger.info(f"[PREVIEW] 收到文件内容预览请求: {file.filename}")
+    logger.info(f"[PREVIEW] max_rows: {max_rows}, max_cols: {max_cols}")
+    logger.info("=" * 50)
+
+    try:
+        file_name = file.filename or "unknown"
+        file_ext = os.path.splitext(file_name)[1].lower()
+        content = await file.read()
+
+        data, file_type, total_rows, sheets, current_sheet = preview_from_content(content, file_ext, max_rows, max_cols)
+        return FilePreviewResponse(
+            success=True,
+            data=data,
+            file_type=file_type,
+            file_name=file_name,
+            total_rows=total_rows,
+            total_cols=len(data[0]) if data else 0,
+            sheets=sheets,
+            current_sheet=current_sheet,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"[PREVIEW] 未知错误: {e}")
+        return FilePreviewResponse(
+            success=False,
+            data=None,
+            file_type="unknown",
+            file_name=file.filename or "",
+            error=f"预览文件时发生错误: {e}",
+        )
+
+
+@router.post(
+    "/switch-sheet",
+    response_model=FilePreviewResponse,
+    summary="切换 Excel 工作表预览",
+    responses={
+        500: {"description": "切换工作表时发生错误"},
+    },
+)
+def switch_sheet(request: SheetSwitchRequest) -> FilePreviewResponse:
+    """切换 Excel 工作表预览"""
+    file_path = request.file_path
+
+    validate_file_access(file_path)
+
+    try:
+        data, file_type, total_rows, sheets, current_sheet = preview_from_path(
+            file_path,
+            request.max_rows,
+            request.max_cols,
+            sheet_name=request.sheet_name,
+        )
+        return FilePreviewResponse(
+            success=True,
+            data=data,
+            file_type=file_type,
+            file_name=os.path.basename(request.file_path),
+            total_rows=total_rows,
+            total_cols=len(data[0]) if data else 0,
+            sheets=sheets,
+            current_sheet=current_sheet,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        return FilePreviewResponse(
+            success=False,
+            data=None,
+            file_type="excel",
+            file_name="",
+            error=f"切换工作表时发生错误: {e}",
+        )
+
+
+@router.post(
+    "/switch-sheet/content",
+    response_model=FilePreviewResponse,
+    summary="基于文件上传切换 Excel 工作表预览",
+    responses={
+        500: {"description": "切换工作表时发生错误"},
+    },
+)
+async def switch_sheet_content(
+    file: UploadFile = File(...),
+    sheet_name: str = Form(...),
+    max_rows: int = Form(65535),
+    max_cols: int = Form(65535),
+) -> FilePreviewResponse:
+    """
+    @methoddesc 基于文件上传切换 Excel 工作表预览
+
+    业务用途:
+    - 接收前端上传的多 Sheet Excel 文件，并切换到指定 sheet 进行预览
+    - 与 switch_sheet_by_path 互补：本接口处理"用户拖入即上传"的场景
+
+    参数:
+        file: 上传的文件对象（multipart/form-data）
+        sheet_name: 目标工作表名
+        max_rows: 最大返回行数，默认 65535
+        max_cols: 最大返回列数，默认 65535
+
+    返回:
+        FilePreviewResponse: 包含新工作表预览数据的响应
+    """
+    try:
+        file_name = file.filename or "unknown"
+        file_ext = os.path.splitext(file_name)[1].lower()
+        content = await file.read()
+
+        data, file_type, total_rows, sheets, current_sheet = preview_from_content(
+            content, file_ext, max_rows, max_cols, sheet_name=sheet_name
+        )
+        return FilePreviewResponse(
+            success=True,
+            data=data,
+            file_type=file_type,
+            file_name=file_name,
+            total_rows=total_rows,
+            total_cols=len(data[0]) if data else 0,
+            sheets=sheets,
+            current_sheet=current_sheet,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        return FilePreviewResponse(
+            success=False,
+            data=None,
+            file_type="excel",
+            file_name=file.filename or "",
+            error=f"切换工作表时发生错误: {e}",
+        )

app/api/routers/preview/header_row.py

@@ -0,0 +1,154 @@
+# 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 表头行变更处理路由模块
+
+功能概述:
+- 接收并处理表头行变更事件
+- 将新的表头行信息持久化到对应的 Schema YAML 文件
+- 记录变更时间戳和节点关联信息
+
+架构设计:
+- 基于 FastAPI APIRouter 组织路由
+- 直接操作本地 YAML Schema 配置文件
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime
+from pathlib import Path
+
+import yaml
+from fastapi import Depends
+
+from app.api.dependencies import get_project_config_path
+from app.api.models import HeaderRowChangedRequest, HeaderRowChangedResponse
+from app.shared.core.io.yaml import write_yaml_atomic
+
+from .router import router
+
+logger = logging.getLogger(__name__)
+
+_SAFE_SCHEMA_NAME_CHARS = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.")
+
+
+def _sanitize_schema_name(name: str) -> str:
+    cleaned = "".join(c for c in name if c in _SAFE_SCHEMA_NAME_CHARS)
+    if not cleaned or cleaned != name:
+        raise ValueError(f"非法的 schema_name: {name!r}")
+    return cleaned
+
+
+@router.post(
+    "/header-row-changed",
+    response_model=HeaderRowChangedResponse,
+    summary="处理表头行变更请求",
+    responses={
+        500: {"description": "处理表头行变更时发生错误"},
+    },
+)
+def handle_header_row_changed(
+    request: HeaderRowChangedRequest,
+    config_path: str = Depends(get_project_config_path),
+) -> HeaderRowChangedResponse:
+    """
+    处理表头行变更请求。
+
+    接收前端传来的表头行变更事件，将新的表头行索引和关联信息
+    持久化到对应的 Schema YAML 文件中。
+
+    参数:
+        request: 表头行变更请求，包含 node_id、header_row、schema_name 等信息
+
+    返回:
+        HeaderRowChangedResponse: 变更处理结果，包含成功状态和消息
+
+    业务逻辑:
+        1. 提取请求中的 node_id、header_row、schema_name 等字段
+        2. 如果指定了 schema_name，尝试更新对应的 Schema YAML 文件
+        3. 在 Schema 文件中记录 header_row.index、node_id 和 updated_at
+        4. 如果提供了 row_data，一并保存
+        5. 返回操作结果
+    """
+    try:
+        node_id = request.node_id
+        header_row = request.header_row
+        _old_header_row = request.old_header_row
+        row_data = request.row_data
+        schema_name = request.schema_name
+
+        if schema_name:
+            try:
+                safe_name = _sanitize_schema_name(schema_name)
+            except ValueError:
+                return HeaderRowChangedResponse(
+                    success=False,
+                    message="非法的 schema_name",
+                    schema_name=schema_name,
+                    updated_at=datetime.now().isoformat(),
+                )
+            schema_path = Path(config_path) / "schemas" / f"{safe_name}.yaml"
+
+            if os.path.exists(schema_path):
+                try:
+                    with open(schema_path, encoding="utf-8") as f:
+                        schema_content = yaml.safe_load(f)
+
+                    if "header_row" not in schema_content:
+                        schema_content["header_row"] = {}
+
+                    schema_content["header_row"]["index"] = header_row
+                    schema_content["header_row"]["node_id"] = node_id
+                    schema_content["header_row"]["updated_at"] = datetime.now().isoformat()
+
+                    if row_data:
+                        schema_content["header_row"]["data"] = row_data
+
+                    write_yaml_atomic(schema_path, schema_content)
+
+                    return HeaderRowChangedResponse(
+                        success=True,
+                        message=f"表头行已更新到第{header_row}行",
+                        schema_name=schema_name,
+                        updated_at=datetime.now().isoformat(),
+                    )
+
+                except Exception as e:
+                    logger.warning("更新Schema文件失败: %s", e)
+                    return HeaderRowChangedResponse(
+                        success=False,
+                        message="更新Schema文件失败",
+                        schema_name=schema_name,
+                        updated_at=datetime.now().isoformat(),
+                    )
+
+        return HeaderRowChangedResponse(
+            success=True,
+            message=f"表头行变更事件已接收，node_id: {node_id}, header_row: {header_row}",
+            schema_name=schema_name or "",
+            updated_at=datetime.now().isoformat(),
+        )
+
+    except Exception as e:
+        logger.warning("处理表头行变更时发生错误: %s", e)
+        return HeaderRowChangedResponse(
+            success=False,
+            message="处理表头行变更时发生错误",
+            schema_name=request.schema_name or "",
+            updated_at=datetime.now().isoformat(),
+        )

app/api/routers/preview/models.py

@@ -0,0 +1,81 @@
+# 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 文件预览请求/响应模型定义
+
+功能概述:
+- 定义文件预览相关的 Pydantic 数据模型
+- 包括路径预览、内容预览、工作表切换等请求和响应结构
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FilePreviewRequest(BaseModel):
+    """文件预览请求（基于上传内容模式）"""
+
+    file_path: str = Field(..., description="文件路径（经 validate_file_access 校验后由后端读取，参与文件 IO）")
+    max_rows: int = Field(default=65535, description="最大返回行数")
+    max_cols: int = Field(default=65535, description="最大返回列数")
+
+
+class FilePreviewResponse(BaseModel):
+    """文件预览响应"""
+
+    success: bool = Field(..., description="是否成功解析")
+    data: list[list[str]] | None = Field(default=None, description="表格化预览数据")
+    file_type: str = Field(..., description="文件类型标识，如 xlsx/csv/json")
+    file_name: str = Field(..., description="原始文件名")
+    total_rows: int | None = Field(default=None, description="文件总行数")
+    total_cols: int | None = Field(default=None, description="文件总列数")
+    sheets: list[str] | None = Field(default=None, description="Excel 工作表列表")
+    current_sheet: str | None = Field(default=None, description="当前预览的工作表名")
+    error: str | None = Field(default=None, description="错误信息")
+    # JSON 原始数据（用于树状显示）
+    raw_data: list[Any] | None = Field(default=None, description="JSON 原始数据（用于树状显示）")
+    # JSON 类型推断（字段名 → 推断类型）
+    type_inference: dict[str, str] | None = Field(default=None, description="JSON 字段类型推断结果")
+    # JSON 结构统计
+    field_count: int | None = Field(default=None, description="JSON 顶层字段数量")
+    nest_depth: int | None = Field(default=None, description="JSON 嵌套深度")
+
+
+class SheetSwitchRequest(BaseModel):
+    """Excel 工作表切换请求"""
+
+    file_path: str = Field(..., description="文件路径或原始名称")
+    sheet_name: str = Field(..., description="目标工作表名")
+    max_rows: int = Field(default=100, description="最大返回行数")
+    max_cols: int = Field(default=50, description="最大返回列数")
+
+
+class FilePathPreviewRequest(BaseModel):
+    """基于文件路径的预览请求"""
+
+    file_path: str = Field(..., description="文件绝对路径")
+    max_rows: int = Field(default=65535, description="最大返回行数")
+    max_cols: int = Field(default=65535, description="最大返回列数")
+    sheet_name: str | None = Field(default=None, description="Excel 工作表名")
+    # JSON 特有参数
+    json_path: str | None = Field(default=None, description="JSONPath 提取路径，如 $.data.items")
+    json_format: str | None = Field(
+        default=None, description="JSON 格式：array / lines / object（前端直接透传,auto 已废弃）"
+    )
+    record_path: str | None = Field(default=None, description="Record path，用于 pd.json_normalize")