precis-cli 0.1.3__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,16 @@
+# 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 Precis 后端应用包入口"""

app/api/__init__.py

@@ -0,0 +1,32 @@
+# 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 模块包入口
+
+功能概述:
+- 标记 backend/app/api 目录为 Python 包
+- 作为 API 层的统一入口，供外部导入使用
+
+架构设计:
+- 该包包含 FastAPI 应用、依赖注入、中间件、数据模型和路由等子模块
+- 通过 __init__.py 暴露公共接口，简化外部导入路径
+
+输入示例:
+    from app.api import main
+
+输出示例:
+    无直接输出，仅作为包标记
+"""

app/api/dependencies.py

@@ -0,0 +1,185 @@
+# 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 依赖注入模块
+
+功能概述:
+- 提供 FastAPI 依赖注入函数
+- 从 HTTP Header 获取并验证项目配置路径
+- 提供 ProjectStore 数据容器在请求生命周期内传递项目路径
+
+架构设计:
+- 使用 FastAPI 的 Depends 机制实现依赖注入
+- 通过 X-Project-Config-Path Header 接收项目路径，支持多项目
+- 路径验证包括绝对路径检查和目录存在性检查
+- ProjectStore 可轻松 mock，便于单元测试
+
+输入示例:
+    Header: X-Project-Config-Path: D:/project （项目根，须含 project.precis.yaml）
+
+输出示例:
+    ProjectStore(project_path="D:/project")
+"""
+
+# backend/app/api/dependencies.py
+import os
+
+from fastapi import Depends, Header, HTTPException
+
+
+class ProjectStore:
+    """
+    项目存储类。
+
+    这是一个简单的数据容器类，用于在 FastAPI 依赖注入链中传递项目路径信息。
+    通过将项目路径封装为对象，可以在类型提示中明确表达依赖关系。
+
+    设计目的：
+    - 提供类型安全的项目路径传递方式
+    - 方便在路由处理器中获取项目根目录
+    - 支持依赖注入的单元测试（可轻松 mock）
+
+    属性：
+        project_path: 项目配置目录的绝对路径
+    """
+
+    def __init__(self, project_path: str):
+        """
+        初始化项目存储对象。
+
+        :param project_path: 项目配置目录的绝对路径
+        """
+        self.project_path = project_path
+
+
+async def get_project_config_path(
+    x_project_config_path: str = Header(..., description="项目根目录的绝对路径（须含 project.precis.yaml）"),
+) -> str:
+    """
+    获取并验证项目配置路径的依赖函数。
+
+    该函数是 FastAPI 的依赖项，用于从 HTTP Header 中提取项目配置路径，
+    并进行合法性验证：
+    1. 检查路径是否为绝对路径
+    2. 检查路径对应的目录是否存在
+    3. 必须含 project.precis.yaml（合法 Precis 项目根标识）
+
+    B-sec3 安全加固: 原校验仅"绝对+是目录"，任意目录都能当项目根，导致后续
+    manifest/数据源/AI 配置写入可能落到任意目录。现对齐 AI 路由的
+    validate_project_path，要求 manifest 存在。项目首次创建走独立的
+    /projects/create 端点（不经此依赖），故不影响创建流程。
+
+    处理流程：
+    1. 从 X-Project-Config-Path Header 获取路径
+    2. 委托 _validate_project_root 做完整校验（绝对路径/拒绝 `..`/目录存在/manifest 存在）
+    3. 返回验证后的绝对路径
+
+    :param x_project_config_path: HTTP Header 中的项目配置路径
+    :return: 验证通过的项目配置绝对路径
+    :raises HTTPException: 路径验证失败时返回 400 或 404 错误
+
+    Header 示例（项目根目录语义，不是 .precis/ 子目录）：
+        X-Project-Config-Path: /path/to/project
+    """
+    return _validate_project_root(x_project_config_path)
+
+
+def _validate_project_root(raw_path: str | None) -> str:
+    """校验路径是否为合法 Precis 项目根（单一事实源）。
+
+    B-sec3: 统一 get_project_config_path 与 ai/utils.validate_project_path 的校验逻辑，
+    消除双套不一致（原 ai 路径要求 manifest，通用依赖不要求，弱者为默认）。
+
+    要求：
+    - 非空
+    - 必须是绝对路径（Windows 下 abspath 会把相对路径转绝对，故须在规范化前先判）
+    - 不含 ".."（normpath 后仍不含）
+    - 必须是存在的目录
+    - 必须含 project.precis.yaml（合法项目根标识）
+
+    参数:
+        raw_path: 原始路径字符串（通常来自 Header）
+
+    返回:
+        规范化后的绝对路径
+
+    抛出:
+        HTTPException(400): 校验失败
+    """
+    if not raw_path:
+        raise HTTPException(status_code=400, detail="X-Project-Config-Path header 不能为空。")
+    # 步骤1：先校验原始输入是否为绝对路径
+    # 在 Windows 下，os.path.abspath 会把相对路径（如 "../project"）解析成绝对路径，
+    # 导致后续 isabs 检查无法拒绝相对路径。因此必须在规范化之前先做判断。
+    if not os.path.isabs(raw_path):
+        raise HTTPException(status_code=400, detail="X-Project-Config-Path header 必须是一个绝对路径。")
+
+    # 路径标准化并解析为绝对路径，防御 Path Traversal
+    normalized_path = os.path.abspath(os.path.normpath(raw_path))
+    # 拒绝路径穿越（normpath 后仍出现 .. 说明超出根）
+    if ".." in normalized_path.split(os.sep):
+        raise HTTPException(status_code=400, detail="X-Project-Config-Path 不允许包含 .. 目录穿越。")
+
+    # 步骤2：验证路径对应的目录是否存在
+    if not os.path.isdir(normalized_path):
+        raise HTTPException(status_code=404, detail=f"提供的项目配置路径不存在: {normalized_path}")
+
+    # 步骤3：验证是合法 Precis 项目根（含 manifest）
+    manifest = os.path.join(normalized_path, "project.precis.yaml")
+    if not os.path.isfile(manifest):
+        # §2.1: manifest 缺失属"资源不存在"语义，统一 404（原 400 与 GET /manifest
+        # 端点对同一情形不同状态码，且前端 404 自愈链永不触发）。detail 携带结构化
+        # 错误码，前端按 detail.code 识别（不再匹配中文措辞前缀）。
+        raise HTTPException(
+            status_code=404,
+            detail={
+                "code": "PROJECT_NOT_FOUND",
+                "message": (
+                    "项目路径下未找到 project.precis.yaml（非合法 Precis 项目根）。"
+                    "若要初始化新项目，请使用 POST /api/latest/projects/create。"
+                ),
+                "path": normalized_path,
+            },
+        )
+
+    return normalized_path
+
+
+async def get_project_store(project_path: str = Depends(get_project_config_path)) -> ProjectStore:
+    """
+    创建项目存储对象的依赖函数。
+
+    该函数是 FastAPI 的依赖项，负责：
+    1. 调用 get_project_config_path 获取验证后的项目路径
+    2. 创建 ProjectStore 实例并返回
+
+    这种分层设计的好处：
+    - 职责分离：路径验证和对象创建分别处理
+    - 可复用性：get_project_config_path 可以被其他依赖函数复用
+    - 可测试性：每个函数都可以独立进行单元测试
+
+    :param project_path: 已验证的项目配置路径（由 get_project_config_path 注入）
+    :return: 包含项目路径的 ProjectStore 实例
+
+    使用示例：
+        @app.get("/projects/{project_id}/schemas")
+        async def get_schemas(project: ProjectStore = Depends(get_project_store)):
+            # 可以直接使用 project.project_path 访问项目路径
+            schemas = load_schemas(project.project_path)
+            return schemas
+    """
+    # 创建并返回项目存储对象，将路径封装为对象形式
+    return ProjectStore(project_path=project_path)

