precis-cli 0.1.3__py3-none-any.whl

app/api/routers/project/template.py

@@ -0,0 +1,325 @@
+# 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 Template CRUD API - 可复用约束模板管理
+
+功能概述:
+- 提供模板定义文件的增删改查
+- 提供模板展开预览接口
+- 读取时从 manifest.templates 定位文件
+
+架构设计:
+- 读取时从 manifest.templates 中查找引用
+- 写入时自动补齐 manifest 引用，默认路径为 templates/{id}.template.yaml
+- 展开预览不写入文件，仅返回展开结果
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from app.api.dependencies import get_project_config_path
+from app.api.models.project import StandardResponse
+from app.shared.core.io.yaml import read_yaml, write_yaml_atomic
+from app.shared.core.project.template.expander import expand_template
+from app.shared.core.project.template.reader import load_template, validate_template_structure
+from app.shared.core.project.template.types import TemplateFile
+
+from .helpers import _resolve_project_path, _v2_manifest_path, project_lock
+from .manifest import get_v2_manifest
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="", tags=["Project-Template"])
+
+
+def _find_template_path(template_id: str, config_path: str) -> Path | None:
+    """从 manifest 中查找模板文件路径"""
+    manifest = get_v2_manifest(config_path)
+    for ref in manifest.templates:
+        if ref.id == template_id:
+            return Path(_resolve_project_path(config_path, ref.path))
+    return None
+
+
+# ============================================================================
+# 请求/响应模型
+# ============================================================================
+
+
+class TemplateExpandRequest(BaseModel):
+    """模板展开预览请求"""
+
+    instance_id: str
+    params: dict[str, Any] = Field(default_factory=dict, description="参数绑定值（覆盖模板默认值）")
+    input_from_node: str | None = Field(None, description="实例级上游节点 ID（通常指向 Schema）")
+
+
+class TemplateExpandResponse(BaseModel):
+    """模板展开预览响应"""
+
+    transforms: list[dict[str, Any]]
+    constraints: list[dict[str, Any]]
+    regex_nodes: list[dict[str, Any]]
+    manual_data: list[dict[str, Any]]
+    # 展开失败的节点清单（node_id/kind/message）——单节点失败不阻断预览，
+    # 其余节点正常返回，失败信息在此可见（默认空，向后兼容）
+    node_errors: list[dict[str, str]] = []
+
+
+# ============================================================================
+# CRUD 端点
+# ============================================================================
+
+
+@router.get(
+    "/template",
+    response_model=list[dict[str, Any]],
+    summary="列出所有模板定义",
+    responses={
+        404: {"description": "Manifest 不存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def list_templates(config_path: str = Depends(get_project_config_path)) -> list[dict[str, Any]]:
+    """列出所有模板定义"""
+    manifest = get_v2_manifest(config_path)
+    templates = []
+    for ref in manifest.templates:
+        tmpl_path = Path(_resolve_project_path(config_path, ref.path))
+        if tmpl_path.exists():
+            try:
+                tmpl = load_template(tmpl_path)
+                templates.append(
+                    {
+                        "id": tmpl.id,
+                        "name": tmpl.name,
+                        "description": tmpl.description,
+                        "node_count": len(tmpl.nodes),
+                        "path": ref.path,
+                    }
+                )
+            except Exception as e:
+                logger.warning(f"模板 '{ref.id}' 加载失败: {e}")
+    return templates
+
+
+@router.get(
+    "/template/{template_id}",
+    response_model=dict[str, Any],
+    summary="读取指定模板定义",
+    responses={
+        404: {"description": "模板不存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def get_template(template_id: str, config_path: str = Depends(get_project_config_path)) -> dict[str, Any]:
+    """读取指定模板定义"""
+    tmpl_path = _find_template_path(template_id, config_path)
+    if not tmpl_path or not tmpl_path.exists():
+        raise HTTPException(status_code=404, detail=f"模板 '{template_id}' 不存在")
+    tmpl = load_template(tmpl_path)
+    return tmpl.model_dump()
+
+
+@router.post(
+    "/template",
+    response_model=StandardResponse,
+    summary="创建模板定义文件",
+    responses={
+        400: {"description": "请求参数错误"},
+        409: {"description": "模板文件已存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def create_template(template_data: dict, config_path: str = Depends(get_project_config_path)) -> StandardResponse:
+    """创建模板定义文件"""
+    project_dir = Path(config_path)
+
+    # 验证数据
+    try:
+        tmpl = TemplateFile.model_validate(template_data)
+        validate_template_structure(tmpl)
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"模板数据验证失败: {e}")
+
+    # 确保目录存在
+    templates_dir = project_dir / "templates"
+    templates_dir.mkdir(parents=True, exist_ok=True)
+
+    # 写入文件
+    # B-sec: 模板 id 直接拼路径且无格式约束,含 ../ 的 id 可将文件写出项目根之外
+    # (其余资源端点均有 _resolve_project_path 校验,此处对齐)。id 应为 UUID 等安全标识。
+    try:
+        file_path = Path(_resolve_project_path(config_path, f"templates/{tmpl.id}.template.yaml"))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"模板 id 非法: {e}")
+    if file_path.exists():
+        raise HTTPException(status_code=409, detail=f"模板文件已存在: {file_path.name}")
+
+    write_yaml_atomic(file_path, tmpl.model_dump(exclude_none=True))
+
+    # 更新 manifest
+    manifest_path = Path(_v2_manifest_path(config_path))
+    with project_lock(config_path):
+        manifest_data = read_yaml(manifest_path)
+        templates_list = manifest_data.get("templates") or []
+        templates_list.append({"id": tmpl.id, "path": f"templates/{tmpl.id}.template.yaml"})
+        manifest_data["templates"] = templates_list
+        write_yaml_atomic(manifest_path, manifest_data)
+
+    return StandardResponse(success=True, message=f"模板 '{tmpl.id}' 创建成功")
+
+
+@router.put(
+    "/template/{template_id}",
+    response_model=StandardResponse,
+    summary="更新模板定义文件",
+    responses={
+        400: {"description": "请求参数错误"},
+        404: {"description": "模板不存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def update_template(
+    template_id: str,
+    template_data: dict,
+    config_path: str = Depends(get_project_config_path),
+) -> StandardResponse:
+    """
+    @methoddesc 更新模板定义文件
+
+    业务用途:
+    - 覆盖写入 templates/{template_id}.template.yaml
+    - 模板不存在时返回 404
+
+    参数:
+        template_id: 模板唯一标识
+        template_data: 模板新内容（任意字典）
+        config_path: 项目配置路径
+
+    返回:
+        StandardResponse: 写入结果
+    """
+    tmpl_path = _find_template_path(template_id, config_path)
+    if not tmpl_path or not tmpl_path.exists():
+        raise HTTPException(status_code=404, detail=f"模板 '{template_id}' 不存在")
+
+    # 验证数据
+    try:
+        tmpl = TemplateFile.model_validate(template_data)
+        validate_template_structure(tmpl)
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"模板数据验证失败: {e}")
+
+    write_yaml_atomic(tmpl_path, tmpl.model_dump(exclude_none=True))
+    return StandardResponse(success=True, message=f"模板 '{template_id}' 更新成功")
+
+
+@router.delete(
+    "/template/{template_id}",
+    response_model=StandardResponse,
+    summary="删除模板定义文件",
+    responses={
+        404: {"description": "模板不存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def delete_template(template_id: str, config_path: str = Depends(get_project_config_path)) -> StandardResponse:
+    """删除模板定义文件"""
+    tmpl_path = _find_template_path(template_id, config_path)
+    if not tmpl_path or not tmpl_path.exists():
+        raise HTTPException(status_code=404, detail=f"模板 '{template_id}' 不存在")
+
+    with project_lock(config_path):
+        if tmpl_path and tmpl_path.exists():
+            tmpl_path.unlink()
+
+        manifest_path = Path(_v2_manifest_path(config_path))
+        manifest_data = read_yaml(manifest_path)
+        templates_list = manifest_data.get("templates") or []
+        manifest_data["templates"] = [t for t in templates_list if t.get("id") != template_id]
+        # 级联清理：删除模板定义后，仍指向它的实例引用会成为永久悬空引用
+        # （每次项目加载都产生 TemplateInstanceMissingTemplate 错误），随定义一并移除
+        instances_list = manifest_data.get("template_instances") or []
+        manifest_data["template_instances"] = [ti for ti in instances_list if ti.get("template_id") != template_id]
+        write_yaml_atomic(manifest_path, manifest_data)
+
+    return StandardResponse(success=True, message=f"模板 '{template_id}' 删除成功")
+
+
+@router.post(
+    "/template/{template_id}/expand",
+    response_model=TemplateExpandResponse,
+    summary="预览模板展开结果",
+    responses={
+        400: {"description": "请求参数错误或模板展开失败"},
+        404: {"description": "模板不存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def preview_template_expand(
+    template_id: str,
+    request: TemplateExpandRequest,
+    config_path: str = Depends(get_project_config_path),
+) -> TemplateExpandResponse:
+    """
+    @methoddesc 预览模板展开结果（不写入文件）
+
+    业务用途:
+    - 在前端"展开前预览"流程中调用
+    - 调用后端 expandV2Template 服务计算展开后的 transforms/constraints/regex_nodes，但不落盘
+
+    参数:
+        template_id: 模板唯一标识
+        request: 包含 instance_id 的请求
+        config_path: 项目配置路径
+
+    返回:
+        TemplateExpandResponse: 展开结果预览
+    """
+    tmpl_path = _find_template_path(template_id, config_path)
+    if not tmpl_path or not tmpl_path.exists():
+        raise HTTPException(status_code=404, detail=f"模板 '{template_id}' 不存在")
+
+    tmpl = load_template(tmpl_path)
+
+    logger.debug(f"模板展开请求: template_id={template_id}, instance_id={request.instance_id}")
+    try:
+        node_errors: list[dict[str, str]] = []
+        transforms, constraints, regex_nodes, manual_data_files = expand_template(
+            tmpl,
+            request.instance_id,
+            params=request.params,
+            input_from_node=request.input_from_node,
+            errors=node_errors,
+        )
+    except ValueError as e:
+        logger.warning(f"模板展开 ValueError: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return TemplateExpandResponse(
+        transforms=[t.model_dump(exclude_none=True) for t in transforms],
+        constraints=[c.model_dump(exclude_none=True) for c in constraints],
+        regex_nodes=[r.model_dump(exclude_none=True) for r in regex_nodes],
+        manual_data=[md.model_dump(exclude_none=True) for md in manual_data_files],
+        node_errors=node_errors,
+    )

app/api/routers/project/validation.py

@@ -0,0 +1,227 @@
+# 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
+
+功能概述:
+- 提供项目全量数据校验的 HTTP 入口
+- 委托核心逻辑给 ValidationExecutor，与 CLI 共享执行层
+- 响应构建下沉到 FullValidationResponseBuilder，保持路由层轻薄
+
+架构设计:
+- API 层负责请求校验、参数转换与执行器调用
+- ValidationExecutor 负责加载数据、执行格式检查与约束校验
+- FullValidationResponseBuilder 负责把执行结果转换为 FullValidationResponse
+"""
+
+import logging
+import os
+import time
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.api.dependencies import get_project_config_path
+from app.api.services.full_validation_response_builder import FullValidationResponseBuilder
+from app.shared.core.io.yaml import read_yaml
+from app.shared.core.project.manifest.coverage import compute_manifest_coverage, coverage_to_api_dict
+from app.shared.core.project.manifest.types import ProjectManifestV2
+from app.shared.services.validation.executor import ValidationExecutor
+
+from ...models import FullValidationRequest, FullValidationResponse
+from .base import _v2_manifest_path
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="", tags=["Project-Validation"])
+
+
+def _resolve_table_filter_from_file_path(config_path: str, file_path: str) -> str | list[str] | None:
+    """根据数据文件绝对路径反查所属 schema table id。
+
+    遍历 manifest 的 schemas，解析每个 schema 的 source.path（相对 config_path），
+    匹配到的 schema 的 id 作为校验过滤器。
+
+    Args:
+        config_path: 项目配置根目录
+        file_path: 数据文件绝对路径（已归一化）
+
+    Returns:
+        匹配的 table id（单个返回 str，多个返回 list），无匹配返回 None
+    """
+    norm_target = os.path.normpath(os.path.abspath(file_path))
+    manifest_path = _v2_manifest_path(config_path)
+    manifest_data = read_yaml(Path(manifest_path))
+    matched: list[str] = []
+    for schema_ref in manifest_data.get("schemas", []) or []:
+        schema_id = schema_ref.get("id")
+        schema_rel = schema_ref.get("path")
+        if not schema_id or not schema_rel:
+            continue
+        schema_abs = os.path.normpath(os.path.join(config_path, schema_rel))
+        try:
+            schema_data = read_yaml(Path(schema_abs))
+        except Exception:
+            continue
+        source = schema_data.get("source") or {}
+        src_path = source.get("path")
+        if not src_path:
+            continue
+        norm_src = os.path.normpath(os.path.abspath(os.path.join(config_path, src_path)))
+        if norm_src == norm_target:
+            matched.append(schema_id)
+    if not matched:
+        return None
+    return matched[0] if len(matched) == 1 else matched
+
+
+@router.post(
+    "/validate/full",
+    response_model=FullValidationResponse,
+    summary="执行项目全量数据校验",
+    responses={
+        400: {"description": "请求参数错误"},
+        404: {"description": "Manifest 不存在"},
+        422: {"description": "Manifest 损坏或无法解析"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def validate_v2_full(
+    request: FullValidationRequest,
+    config_path: str = Depends(get_project_config_path),
+) -> FullValidationResponse:
+    """
+    执行项目全量数据校验。
+
+    参数:
+        request: 校验请求，包含可选的配置覆盖
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        FullValidationResponse: 校验结果
+    """
+    started = time.monotonic()
+    logger.info(f"[validate_v2_full] 收到请求，config_path: {config_path}")
+    manifest_path = _v2_manifest_path(config_path)
+    logger.info(f"[validate_v2_full] manifest_path: {manifest_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 文件路径）
+            },
+        )
+
+    # 清单读取与校验必须先于 coverage 计算独立失败（422，与 GET /manifest 同口径）：
+    # 原实现把清单损坏吞进 coverage 的 try/except 继续执行，返回 summary 全零的
+    # 200 空成功，前端只看 summary 会把"清单损坏"误读为"校验通过零错误"。
+    try:
+        manifest_data = read_yaml(Path(manifest_path))
+        manifest_model = ProjectManifestV2.model_validate(manifest_data)
+    except Exception as e:
+        logger.error(f"[validate_v2_full] 项目清单损坏: {e}")
+        raise HTTPException(
+            status_code=422,
+            detail=f"项目清单文件损坏或为空，无法解析: {manifest_path}。请修复或回退 project.precis.yaml 后重试。（{e}）",
+        ) from e
+
+    coverage_payload = None
+    try:
+        coverage_payload = coverage_to_api_dict(compute_manifest_coverage(config_path, manifest_model))
+    except Exception as e:
+        logger.warning(f"[validate_v2_full] 计算 coverage 失败: {e}")
+
+    # 初始化执行器
+    try:
+        override_settings = None
+        if request.options and request.options.override_settings:
+            override_settings = request.options.override_settings
+        executor = ValidationExecutor(manifest_path, override_settings)
+    except Exception as e:
+        logger.error(f"[validate_v2_full] 初始化执行器失败: {e}")
+        return FullValidationResponseBuilder(
+            executor=None,
+            started=started,
+            coverage=coverage_payload,
+        ).build_error(e)
+
+    builder = FullValidationResponseBuilder(
+        executor=executor,
+        started=started,
+        coverage=coverage_payload,
+    )
+
+    # 确定数据目录
+    data_directory = config_path
+    if request.options and request.options.data_directory:
+        data_directory = request.options.data_directory
+
+    # 校验目标解析
+    table_filter = None
+    if request.target:
+        if request.target.type == "single_file":
+            file_path = (request.target.file_path or "").strip()
+            if not file_path:
+                raise HTTPException(status_code=400, detail="单文件校验缺少 file_path")
+            # 若传入相对路径，基于 config_path 解析为绝对路径
+            if not os.path.isabs(file_path):
+                file_path = os.path.normpath(os.path.join(config_path, file_path))
+            if not os.path.isfile(file_path):
+                raise HTTPException(status_code=404, detail=f"数据文件不存在: {file_path}")
+            table_filter = _resolve_table_filter_from_file_path(config_path, file_path)
+            if table_filter is None:
+                raise HTTPException(
+                    status_code=404,
+                    detail=f"未找到引用该文件的 schema: {file_path}",
+                )
+        if request.target.type == "single_table":
+            table_filter = (request.target.table_id or "").strip()
+            if not table_filter:
+                raise HTTPException(status_code=400, detail="单表校验缺少 table_id")
+
+    # 执行选项
+    validation_settings = executor.settings.validation
+    timeout_seconds = int(validation_settings.timeout_seconds or 0)
+    if timeout_seconds <= 0:
+        timeout_seconds = 30
+
+    from app.shared.services.validation.executor import ValidationOptions
+
+    options = ValidationOptions(
+        timeout_seconds=timeout_seconds,
+        error_handling=validation_settings.error_handling or "continue",
+        strict_mode=validation_settings.strict_mode or False,
+        table_filter=table_filter,
+        allow_unsafe_eval=request.options.allow_unsafe_eval if request.options else None,
+    )
+
+    logger.info(f"[validate_v2_full] 开始执行校验，数据目录: {data_directory}")
+
+    # 执行校验并构建响应
+    try:
+        result = executor.execute(data_directory, options)
+    except Exception as e:
+        logger.error(f"[validate_v2_full] 校验执行过程中发生异常: {e}", exc_info=True)
+        files_total = len(executor.dataset_schema.tables) if executor.dataset_schema else 0
+        return builder.build_error(e, files_total=files_total)
+
+    return builder.build_from_result(result)