precis-cli 0.1.3__py3-none-any.whl

app/api/routers/project/schema_helpers.py

@@ -0,0 +1,149 @@
+# 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 辅助函数模块
+
+功能概述:
+- 提供 Schema 文件路径查找、冲突检测和合并等辅助函数
+- 支持查找策略：manifest 引用、schemas/ 目录文件名匹配
+- 用于 Schema CRUD API 的底层支撑
+
+架构设计:
+- 纯函数设计，无状态无副作用，便于单元测试
+- 与 schema.py 路由层解耦，职责分离
+- 使用 YAML 读取和 Pydantic 模型进行数据验证
+
+输入示例:
+    path = _get_schema_path(manifest, "users", "/project/root")
+    conflicts = _compute_conflicts(existing_schema, new_schema)
+    merged = _merge_schemas(existing_schema, new_schema)
+
+输出示例:
+    "/project/root/schemas/users.schema.yaml"
+    ["columns", "constraints"]
+    {"version": 2, "id": "users", "columns": [...]}
+"""
+
+import os
+from typing import Any
+
+from app.shared.core.project.manifest.types import ProjectManifestV2
+
+
+def _get_schema_path(manifest: ProjectManifestV2, table_id: str, config_path: str) -> str | None:
+    """
+    获取 schema 文件路径。
+
+    查找策略：
+    1. 从 manifest.schemas 中查找引用，并验证引用路径实际存在
+    2. 扫描 schemas/ 目录，按文件名（去除 .schema.yaml 后缀）= table_id 查找
+       （兼容直接以节点 ID 作为文件名的项目）
+    """
+    ref = next((s for s in manifest.schemas if s.id == table_id), None)
+    if ref:
+        ref_path = os.path.join(config_path, ref.path)
+        if os.path.isfile(ref_path):
+            return ref_path
+
+    schemas_dir = os.path.join(config_path, "schemas")
+    if os.path.isdir(schemas_dir):
+        for filename in os.listdir(schemas_dir):
+            if filename.lower().endswith(".schema.yaml"):
+                tid = filename[:-12]
+                if tid == table_id:
+                    return os.path.join(schemas_dir, filename)
+    return None
+
+
+def _compute_conflicts(existing: dict[str, Any], new: dict[str, Any]) -> list[str]:
+    """
+    计算两个 schema 之间的冲突字段。
+
+    比较策略：
+    - 顶层字段：version, id, name, source, sheet, columns, constraints, script_checks
+    - columns 列表：比较列 ID、name、type
+    - constraints 列表：比较约束 ID 和类型
+    """
+    conflict_fields = []
+
+    for field in ["version", "id", "name", "source", "sheet", "columns", "constraints", "script_checks"]:
+        if field in existing and field in new:
+            if field == "columns":
+                existing_cols = existing.get("columns", [])
+                new_cols = new.get("columns", [])
+                if len(existing_cols) != len(new_cols):
+                    conflict_fields.append(f"columns (数量: {len(existing_cols)} vs {len(new_cols)})")
+                else:
+                    column_conflicts = []
+                    for i, (ec, nc) in enumerate(zip(existing_cols, new_cols)):
+                        if (
+                            ec.get("id") != nc.get("id")
+                            or ec.get("name") != nc.get("name")
+                            or ec.get("type") != nc.get("type")
+                        ):
+                            column_conflicts.append(f"columns[{i}]")
+                    if column_conflicts:
+                        conflict_fields.append("columns")
+                        conflict_fields.extend(column_conflicts)
+            elif field == "constraints":
+                existing_constraints = existing.get("constraints", [])
+                new_constraints = new.get("constraints", [])
+                if len(existing_constraints) != len(new_constraints):
+                    conflict_fields.append(f"constraints (数量: {len(existing_constraints)} vs {len(new_constraints)})")
+            elif existing[field] != new[field]:
+                conflict_fields.append(field)
+        elif field in existing or field in new:
+            conflict_fields.append(field)
+
+    return conflict_fields
+
+
+def _merge_schemas(existing: dict[str, Any], new: dict[str, Any]) -> dict[str, Any]:
+    """
+    合并两个 schema 配置。
+
+    合并策略：
+    - version: 使用新的
+    - id: 使用新的（必须一致）
+    - name: 使用新的
+    - source: 使用新的
+    - sheet: 使用新的
+    - columns: 使用新的（替换）
+    - constraints: 追加新的约束，保留已有的
+    - script_checks: 追加新的，保留已有的
+    """
+    merged = existing.copy()
+
+    for field in ["version", "id", "name", "source", "sheet", "columns"]:
+        if field in new:
+            merged[field] = new[field]
+
+    if "constraints" in new:
+        existing_constraints = merged.get("constraints", [])
+        new_constraints = new.get("constraints", [])
+        existing_ids = {c.get("id") for c in existing_constraints}
+        for nc in new_constraints:
+            if nc.get("id") not in existing_ids:
+                existing_constraints.append(nc)
+        merged["constraints"] = existing_constraints
+
+    if "script_checks" in new:
+        existing_checks = merged.get("script_checks", [])
+        new_checks = new.get("script_checks", [])
+        existing_checks.extend(new_checks)
+        merged["script_checks"] = existing_checks
+
+    return merged

app/api/routers/project/settings.py

@@ -0,0 +1,399 @@
+# 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 - 项目设置、校验设置、文件处理、脚本安全
+
+功能概述:
+- 提供项目各类设置的独立读写接口（ProjectSettings / Validation / FileProcessing / ScriptSecurity）
+- 所有设置存储在 manifest 的 settings 字段中，保证原子性
+- 支持按需加载与保存，减少前端数据传输
+
+架构设计:
+- 每个设置类别有独立的 GET/PUT 端点，避免全量覆盖
+- 读取时解析 manifest，写入时仅更新对应子字段
+- 使用 exclude_none=True 清理空值，保持 YAML 整洁
+
+输入示例:
+    GET /config/settings
+    PUT /config/validation (body: ValidationSettingsV2)
+
+输出示例:
+    ProjectSettingsV2 / ValidationSettingsV2 / FileProcessingSettingsV2 / ScriptSecuritySettingsV2
+    StandardResponse: 操作结果消息
+"""
+
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.api.dependencies import get_project_config_path
+from app.shared.core.io.yaml import read_yaml, write_yaml_atomic
+from app.shared.core.project.manifest.types import ProjectManifestV2
+
+from .base import (
+    FileProcessingSettingsV2,
+    ProjectSettingsV2,
+    ScriptSecuritySettingsV2,
+    StandardResponse,
+    ValidationSettingsV2,
+    _v2_manifest_path,
+)
+from .helpers import project_lock
+
+router = APIRouter(prefix="", tags=["Project-Settings"])
+
+
+def _save_manifest_field(
+    config_path: str,
+    apply: Callable[[ProjectManifestV2], None],
+    *,
+    read_log: str,
+    write_log: str,
+    success_message: str,
+) -> dict[str, str]:
+    """读取 manifest → 修改指定字段 → 写回的通用辅助函数。
+
+    所有 PUT 端点共享此逻辑，仅 apply 回调（修改哪个字段）和文案不同。
+
+    Args:
+        config_path: 项目配置根目录
+        apply: 接收 manifest 对象并就地修改目标字段的回调
+        read_log: 读取失败时的日志消息
+        write_log: 写入失败时的日志消息
+        success_message: 成功时返回给前端的消息
+
+    Returns:
+        {"message": success_message}
+    """
+    manifest_path = _v2_manifest_path(config_path)
+    if not os.path.isfile(manifest_path):
+        raise HTTPException(
+            status_code=404,
+            detail={
+                # §2.1: 结构化错误码统一（与 dependencies.py 的 manifest 缺失出口同构），
+                # 前端按 detail.code 识别项目失效并触发自愈
+                "code": "PROJECT_NOT_FOUND",
+                "message": f"项目配置文件（project.precis.yaml）不存在，请确认项目是否已被移动或删除（配置目录: {manifest_path}）",
+                "path": str(
+                    config_path
+                ),  # §2.1: 项目根目录（前端与 activeProjectPath 同口径比对，勿传 manifest 文件路径）
+            },
+        )
+    try:
+        raw = read_yaml(Path(manifest_path))
+        manifest = ProjectManifestV2.model_validate(raw)
+    except Exception as exc:
+        logging.getLogger(__name__).exception(read_log)
+        raise HTTPException(status_code=500, detail=f"设置文件读取失败: {exc}")
+    apply(manifest)
+    try:
+        with project_lock(config_path):
+            write_yaml_atomic(Path(manifest_path), manifest.model_dump(exclude_none=True))
+    except Exception as exc:
+        logging.getLogger(__name__).exception(write_log)
+        raise HTTPException(status_code=500, detail=f"设置文件保存失败: {exc}")
+    return {"message": success_message}
+
+
+@router.get(
+    "/config/settings",
+    response_model=ProjectSettingsV2,
+    summary="读取当前项目的设置",
+    responses={
+        404: {"description": "项目配置文件（project.precis.yaml）不存在"},
+        500: {"description": "设置文件读取失败"},
+    },
+)
+def get_v2_project_settings(config_path: str = Depends(get_project_config_path)) -> ProjectSettingsV2:
+    """
+    读取当前项目的设置（从 project.precis.yaml 的 settings 字段）。
+
+    使用场景：
+    - 前端加载项目设置界面
+    - 需要获取项目的通用配置
+
+    副作用：
+    - 如果 manifest 文件不存在，返回 404 错误
+
+    参数:
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        ProjectSettingsV2: 项目设置对象
+    """
+    manifest_path = _v2_manifest_path(config_path)
+    if not os.path.isfile(manifest_path):
+        raise HTTPException(
+            status_code=404,
+            detail={
+                # §2.1: 结构化错误码统一（与 dependencies.py 的 manifest 缺失出口同构），
+                # 前端按 detail.code 识别项目失效并触发自愈
+                "code": "PROJECT_NOT_FOUND",
+                "message": f"项目配置文件（project.precis.yaml）不存在，请确认项目是否已被移动或删除（配置目录: {manifest_path}）",
+                "path": str(
+                    config_path
+                ),  # §2.1: 项目根目录（前端与 activeProjectPath 同口径比对，勿传 manifest 文件路径）
+            },
+        )
+    try:
+        raw = read_yaml(Path(manifest_path))
+        manifest = ProjectManifestV2.model_validate(raw)
+    except Exception as exc:
+        logging.getLogger(__name__).exception("Failed to read project settings")
+        raise HTTPException(status_code=500, detail=f"设置文件读取失败: {exc}")
+    return manifest.settings
+
+
+@router.put(
+    "/config/settings",
+    response_model=StandardResponse,
+    summary="写入当前项目的设置",
+    responses={
+        404: {"description": "项目配置文件（project.precis.yaml）不存在"},
+        500: {"description": "设置文件保存失败"},
+    },
+)
+def put_v2_project_settings(
+    settings: ProjectSettingsV2, config_path: str = Depends(get_project_config_path)
+) -> dict[str, str]:
+    """
+    写入当前项目的设置（更新 project.precis.yaml 的 settings 字段）。
+
+    使用场景：
+    - 用户修改项目设置后保存
+
+    副作用：
+    - 直接覆盖 manifest 中的 settings 字段
+    - 使用 exclude_none=True 清理空值
+
+    参数:
+        settings: 新的项目设置
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        StandardResponse: 操作结果消息
+    """
+    return _save_manifest_field(
+        config_path,
+        lambda m: setattr(m, "settings", settings),
+        read_log="Failed to read project settings for update",
+        write_log="Failed to write project settings",
+        success_message="项目设置已保存。",
+    )
+
+
+@router.get(
+    "/config/validation",
+    response_model=ValidationSettingsV2,
+    summary="读取当前项目的校验行为设置",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def get_v2_validation_settings(config_path: str = Depends(get_project_config_path)) -> ValidationSettingsV2:
+    """
+    读取当前项目的校验行为设置。
+
+    使用场景：
+    - 前端加载校验设置界面
+    - 全量校验时获取校验配置
+
+    副作用：
+    - 调用 get_v2_project_settings 获取完整设置
+
+    参数:
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        ValidationSettingsV2: 校验设置对象
+    """
+    settings = get_v2_project_settings(config_path)
+    return settings.validation
+
+
+@router.put(
+    "/config/validation",
+    response_model=StandardResponse,
+    summary="写入当前项目的校验行为设置",
+    responses={
+        404: {"description": "项目配置文件（project.precis.yaml）不存在"},
+        500: {"description": "设置文件保存失败"},
+    },
+)
+def put_v2_validation_settings(
+    validation: ValidationSettingsV2, config_path: str = Depends(get_project_config_path)
+) -> dict[str, str]:
+    """
+    写入当前项目的校验行为设置。
+
+    使用场景：
+    - 用户修改校验设置后保存
+
+    副作用：
+    - 只更新 settings.validation 字段
+    - 保留其他 settings 字段不变
+
+    参数:
+        validation: 新的校验设置
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        StandardResponse: 操作结果消息
+    """
+    return _save_manifest_field(
+        config_path,
+        lambda m: setattr(m.settings, "validation", validation),
+        read_log="Failed to read validation settings",
+        write_log="Failed to write validation settings",
+        success_message="校验设置已保存。",
+    )
+
+
+@router.get(
+    "/config/file-processing",
+    response_model=FileProcessingSettingsV2,
+    summary="读取当前项目的文件处理设置",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def get_v2_file_processing_settings(config_path: str = Depends(get_project_config_path)) -> FileProcessingSettingsV2:
+    """
+    读取当前项目的文件处理设置。
+
+    使用场景：
+    - 前端加载文件处理设置界面
+    - 数据加载时获取文件编码、分隔符等配置
+
+    副作用：
+    - 调用 get_v2_project_settings 获取完整设置
+
+    参数:
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        FileProcessingSettingsV2: 文件处理设置对象
+    """
+    settings = get_v2_project_settings(config_path)
+    return settings.file_processing
+
+
+@router.put(
+    "/config/file-processing",
+    response_model=StandardResponse,
+    summary="写入当前项目的文件处理设置",
+    responses={
+        404: {"description": "项目配置文件（project.precis.yaml）不存在"},
+        500: {"description": "设置文件保存失败"},
+    },
+)
+def put_v2_file_processing_settings(
+    file_processing: FileProcessingSettingsV2, config_path: str = Depends(get_project_config_path)
+) -> dict[str, str]:
+    """
+    写入当前项目的文件处理设置。
+
+    使用场景：
+    - 用户修改文件处理设置后保存（如 CSV 分隔符、编码等）
+
+    副作用：
+    - 只更新 settings.file_processing 字段
+    - 保留其他 settings 字段不变
+
+    参数:
+        file_processing: 新的文件处理设置
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        StandardResponse: 操作结果消息
+    """
+    return _save_manifest_field(
+        config_path,
+        lambda m: setattr(m.settings, "file_processing", file_processing),
+        read_log="Failed to read file-processing settings",
+        write_log="Failed to write file-processing settings",
+        success_message="文件处理设置已保存。",
+    )
+
+
+@router.get(
+    "/config/script-security",
+    response_model=ScriptSecuritySettingsV2,
+    summary="读取当前项目的脚本安全设置",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def get_v2_script_security_settings(config_path: str = Depends(get_project_config_path)) -> ScriptSecuritySettingsV2:
+    """
+    读取当前项目的脚本安全设置。
+
+    使用场景：
+    - 前端加载脚本安全设置界面
+    - 约束校验时判断是否允许 eval/exec
+
+    副作用：
+    - 调用 get_v2_project_settings 获取完整设置
+
+    参数:
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        ScriptSecuritySettingsV2: 脚本安全设置对象
+    """
+    settings = get_v2_project_settings(config_path)
+    return settings.script_security
+
+
+@router.put(
+    "/config/script-security",
+    response_model=StandardResponse,
+    summary="写入当前项目的脚本安全设置",
+    responses={
+        404: {"description": "项目配置文件（project.precis.yaml）不存在"},
+        500: {"description": "设置文件保存失败"},
+    },
+)
+def put_v2_script_security_settings(
+    script_security: ScriptSecuritySettingsV2, config_path: str = Depends(get_project_config_path)
+) -> dict[str, str]:
+    """
+    写入当前项目的脚本安全设置。
+
+    使用场景：
+    - 用户修改脚本安全设置后保存（如是否允许 eval/exec）
+
+    副作用：
+    - 只更新 settings.script_security 字段
+    - 保留其他 settings 字段不变
+
+    参数:
+        script_security: 新的脚本安全设置
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        StandardResponse: 操作结果消息
+    """
+    return _save_manifest_field(
+        config_path,
+        lambda m: setattr(m.settings, "script_security", script_security),
+        read_log="Failed to read script-security settings",
+        write_log="Failed to write script-security settings",
+        success_message="脚本安全设置已保存。",
+    )