precis-cli 0.1.3__py3-none-any.whl

app/api/routers/core/reporting.py

@@ -0,0 +1,263 @@
+# 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 路由模块
+
+功能概述:
+- 提供校验结果报告配置的读取和修改接口
+- 支持多种报告渠道：本地文件、邮件、企业微信、飞书、钉钉
+- 管理各报告服务的启用/禁用状态和详细配置
+
+架构设计:
+- 每种报告渠道对应独立的 Pydantic 配置模型
+- 配置持久化为项目目录下的 reporting_config.yaml
+- 不存在的配置返回默认值（local_file 启用，其余禁用）
+
+输入示例:
+    POST /reporting/config
+    {
+        "reporters": {
+            "local_file": {"enabled": true, "log_dir": "logs"},
+            "email": {"enabled": false}
+        }
+    }
+
+输出示例:
+    {"message": "报告配置已成功更新。"}
+"""
+
+import os
+from pathlib import Path
+
+import yaml
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, EmailStr, Field
+
+from app.api.dependencies import ProjectStore, get_project_store
+from app.api.services.io_error_messages import describe_io_error
+from app.shared.core.io.yaml import write_yaml_atomic
+
+router = APIRouter(prefix="/api/latest")
+
+
+class LocalFileConfig(BaseModel):
+    """本地文件报告配置
+
+    将校验结果输出到本地日志文件。
+
+    字段说明:
+        enabled: 是否启用本地文件报告
+        log_dir: 日志文件存放目录（相对于项目路径）
+    """
+
+    enabled: bool
+    log_dir: str = "logs"
+
+
+class EmailConfig(BaseModel):
+    """邮件报告配置
+
+    通过 SMTP 服务器发送校验结果邮件。
+
+    字段说明:
+        enabled: 是否启用邮件报告
+        smtp_server: SMTP 服务器地址
+        smtp_port: SMTP 服务器端口
+        sender_email: 发件人邮箱
+        sender_password: 发件人邮箱密码
+        receiver_email: 收件人邮箱
+    """
+
+    enabled: bool
+    smtp_server: str | None = None
+    smtp_port: int | None = None
+    sender_email: EmailStr | None = None
+    sender_password: str | None = None
+    receiver_email: EmailStr | None = None
+
+
+class WeComAppConfig(BaseModel):
+    """企业微信应用报告配置
+
+    通过企业微信应用发送校验结果消息。
+
+    字段说明:
+        enabled: 是否启用企业微信报告
+        corp_id: 企业ID
+        corp_secret: 应用Secret
+        agent_id: 应用ID
+        touser: 接收消息的成员ID列表，多个用'|'分隔，默认@all（所有人）
+    """
+
+    enabled: bool
+    corp_id: str | None = Field(None, description="企业ID")
+    corp_secret: str | None = Field(None, description="应用Secret")
+    agent_id: int | None = Field(None, description="应用ID")
+    touser: str | None = Field("@all", description="接收消息的成员ID列表，多个用'|'分隔")
+
+
+class FeishuAppConfig(BaseModel):
+    """飞书应用报告配置
+
+    通过飞书应用发送校验结果消息。
+
+    字段说明:
+        enabled: 是否启用飞书报告
+        app_id: 应用App ID
+        app_secret: 应用App Secret
+        receive_id_type: 接收者ID类型（open_id/user_id/email）
+        receive_ids: 接收者ID，多个用','分隔
+    """
+
+    enabled: bool
+    app_id: str | None = Field(None, description="应用App ID")
+    app_secret: str | None = Field(None, description="应用App Secret")
+    receive_id_type: str | None = Field("open_id", description="接收者ID类型, 例如: open_id, user_id, email")
+    receive_ids: str | None = Field(None, description="接收者ID, 多个用','分隔")
+
+
+class DingTalkAppConfig(BaseModel):
+    """钉钉应用报告配置
+
+    通过钉钉应用发送校验结果消息。
+
+    字段说明:
+        enabled: 是否启用钉钉报告
+        app_key: 应用AppKey（client_id）
+        app_secret: 应用AppSecret（client_secret）
+        agent_id: 应用AgentId
+        userid_list: 接收者的用户ID列表，多个用','分隔
+    """
+
+    enabled: bool
+    app_key: str | None = Field(None, description="应用AppKey (client_id)")
+    app_secret: str | None = Field(None, description="应用AppSecret (client_secret)")
+    agent_id: int | None = Field(None, description="应用AgentId")
+    userid_list: str | None = Field(None, description="接收者的用户ID列表, 多个用','分隔")
+
+
+class ReportersConfig(BaseModel):
+    """报告渠道汇总配置
+
+    包含所有支持的报告渠道配置，每个渠道独立管理。
+
+    字段说明:
+        local_file: 本地文件报告配置
+        email: 邮件报告配置
+        wecom: 企业微信报告配置
+        feishu: 飞书报告配置
+        dingtalk: 钉钉报告配置
+    """
+
+    local_file: LocalFileConfig
+    email: EmailConfig
+    wecom: WeComAppConfig
+    feishu: FeishuAppConfig
+    dingtalk: DingTalkAppConfig
+
+
+class ReportingConfig(BaseModel):
+    """报告配置根模型
+
+    作为 API 请求和响应的根对象，包含所有报告渠道的配置。
+
+    字段说明:
+        reporters: 报告渠道汇总配置
+    """
+
+    reporters: ReportersConfig
+
+
+@router.get(
+    "/reporting/config",
+    response_model=ReportingConfig,
+    summary="获取报告配置",
+    responses={
+        500: {"description": "读取报告配置文件失败"},
+    },
+)
+def get_reporting_config(store: ProjectStore = Depends(get_project_store)) -> ReportingConfig:
+    """获取报告配置
+
+    从项目目录下的 reporting_config.yaml 读取配置。
+    如果文件不存在，返回默认配置（仅启用本地文件报告）。
+
+    Args:
+        store: 项目存储依赖，包含项目路径
+
+    Returns:
+        当前项目的报告配置对象
+
+    Raises:
+        HTTPException: 读取配置文件失败时返回 500 错误
+    """
+    # 构建配置文件完整路径
+    config_path = os.path.join(store.project_path, "reporting_config.yaml")
+    if not os.path.exists(config_path):
+        # 配置文件不存在时返回默认配置
+        return ReportingConfig(
+            reporters=ReportersConfig(
+                local_file=LocalFileConfig(enabled=True, log_dir="logs"),
+                email=EmailConfig(enabled=False),
+                wecom=WeComAppConfig(enabled=False, corp_id=None, corp_secret=None, agent_id=None, touser="@all"),
+                feishu=FeishuAppConfig(
+                    enabled=False, app_id=None, app_secret=None, receive_id_type="open_id", receive_ids=None
+                ),
+                dingtalk=DingTalkAppConfig(
+                    enabled=False, app_key=None, app_secret=None, agent_id=None, userid_list=None
+                ),
+            )
+        )
+    try:
+        # 读取并解析 YAML 配置文件
+        with open(config_path, encoding="utf-8") as f:
+            config_data = yaml.safe_load(f)
+        return ReportingConfig(**config_data)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"读取报告配置文件失败：{describe_io_error(e)}")
+
+
+@router.post(
+    "/reporting/config",
+    summary="更新报告配置",
+    responses={
+        500: {"description": "写入报告配置文件失败"},
+    },
+)
+def update_reporting_config(
+    config: ReportingConfig, store: ProjectStore = Depends(get_project_store)
+) -> dict[str, str]:
+    """更新报告配置
+
+    将新的报告配置持久化保存到项目目录下的 reporting_config.yaml。
+
+    Args:
+        config: 新的报告配置对象
+        store: 项目存储依赖，包含项目路径
+
+    Returns:
+        更新成功消息
+
+    Raises:
+        HTTPException: 写入配置文件失败时返回 500 错误
+    """
+    # 构建配置文件完整路径
+    config_path = os.path.join(store.project_path, "reporting_config.yaml")
+    try:
+        write_yaml_atomic(Path(config_path), config.model_dump())
+        return {"message": "报告配置已成功更新。"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"写入报告配置文件失败：{describe_io_error(e)}")

app/api/routers/files/__init__.py

@@ -0,0 +1,24 @@
+# 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.
+"""文件操作路由聚合：/api/latest/files 下的读写操作与上传传输子路由。"""
+
+from fastapi import APIRouter
+
+from . import ops, transfer
+
+router = APIRouter(prefix="/api/latest/files", tags=["Files"])
+router.include_router(ops.router)
+router.include_router(transfer.router)

app/api/routers/files/ops.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.
+"""文件操作路由：读写文件、目录扫描与创建，路径校验限定在项目白名单根内。"""
+
+from __future__ import annotations
+
+import os
+
+from fastapi import APIRouter, HTTPException, Query
+
+from app.api.dependencies import _validate_project_root
+from app.api.models.files import (
+    DirectoryEntry,
+    FileExistsResponse,
+    MkdirRequest,
+    MkdirResponse,
+    ReadFileRequest,
+    ReadFileResponse,
+    ScanDirectoryRequest,
+    ScanDirectoryResponse,
+    WriteFileRequest,
+    WriteFileResponse,
+)
+from app.shared.services.preview.path_validation import assert_path_within_root
+
+router = APIRouter(prefix="", tags=["Files-Ops"])
+
+
+def _validated_root(root: str) -> str:
+    """校验并规范化白名单根目录。
+
+    B-sec: 此前 root 完全由客户端请求体提供,传 root="C:\\Users\\x" 即可通过
+    assert_path_within_root 的包含检查,构成任意文件读/写原语(B-sec1 防线形同虚设)。
+    现要求 root 必须是含 project.precis.yaml 的合法 Precis 项目根(复用 dependencies
+    的统一校验)。前端 Web 模式唯一调用方传的 root 即项目配置根,正常用法不受影响;
+    Electron 模式不走本端点(经原生 IPC)。
+    """
+    return _validate_project_root(root)
+
+
+@router.post(
+    "/read",
+    response_model=ReadFileResponse,
+    summary="读取文件内容",
+)
+def read_file(request: ReadFileRequest) -> ReadFileResponse:
+    """读取指定路径的文件内容。
+
+    B-sec1 安全约束: path 必须位于 root（白名单根）下，由 assert_path_within_root 强制校验，
+    拒绝项目外任意文件读取。root 通常为当前项目配置目录（X-Project-Config-Path）。
+    """
+    root = _validated_root(request.root)
+    path = assert_path_within_root(request.path, root, must_exist=False)
+    if not os.path.isfile(path):
+        raise HTTPException(status_code=404, detail=f"文件不存在: {path}")
+    try:
+        with open(path, encoding="utf-8") as f:
+            content = f.read()
+        return ReadFileResponse(content=content)
+    except UnicodeDecodeError:
+        raise HTTPException(status_code=400, detail="文件编码不是 UTF-8，暂时不支持")
+    except PermissionError:
+        raise HTTPException(status_code=403, detail="无权限读取文件")
+
+
+@router.post(
+    "/write",
+    response_model=WriteFileResponse,
+    summary="写入文件内容",
+)
+def write_file(request: WriteFileRequest) -> WriteFileResponse:
+    """写入内容到指定文件（自动创建父目录）。
+
+    B-sec1 安全约束: path 必须位于 root（白名单根）下，由 assert_path_within_root 强制校验，
+    拒绝项目外任意文件写入。
+    """
+    # 写入场景允许目标不存在，故 must_exist=False
+    root = _validated_root(request.root)
+    path = assert_path_within_root(request.path, root, must_exist=False)
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(request.content)
+        return WriteFileResponse(success=True)
+    except PermissionError:
+        raise HTTPException(status_code=403, detail="无权限写入文件")
+    except OSError as e:
+        raise HTTPException(status_code=500, detail=f"写入文件失败: {e}")
+
+
+@router.get(
+    "/exists",
+    response_model=FileExistsResponse,
+    summary="检查文件是否存在",
+)
+def check_file_exists(
+    path: str,
+    root: str = Query(..., description="项目根目录绝对路径，作为白名单根；path 必须落于此目录内"),
+) -> FileExistsResponse:
+    """检查指定路径的文件是否存在。
+
+    B-sec1 安全约束: path 必须位于 root（白名单根）下。GET 端点通过 query 参数传 root。
+    """
+    root = _validated_root(root)
+    resolved = assert_path_within_root(path, root, must_exist=False)
+    return FileExistsResponse(exists=os.path.isfile(resolved) or os.path.isdir(resolved))
+
+
+@router.post(
+    "/scan",
+    response_model=ScanDirectoryResponse,
+    summary="扫描目录内容",
+)
+def scan_directory(request: ScanDirectoryRequest) -> ScanDirectoryResponse:
+    """扫描指定目录，返回文件和子目录列表。
+
+    B-sec1 安全约束: path 必须位于 root（白名单根）下。
+    """
+    root = _validated_root(request.root)
+    path = assert_path_within_root(request.path, root, must_exist=False)
+    if not os.path.isdir(path):
+        raise HTTPException(status_code=404, detail=f"目录不存在: {path}")
+    try:
+        entries: list[DirectoryEntry] = []
+        for entry in os.scandir(path):
+            name = entry.name
+            if request.extensions and not entry.is_dir():
+                ext = os.path.splitext(name)[1].lower()
+                # B16 修复：扩展名归一化，允许调用方传 ['csv'] 或 ['.csv'] 均可命中
+                # 过去要求带前导点，传 ['csv'] 会因 '.csv' not in ['csv'] 被全部过滤
+                normalized_exts = {e if e.startswith(".") else f".{e}" for e in request.extensions}
+                normalized_exts_lower = {e.lower() for e in normalized_exts}
+                if ext not in normalized_exts_lower:
+                    continue
+            entries.append(
+                DirectoryEntry(
+                    name=name,
+                    path=os.path.abspath(entry.path),
+                    is_dir=entry.is_dir(),
+                )
+            )
+        entries.sort(key=lambda e: (not e.is_dir, e.name.lower()))
+        return ScanDirectoryResponse(entries=entries)
+    except PermissionError:
+        raise HTTPException(status_code=403, detail="无权限访问目录")
+
+
+@router.post(
+    "/mkdir",
+    response_model=MkdirResponse,
+    summary="创建目录（含父目录）",
+)
+def make_directory(request: MkdirRequest) -> MkdirResponse:
+    """递归创建目录。
+
+    B-sec1 安全约束: path 必须位于 root（白名单根）下。
+    """
+    root = _validated_root(request.root)
+    path = assert_path_within_root(request.path, root, must_exist=False)
+    try:
+        os.makedirs(path, exist_ok=True)
+        return MkdirResponse(success=True)
+    except PermissionError:
+        raise HTTPException(status_code=403, detail="无权限创建目录")
+    except OSError as e:
+        raise HTTPException(status_code=500, detail=f"创建目录失败: {e}")

app/api/routers/files/transfer.py

@@ -0,0 +1,101 @@
+# 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.
+"""文件传输路由：Web 模式下的文件上传/下载（经服务器临时目录中转）。"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import uuid
+
+from fastapi import APIRouter, File, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+
+from app.shared.services.preview.path_validation import assert_path_within_root
+
+router = APIRouter(prefix="", tags=["Files-Transfer"])
+
+# 临时文件存储目录
+TEMP_DIR = os.path.join(tempfile.gettempdir(), "precis-web-uploads")
+
+
+@router.post(
+    "/upload",
+    summary="上传文件到临时目录",
+)
+async def upload_file(file: UploadFile = File(...)) -> dict:
+    """上传文件到服务器临时目录，返回临时路径。"""
+    os.makedirs(TEMP_DIR, exist_ok=True)
+    file_id = str(uuid.uuid4())
+    # 保留原始扩展名
+    ext = os.path.splitext(file.filename or "file")[1] if file.filename else ""
+    dest_path = os.path.join(TEMP_DIR, f"{file_id}{ext}")
+    try:
+        content = await file.read()
+        with open(dest_path, "wb") as f:
+            f.write(content)
+        return {
+            "success": True,
+            "temp_path": dest_path,
+            "original_name": file.filename or "unknown",
+            "size": len(content),
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"文件上传失败: {e}")
+
+
+@router.get(
+    "/download",
+    summary="下载临时文件",
+)
+def download_file(path: str) -> FileResponse:
+    """
+    下载指定的临时上传文件。
+
+    安全约束：仅允许下载 TEMP_DIR 内的文件，防止任意文件下载。
+    """
+    resolved = assert_path_within_root(path, TEMP_DIR, must_exist=True)
+    filename = os.path.basename(resolved)
+    return FileResponse(resolved, filename=filename, media_type="application/octet-stream")
+
+
+@router.delete(
+    "/temp/{file_id:path}",
+    summary="清理临时文件",
+)
+def delete_temp_file(file_id: str) -> dict:
+    """
+    删除临时目录中的文件。
+
+    安全约束：file_id 经反穿越校验后限定在 TEMP_DIR 内，防止 `..` 逃逸。
+    """
+    # file_id 来自 path 参数，可能含 `..`；先组装再用 assert_path_within_root 限定到 TEMP_DIR
+    candidate = os.path.join(TEMP_DIR, file_id)
+    try:
+        resolved = assert_path_within_root(candidate, TEMP_DIR, must_exist=False)
+    except HTTPException:
+        raise
+    # 精确匹配
+    if os.path.isfile(resolved):
+        os.unlink(resolved)
+        return {"success": True}
+    # 尝试匹配前缀（file_id 可能不含扩展名），前缀比对基于 basename 防止逃逸
+    target_prefix = os.path.basename(resolved)
+    for f in os.listdir(TEMP_DIR):
+        if f.startswith(target_prefix):
+            os.unlink(os.path.join(TEMP_DIR, f))
+            return {"success": True}
+    raise HTTPException(status_code=404, detail="临时文件未找到")

app/api/routers/preview/__init__.py

@@ -0,0 +1,35 @@
+# 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 预览路由模块包入口
+
+功能概述:
+- 导出 preview 模块共享的 APIRouter 实例
+- 显式导入各子路由模块，确保装饰器在模块加载时完成注册
+
+架构设计:
+- `router.py` 只负责创建带 `/preview` 前缀的路由对象
+- `path_mode.py`、`content_mode.py`、`header_row.py` 通过副作用方式向同一个 router 挂载端点
+- 因此包入口必须导入这些模块，否则 FastAPI 只能拿到一个没有任何子路由的空 router
+"""
+
+# 显式导入子模块，触发 `@router.*` 装饰器执行，确保路由被真正注册。
+from . import content_mode, header_row, path_mode  # noqa: F401
+from .router import router
+
+preview_router = router
+
+__all__ = ["router", "preview_router"]