precis-cli 0.1.3__py3-none-any.whl

app/api/routers/project/models.py

@@ -0,0 +1,177 @@
+# 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 模型定义模块
+
+功能概述:
+- 定义 V2 项目视图模型（画布节点坐标和视口）
+- 定义 V2 全量配置请求/响应模型
+- 定义工作区条目和工作区列表模型
+- 提供标准响应模型
+
+架构设计:
+- 视图模型与校验语义配置解耦，避免 UI 信息污染业务配置
+- 全量配置模型用于前端导出、AI 生成、备份恢复场景
+- 工作区模型支持多标签页画布的状态持久化
+
+输入示例:
+    class ProjectViewV2Model(BaseModel):
+        version: int = 1
+        nodes: dict[str, dict[str, float]]  # node_id -> {x, y}
+        viewport: Optional[dict[str, float]]  # {x, y, zoom}
+
+输出示例:
+    class FullConfigV2Request(BaseModel):
+        manifest: ProjectManifestV2
+        schemas: dict[str, TableSchemaFileV2]
+        constraints: dict[str, ConstraintFileV2]
+        regex_nodes: dict[str, RegexNodeFileV2]
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+from app.shared.core.project.constraint.types import ConstraintFileV2
+from app.shared.core.project.manifest.types import (
+    ProjectManifestV2,
+)
+from app.shared.core.project.manual_data.types import ManualDataFileV2
+from app.shared.core.project.regex.types import RegexNodeFileV2
+from app.shared.core.project.schema.types import TableSchemaFileV2
+from app.shared.core.project.transform.types import TransformFileV2
+
+
+class ProjectViewV2Model(BaseModel):
+    """
+    V2 项目视图文件模型（前端画布布局）。
+
+    设计目标：
+    - 将画布布局（节点坐标/视口）与后端校验语义配置解耦
+    - 避免把 UI 相关信息写入 project.precis.yaml / schema / constraint / regex 文件
+
+    数据流：
+    - 前端保存画布视图时调用 PUT /project/view
+    - 前端加载项目时调用 GET /project/view 获取节点位置
+
+    字段说明：
+    - version: 视图文件版本，用于后续格式迁移
+    - nodes: 节点ID到坐标的映射，用于恢复画布布局
+    - viewport: 当前视口信息，用于恢复用户查看位置
+    """
+
+    version: int = Field(default=1, description="视图文件版本")
+    nodes: dict[str, dict[str, float]] = Field(default_factory=dict, description="节点坐标：node_id -> {x,y}")
+    viewport: dict[str, float] | None = Field(default=None, description="视口信息：{x,y,zoom}")
+
+
+class FullConfigV2Request(BaseModel):
+    """
+    V2 全量配置写入请求模型。
+
+    使用场景：
+    - 前端导出整个项目配置时使用
+    - AI 生成完整项目配置时使用
+    - 项目备份/恢复场景
+
+    数据完整性保证：
+    - manifest: 必填，作为所有资源的索引
+    - schemas/constraints/regex_nodes: 可选，用于批量更新资源文件
+    """
+
+    manifest: ProjectManifestV2 = Field(..., description="项目清单")
+    schemas: dict[str, TableSchemaFileV2] = Field(default_factory=dict, description="schemas 映射：table_id -> schema")
+    constraints: dict[str, ConstraintFileV2] = Field(
+        default_factory=dict, description="constraints 映射：constraint_id -> constraint"
+    )
+    regex_nodes: dict[str, RegexNodeFileV2] = Field(
+        default_factory=dict, description="regex_nodes 映射：regex_id -> regex_node"
+    )
+    transforms: dict[str, TransformFileV2] = Field(
+        default_factory=dict, description="transforms 映射：transform_id -> transform"
+    )
+    manual_data: dict[str, ManualDataFileV2] = Field(
+        default_factory=dict, description="manual_data 映射：manual_data_id -> manual_data"
+    )
+
+
+class DisplayNameUpdateRequest(BaseModel):
+    """
+    更新资源展示名的请求体模型。
+
+    设计意图：
+    - 允许用户修改资源的显示名称而不改变资源 ID 或文件路径
+    - 用于提升用户体验，如给 "customer_table" 改为 "客户信息表"
+
+    约束：
+    - name 不能为空或纯空白（field_validator 拒绝，返回 422）
+    """
+
+    name: str = Field(..., description="新的展示名称")
+
+    @field_validator("name")
+    @classmethod
+    def _reject_blank(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("展示名称不能为空或纯空白")
+        return v
+
+
+class WorkspaceV2Item(BaseModel):
+    """
+    V2 工作区条目模型。
+
+    设计目标：
+    - 存储单个工作区的元数据、视图状态和完整画布快照
+    - nodes/edges 保存完整画布数据，切换/关闭工作区时立即持久化
+    - 重新打开项目时从 workspaces.json 恢复所有工作区的画布状态
+
+    字段说明：
+    - id: 工作区唯一标识
+    - title: 工作区显示名称
+    - index: 排序索引（删除后不重新编号，新建时取 max+1）
+    - createdAt/lastActiveAt: 时间戳
+    - visibleNodeIds: 在该工作区中可见的节点 ID 列表
+    - viewport: 画布视口状态（位置+缩放）
+    - nodes: 画布节点完整数据（JSON 数组）
+    - edges: 画布边完整数据（JSON 数组）
+    """
+
+    id: str = Field(..., description="工作区唯一标识")
+    title: str = Field(..., description="工作区显示名称")
+    index: int = Field(default=0, description="排序索引")
+    createdAt: str = Field(default="", description="创建时间 ISO 字符串")
+    lastActiveAt: str = Field(default="", description="最后活跃时间 ISO 字符串")
+    visibleNodeIds: list[str] = Field(default_factory=list, description="可见节点 ID 列表")
+    viewport: dict[str, float] | None = Field(default=None, description="视口信息：{x,y,zoom}")
+    nodes: list[dict] = Field(default_factory=list, description="画布节点完整数据")
+    edges: list[dict] = Field(default_factory=list, description="画布边完整数据")
+
+
+class WorkspacesV2Model(BaseModel):
+    """
+    V2 工作区配置文件模型。
+
+    使用场景：
+    - 前端多标签页画布的工作区持久化
+    - 每个工作区保存完整画布快照（nodes/edges），实现跨会话恢复
+
+    数据流：
+    - 前端切换/关闭工作区时调用 PUT /project/workspaces 保存
+    - 前端加载项目时调用 GET /project/workspaces 恢复所有工作区画布状态
+    """
+
+    version: int = Field(default=1, description="工作区文件版本")
+    activeWorkspaceId: str | None = Field(default=None, description="当前活跃工作区 ID")
+    workspaces: list[WorkspaceV2Item] = Field(default_factory=list, description="工作区列表")

app/api/routers/project/pattern.py

@@ -0,0 +1,268 @@
+# 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 Pattern CRUD API - 正则表达式模式管理
+
+功能概述:
+- 提供 Pattern（可复用正则表达式单元）的创建与存在性检查
+- Pattern 存储在项目的 patterns/ 目录下
+- 支持命名冲突处理（覆盖、建议新名称、取消）
+
+架构设计:
+- 依赖 get_v2_manifest 获取 patterns_dir 配置
+- 使用 PatternFile 模型序列化为 YAML 文件
+- 创建请求使用 CreatePatternRequest，响应使用 CreatePatternResponse
+
+输入示例:
+    POST /pattern (body: CreatePatternRequest)
+    GET /pattern/phone_cn/exists
+
+输出示例:
+    CreatePatternResponse: {message, pattern_path, pattern_name}
+    dict: {pattern_name, exists}
+"""
+
+import logging
+import os
+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.shared.core.io.yaml import read_yaml
+from app.shared.core.patterns.writer import (
+    PatternFile,
+    check_pattern_exists,
+    delete_pattern_file,
+    generate_unique_pattern_name,
+    save_pattern_file,
+)
+
+from .manifest import get_v2_manifest
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="", tags=["Project-Pattern"])
+
+
+class CreatePatternRequest(BaseModel):
+    """创建 Pattern 的请求体。"""
+
+    name: str = Field(..., description="Pattern 名称")
+    regex: str = Field(..., description="正则表达式")
+    description: str | None = Field(None, description="描述信息")
+    output: dict | None = Field(None, description="输出配置")
+    overwrite: bool = Field(False, description="是否覆盖已存在的 Pattern")
+
+
+class CreatePatternResponse(BaseModel):
+    """创建 Pattern 的响应体。"""
+
+    message: str
+    pattern_path: str
+    pattern_name: str
+
+
+@router.post(
+    "/pattern",
+    response_model=CreatePatternResponse,
+    summary="创建新的 Pattern 文件",
+    responses={
+        409: {"description": "Pattern 已存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def create_v2_pattern(
+    payload: CreatePatternRequest,
+    config_path: str = Depends(get_project_config_path),
+) -> CreatePatternResponse:
+    """
+    创建新的 Pattern 文件。
+
+    业务逻辑：
+    - 在项目的 patterns/ 目录下创建 Pattern YAML 文件
+    - 支持命名冲突处理（覆盖/重命名/报错）
+
+    参数:
+        payload: 创建 Pattern 的请求数据
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        CreatePatternResponse: 创建结果
+    """
+    manifest = get_v2_manifest(config_path)
+    patterns_dir = os.path.join(config_path, manifest.patterns_dir or "patterns")
+
+    pattern_exists = check_pattern_exists(patterns_dir, payload.name)
+
+    if pattern_exists and not payload.overwrite:
+        suggested_name = generate_unique_pattern_name(patterns_dir, payload.name)
+        raise HTTPException(
+            status_code=409,
+            detail={
+                "error": "pattern_exists",
+                "message": f"Pattern '{payload.name}' 已存在",
+                "suggested_name": suggested_name,
+                "options": ["overwrite", "use_suggested_name", "cancel"],
+            },
+        )
+
+    if payload.overwrite and pattern_exists:
+        logger.info(f"[Pattern API] 覆盖已存在的 Pattern: {payload.name}")
+
+    pattern_file = PatternFile(
+        name=payload.name,
+        regex=payload.regex,
+        description=payload.description,
+        output=payload.output,
+    )
+
+    filepath = save_pattern_file(pattern_file, patterns_dir)
+    logger.info(f"[Pattern API] Pattern 已创建: {filepath}")
+
+    return CreatePatternResponse(
+        message=f"Pattern '{payload.name}' 已创建",
+        pattern_path=filepath,
+        pattern_name=payload.name,
+    )
+
+
+@router.get(
+    "/pattern/{pattern_name}/exists",
+    response_model=dict,
+    summary="检查 Pattern 名称是否已存在",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def check_pattern_name_exists(
+    pattern_name: str,
+    config_path: str = Depends(get_project_config_path),
+) -> dict[str, Any]:
+    """
+    检查指定名称的 Pattern 是否已存在。
+
+    参数:
+        pattern_name: Pattern 名称
+        config_path: 项目配置根目录
+
+    返回:
+        包含是否存在信息的字典
+    """
+    manifest = get_v2_manifest(config_path)
+    patterns_dir = os.path.join(config_path, manifest.patterns_dir or "patterns")
+
+    exists = check_pattern_exists(patterns_dir, pattern_name)
+
+    return {
+        "pattern_name": pattern_name,
+        "exists": exists,
+    }
+
+
+@router.get(
+    "/pattern",
+    response_model=list[dict],
+    summary="列出所有 Pattern 规则",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def list_v2_patterns(
+    config_path: str = Depends(get_project_config_path),
+) -> list[dict[str, Any]]:
+    """列出项目 patterns/ 目录下的所有 Pattern。"""
+    manifest = get_v2_manifest(config_path)
+    patterns_dir = os.path.join(config_path, manifest.patterns_dir or "patterns")
+    result: list[dict[str, Any]] = []
+    if not os.path.isdir(patterns_dir):
+        return result
+    for fname in sorted(os.listdir(patterns_dir)):
+        if not (fname.endswith(".yaml") or fname.endswith(".yml")):
+            continue
+        fpath = os.path.join(patterns_dir, fname)
+        try:
+            data = read_yaml(Path(fpath))
+            if isinstance(data, dict) and data.get("name"):
+                result.append(data)
+        except Exception as e:
+            logger.warning(f"[Pattern API] 读取 pattern 文件失败: {fpath}, {e}")
+    return result
+
+
+@router.put(
+    "/pattern/{pattern_name}",
+    response_model=CreatePatternResponse,
+    summary="更新已存在的 Pattern",
+    responses={
+        404: {"description": "Pattern 不存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def update_v2_pattern(
+    pattern_name: str,
+    payload: CreatePatternRequest,
+    config_path: str = Depends(get_project_config_path),
+) -> CreatePatternResponse:
+    """更新已存在的 Pattern 文件（覆盖写）。"""
+    manifest = get_v2_manifest(config_path)
+    patterns_dir = os.path.join(config_path, manifest.patterns_dir or "patterns")
+
+    if not check_pattern_exists(patterns_dir, pattern_name):
+        raise HTTPException(status_code=404, detail=f"Pattern '{pattern_name}' 不存在")
+
+    # 以路径中的名称为准（payload.name 应与 pattern_name 一致）
+    pattern_file = PatternFile(
+        name=pattern_name,
+        regex=payload.regex,
+        description=payload.description,
+        output=payload.output,
+    )
+    filepath = save_pattern_file(pattern_file, patterns_dir)
+    logger.info(f"[Pattern API] Pattern 已更新: {filepath}")
+
+    return CreatePatternResponse(
+        message=f"Pattern '{pattern_name}' 已更新",
+        pattern_path=filepath,
+        pattern_name=pattern_name,
+    )
+
+
+@router.delete(
+    "/pattern/{pattern_name}",
+    response_model=dict,
+    summary="删除 Pattern",
+    responses={
+        404: {"description": "Pattern 不存在"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def delete_v2_pattern(
+    pattern_name: str,
+    config_path: str = Depends(get_project_config_path),
+) -> dict[str, Any]:
+    """删除指定 Pattern 文件。"""
+    manifest = get_v2_manifest(config_path)
+    patterns_dir = os.path.join(config_path, manifest.patterns_dir or "patterns")
+
+    deleted = delete_pattern_file(patterns_dir, pattern_name)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Pattern '{pattern_name}' 不存在")
+
+    logger.info(f"[Pattern API] Pattern 已删除: {pattern_name}")
+    return {"pattern_name": pattern_name, "deleted": True}