app/api/main.py

@@ -0,0 +1,301 @@
+# 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.
+# backend/app/api/main.py
+"""
+@fileoverview FastAPI 应用入口模块
+
+功能概述:
+- 创建和配置 FastAPI 应用实例
+- 配置 CORS 中间件支持跨域请求
+- 注册所有 API 路由
+- 提供根路径的健康检查端点
+
+架构设计:
+- 单入口: 所有路由通过此模块注册
+- 中间件模式: 使用 FastAPI 中间件机制处理横切关注点
+- 模块化路由: 路由按功能模块分组（project, utils, reporting 等）
+
+Electron 集成说明:
+- 打包模式：主进程每次启动后端生成随机 token，经 PRECIS_API_TOKEN 注入本进程，
+  TokenOriginAuthMiddleware 对携带有效 token（X-Precis-Auth 头）的请求放行 null
+  Origin 的 CORS（预检代答 + 响应头补写）；无效/缺失 token 的 null Origin 仍被
+  DynamicPortCORSMiddleware 拒绝（防沙箱 iframe 跨域读取本机 API）
+- DynamicPortCORSMiddleware 放行 Electron 自定义协议（app:// / electron://），
+  支持 127.0.0.1 / localhost 的任意端口（动态端口分配）
+- 桌面应用经内嵌窗口加载前端，无跨站风险
+- PRECIS_ALLOW_NULL_ORIGIN=1 为旧的全局放行兼容开关（DynamicPortCORSMiddleware
+  内保留读取逻辑），打包模式已改用 token 机制、不再注入该变量
+
+日志配置:
+- 配置 logging 以显示 HTTP 请求和响应信息
+- 使用 uvicorn 的访问日志记录器
+- 可通过环境变量 LOG_LEVEL 控制日志级别
+"""
+
+import logging
+import os
+import re
+import sys
+
+# ============================================================================
+# 日志与输出配置
+# ============================================================================
+
+logger = logging.getLogger(__name__)
+logger.info("[INIT] Precis Backend 启动中...")
+logger.info("[INIT] Python 版本: %s", sys.version)
+
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+
+from .middleware.exception_handler import (
+    ExceptionHandlerMiddleware,
+    request_validation_exception_handler,
+)
+from .middleware.request_logging import RequestLoggingMiddleware
+from .middleware.token_auth import TokenOriginAuthMiddleware
+from .routers import (
+    ai_router,
+    connection_rules_router,
+    data_sources_router,
+    files_router,
+    preview_router,
+    project_router,
+    projects_router,
+    regex_router,
+    reporting_router,
+    validation_router,
+)
+
+# ============================================================================
+# FastAPI 应用创建
+# ============================================================================
+
+# 创建 FastAPI 应用实例
+# [FastAPI 配置说明]
+# - title: API 文档中显示的标题
+# - description: API 功能描述
+# - version: API 版本号，用于版本管理
+app = FastAPI(
+    title="数据校验工具 API",
+    description="为数据校验工具前端提供后端服务的 API。",
+    version="1.0.0",
+)
+
+# 初始化应用状态（Web 模式使用）
+app.state.current_project_path = None
+app.state.current_project_name = None
+
+# 端口文件自愈：uvicorn --reload 重启 app 进程时（或外部进程误删端口文件后），
+# 依据 start_server 通过环境变量传入的实际端口重写 backend/.backend-port，
+# 保证 Vite 代理 / Electron 主进程始终能发现后端，避免 502。
+_actual_port_env = os.environ.get("PRECIS_BACKEND_PORT_ACTUAL")
+if _actual_port_env and _actual_port_env.isdigit():
+    from app.shared.core.config.server import write_port_file
+
+    write_port_file(int(_actual_port_env))
+
+# ============================================================================
+# 日志配置
+# ============================================================================
+
+
+def configure_logging() -> None:
+    """配置 logging 以显示 HTTP 请求和响应信息。"""
+    log_level = os.environ.get("LOG_LEVEL", "INFO").upper()
+    uvicorn_logger = logging.getLogger("uvicorn")
+    uvicorn_logger.setLevel(log_level)
+
+    # 减少 FastAPI reload 模式的日志噪音
+    if os.environ.get("UVICORN_RELOAD", "").lower() in ("true", "1"):
+        logging.getLogger("uvicorn.error").setLevel(logging.WARNING)
+
+    logger.info("[CONFIG] 日志级别: %s", log_level)
+
+
+configure_logging()
+
+# ============================================================================
+# CORS 中间件配置
+# ============================================================================
+
+# 自定义 CORS 中间件，支持动态端口匹配
+
+
+class DynamicPortCORSMiddleware(CORSMiddleware):
+    """
+    支持动态端口与桌面应用协议的 CORS 中间件
+
+    功能:
+    - 允许 127.0.0.1 和 localhost 的任意端口访问（支持动态端口分配）
+    - 放行 Electron 自定义协议（app:// / electron://）下浏览器发送的 null/空 Origin
+    - 保留原有 CORS 中间件的所有功能
+
+    [安全考量]
+    - null/空 Origin 默认拒绝：后端无鉴权且存在文件读取端点，沙箱 iframe / file:// 页面
+      发送的 null Origin 一旦放行，任意网页可跨域读取本机 API 响应（loopback 端口可被
+      浏览器枚举）。打包模式改由 TokenOriginAuthMiddleware 按"一次性 token"放行本应用
+      页面（携带有效 X-Precis-Auth 头的请求在其上游补写 CORS 头/代答预检），本中间件
+      不再对 null Origin 无差别放行；PRECIS_ALLOW_NULL_ORIGIN=1 保留为兼容开关
+      （Electron 旧版主进程注入时仍生效），打包模式不再注入。
+    - 若未来该 API 暴露到网络（非 127.0.0.1），必须进一步收紧（token 鉴权 + Host 校验）。
+    """
+
+    def is_allowed_origin(self, origin: str) -> bool:
+        """
+        @methoddesc 判断请求 Origin 是否被允许
+
+        业务用途:
+        - 在 CORS 握手阶段决定是否在响应中回写 Access-Control-Allow-Origin
+        - 在标准 allow_origins 之外，额外放行桌面应用场景下的特殊 Origin
+
+        参数:
+            origin: 浏览器请求头中的 Origin 字段（形如 ``http://127.0.0.1:5173``、
+                    ``app://.`` 或 ``null``）
+
+        返回:
+            True 表示允许该 Origin 的跨域请求，False 表示拒绝
+        """
+        # Electron 打包模式已改用一次性 token 机制（TokenOriginAuthMiddleware 对携带
+        # 有效 X-Precis-Auth 头的请求补写 CORS 头）。此处保留 PRECIS_ALLOW_NULL_ORIGIN
+        # 兼容开关：旧版 Electron 主进程注入该变量时仍对 null/空 Origin 全局放行。
+        # 默认拒绝：null Origin 也来自沙箱 iframe 与 file:// 页面——后端无鉴权且存在
+        # 文件读取端点，放行 null 等于允许任意网页经沙箱 iframe 跨域读取本机 API 响应。
+        if (origin == "null" or origin == "") and os.environ.get("PRECIS_ALLOW_NULL_ORIGIN", "").strip().lower() in (
+            "1",
+            "true",
+            "yes",
+        ):
+            return True
+
+        # 检查是否在明确允许列表中
+        if origin in self.allow_origins:
+            return True
+
+        # 支持 127.0.0.1 和 localhost 的任意端口（动态端口分配场景）
+        # 匹配 http://127.0.0.1:PORT 或 http://localhost:PORT 格式
+        if re.match(r"^http://(127\.0\.0\.1|localhost):\d+$", origin):
+            return True
+
+        return False
+
+
+# 定义允许的跨域来源列表
+# [设计说明]
+# - 明确列出允许的来源，而非使用通配符，便于审计
+# - 127.0.0.1 / localhost 的任意端口及 null/空 Origin 由中间件逻辑放行（见上）
+# - [安全考量] 生产环境应限制为具体域名，避免开放过多来源
+origins = [
+    # 后端自检（动态端口范围）
+    "http://127.0.0.1:8000",
+    # macOS Electron 应用协议（前端打包后以 app://./index.html 加载）
+    "app://.",
+    # Electron 通用协议
+    "electron://.",
+]
+
+# 422 请求校验错误全局 handler：detail 结构保持 FastAPI 默认，msg 本地化为中文
+app.add_exception_handler(RequestValidationError, request_validation_exception_handler)
+
+app.add_middleware(
+    DynamicPortCORSMiddleware,
+    allow_origins=origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# 一次性 token 放行中间件（打包模式）：
+# [中间件顺序] FastAPI/Starlette 的 add_middleware 后添加的先执行（外层）。
+# 本中间件在 CORSMiddleware 之后添加 → 位于 CORS 外层、先于 CORS 处理请求：
+# - 携带有效 token（X-Precis-Auth）的 null Origin 预检在此被直接代答放行，
+#   不会被 CORSMiddleware 以"Origin 不在允许列表"拒绝
+# - 无效/缺失 token 的请求原样透传给 CORSMiddleware，null Origin 仍按既有规则拒绝
+# - 未配置 PRECIS_API_TOKEN（Web/开发模式）时完全直通，既有 localhost CORS 行为不变
+app.add_middleware(TokenOriginAuthMiddleware)
+
+app.add_middleware(ExceptionHandlerMiddleware)
+app.add_middleware(RequestLoggingMiddleware)
+
+# ============================================================================
+# 路由注册
+# ============================================================================
+
+# 注册各功能模块的路由
+# [FastAPI] include_router 将路由添加到应用
+# 路由顺序不影响匹配，FastAPI 使用最长前缀匹配
+# 【路由列表】按功能模块分组，便于维护和扩展
+app.include_router(project_router)  # 项目管理路由（V2 配置读写）
+app.include_router(projects_router)  # 项目扫描路由（Web 模式）
+app.include_router(files_router)  # 文件操作路由（Web 模式）
+app.include_router(ai_router)  # AI 辅助路由（智能提示、生成）
+app.include_router(regex_router)  # 正则表达式路由（测试、验证）
+app.include_router(reporting_router)  # 报告路由（校验结果导出）
+app.include_router(preview_router)  # 预览路由（数据预览、Schema 预览）
+app.include_router(data_sources_router)  # 数据源路由（文件上传、加载）
+app.include_router(validation_router)  # 校验路由（执行校验、获取结果）
+app.include_router(connection_rules_router)  # 连接规则路由（画布连线规则）
+
+# ============================================================================
+# 根路径路由
+# ============================================================================
+
+
+@app.get("/")
+async def root() -> dict[str, str]:
+    """
+    @methoddesc 根路径路由，返回简单的欢迎信息
+
+    业务用途:
+    - 提供 API 根路径访问时的友好提示
+    - 不包含敏感信息，适合公开访问
+    """
+    return {"message": "欢迎使用数据校验工具 API! 请访问 /docs 查看详情。"}
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    """
+    @methoddesc 健康检查端点
+
+    业务用途:
+    - 供 Electron 主进程和负载均衡器探测后端存活状态
+    - 返回 {"status": "ok"} 即表示 FastAPI 应用已启动并能响应 HTTP 请求
+
+    @returns dict - 包含 status 字段的响应对象
+    """
+    return {"status": "ok"}
+
+
+@app.get("/api/latest/version", summary="获取应用版本号")
+def get_version() -> dict[str, str]:
+    """
+    @methoddesc 返回当前应用版本号
+
+    业务用途:
+    - Web 模式下替代 Electron 的 getAppVersion IPC
+    - 版本优先级：PRECIS_APP_VERSION 环境变量（Electron 主进程注入 app.getVersion()）→
+      包元数据（开发环境 pip install -e 提供）→ "0.0.0-dev"
+      （打包环境不安装 precis 包元数据，importlib.metadata 拿不到真实版本，
+      环境变量是桌面打包场景的唯一真实来源）
+
+    @returns dict - 包含 version 字段的响应对象
+    """
+    from app.shared.core.app_version import get_app_version
+
+    ver = get_app_version(fallback="0.0.0-dev")
+    return {"version": ver}

app/api/middleware/__init__.py

@@ -0,0 +1,34 @@
+# 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 中间件模块包入口
+
+功能概述:
+- 标记 backend/app/api/middleware 目录为 Python 包
+- 聚合全局异常处理和请求日志记录等中间件组件
+
+架构设计:
+- 各中间件继承 Starlette BaseHTTPMiddleware
+- 通过主应用 main.py 统一注册，按顺序执行
+- 异常处理中间件应在最外层，请求日志在最内层
+
+输入示例:
+    from app.api.middleware.exception_handler import ExceptionHandlerMiddleware
+    from app.api.middleware.request_logging import RequestLoggingMiddleware
+
+输出示例:
+    无直接输出，仅作为包标记
+"""