precis-cli 0.1.3__py3-none-any.whl

app/api/routers/core/data_sources.py

@@ -0,0 +1,374 @@
+# 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 路由模块
+
+功能概述:
+- 提供工作区配置的读写接口（数据源列表、UI 偏好设置）
+- 管理数据源的增删改查操作
+- 支持 Electron 和 CLI/Web 两种使用模式
+
+架构设计:
+- 配置优先从新路径 .precis/data_sources.yaml 读取，兼容旧路径
+- 数据源使用 ExternalDataSource 模型 enriched 后返回
+- 通过环境变量 PRECIS_PROJECT_ROOT 确定项目根目录
+
+输入示例:
+    POST /workspace/data-sources
+    {"fileId": "data/users.xlsx", "name": "用户表", "type": "excel"}
+
+输出示例:
+    {
+        "version": "1.0.0",
+        "data_sources": [{"id": "...", "name": "用户表", "type": "excel", "status": "ready"}],
+        "ui_preferences": {"expanded_folders": {}, "startup_loading_enabled": true}
+    }
+"""
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.api.dependencies import get_project_config_path
+from app.api.models import ExternalDataSource, UIPreferences, WorkspaceConfig
+from app.api.services.io_error_messages import describe_io_error
+from app.shared.core.config import ConfigPaths
+from app.shared.core.io.yaml import write_yaml_atomic
+
+router = APIRouter(prefix="/api/latest/workspace", tags=["Data Sources"])
+
+
+def get_workspace_config_path(project_root: str) -> Path:
+    """获取工作区配置文件路径（优先新路径，兼容旧路径）"""
+    # 优先使用新路径
+    new_path = ConfigPaths.data_sources(project_root)
+    if new_path.exists():
+        return new_path
+
+    # 向后兼容：检查旧路径
+    old_path = Path(project_root) / ".precis-workspace.yaml"
+    if old_path.exists():
+        return old_path
+
+    # 默认返回新路径（用于创建）
+    return new_path
+
+
+def load_workspace_config(project_root: str) -> dict[str, Any]:
+    """加载工作区配置"""
+    config_path = get_workspace_config_path(project_root)
+
+    if not config_path.exists():
+        # 返回默认配置
+        return {
+            "data_sources": [],
+            "alias_mappings": {},
+            "ui_preferences": {},
+            "version": "1.0",
+            "last_updated": datetime.now().isoformat(),
+        }
+
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"加载数据源配置失败：{describe_io_error(e)}"
+        )
+
+
+def save_workspace_config(project_root: str, config: dict[str, Any]) -> None:
+    """保存工作区配置到文件"""
+    config_path = get_workspace_config_path(project_root)
+
+    try:
+        write_yaml_atomic(config_path, config)
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"保存数据源配置失败：{describe_io_error(e)}"
+        )
+
+
+def build_ui_preferences(config: dict[str, Any]) -> UIPreferences:
+    """构建 UI 偏好设置对象"""
+    raw = config.get("ui_preferences") or {}
+    expanded_folders: dict[str, bool] = {}
+    startup_loading_enabled = True
+
+    if isinstance(raw, dict):
+        startup_loading_enabled = raw.get("startup_loading_enabled", True)
+        expanded = raw.get("expanded_folders")
+        if isinstance(expanded, dict):
+            expanded_folders = {k: bool(v) for k, v in expanded.items()}
+        else:
+            expanded_folders = {k: bool(v) for k, v in raw.items() if isinstance(v, bool)}
+
+    return UIPreferences(expanded_folders=expanded_folders, startup_loading_enabled=bool(startup_loading_enabled))
+
+
+def _get_project_root(config_path: str) -> str:
+    """返回项目根目录。
+
+    B-sec3 加固后 X-Project-Config-Path Header 必须指向含 project.precis.yaml 的
+    项目根目录（见 dependencies._validate_project_root），因此 config_path 本身就是
+    项目根。此前此处误取 config_path 的 parent，导致 data_sources.yaml 被写到项目
+    父目录的 .precis/ 下——同一父目录下的多个项目会互相覆盖数据源配置。
+
+    参数:
+        config_path: 项目根目录的绝对路径（依赖注入校验后的值）
+
+    返回:
+        项目根目录（与 config_path 相同）
+    """
+    return config_path
+
+
+@router.get(
+    "/config",
+    response_model=WorkspaceConfig,
+    summary="获取工作区配置",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+async def get_workspace_config(config_path: str = Depends(get_project_config_path)) -> WorkspaceConfig:
+    """
+    获取工作区配置
+
+    适用于所有模式（Electron/CLI/Web）
+    """
+    project_root = _get_project_root(config_path)
+    config = load_workspace_config(project_root)
+
+    enriched_data_sources = []
+    for ds in config.get("data_sources", []):
+        enriched_ds = ExternalDataSource(
+            id=ds.get("id", ds.get("fileId", ds.get("fullPath", ""))),
+            name=ds.get("name", ""),
+            fileId=ds.get("fileId", ds.get("fullPath", "")),
+            type=ds.get("type", "excel"),
+            status=ds.get("status", "ready"),
+            addedAt=ds.get("addedAt", "2024-01-01T00:00:00Z"),
+            lastUsed=ds.get("lastUsed", "2024-01-01T00:00:00Z"),
+            alias=ds.get("alias", ""),
+            error=ds.get("error", ""),
+            size=ds.get("size"),
+            sourceMode=ds.get("sourceMode"),
+            localPath=ds.get("localPath"),
+            folderPath=ds.get("folderPath"),
+        )
+        enriched_data_sources.append(enriched_ds)
+
+    return WorkspaceConfig(
+        version=config.get("version", "1.0.0"),
+        data_sources=enriched_data_sources,
+        alias_mappings=config.get("alias_mappings", {}),
+        ui_preferences=build_ui_preferences(config),
+        last_updated=config.get("last_updated", "2024-01-01T00:00:00Z"),
+    )
+
+
+@router.put(
+    "/config",
+    response_model=WorkspaceConfig,
+    summary="更新工作区配置",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+async def update_workspace_config(
+    config_data: dict[str, Any], config_path: str = Depends(get_project_config_path)
+) -> WorkspaceConfig:
+    """
+    更新工作区配置
+
+    适用于所有模式（Electron/CLI/Web）
+    """
+    project_root = _get_project_root(config_path)
+
+    # 更新最后修改时间
+    config_data["last_updated"] = datetime.now().isoformat()
+
+    # 保存到文件
+    save_workspace_config(project_root, config_data)
+
+    # 返回更新后的配置
+    return await get_workspace_config(config_path)
+
+
+@router.post(
+    "/data-sources",
+    response_model=WorkspaceConfig,
+    summary="添加数据源",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+async def add_data_source(
+    data_source: dict[str, Any], config_path: str = Depends(get_project_config_path)
+) -> WorkspaceConfig:
+    """
+    添加数据源
+
+    适用于所有模式（Electron/CLI/Web）
+    """
+    project_root = _get_project_root(config_path)
+    config = load_workspace_config(project_root)
+
+    file_id = data_source.get("fileId", data_source.get("fullPath"))
+    # 仅在路径为绝对路径时执行 normpath；在 Windows 上 normpath("/a") 会变成 "\a"
+    # （去掉前导斜杠、视作相对路径），导致不同 fileId 在比较时塌缩为同一字符串。
+    if file_id and os.path.isabs(file_id):
+        file_id = os.path.normpath(file_id)
+
+    # 检查是否已存在
+    # 注意：fullPath 比较必须排除 None == None 的情况——否则当 payload 与已有项都缺
+    # 少 fullPath 字段时，条件会误判为重复，导致不同 fileId 的新数据源被错误地覆盖。
+    new_full_path = data_source.get("fullPath")
+    for ds in config.get("data_sources", []):
+        if ds.get("fileId") == file_id or (new_full_path and ds.get("fullPath") == new_full_path):
+            # 更新现有数据源
+            ds["name"] = data_source.get("name", ds.get("name", ""))
+            ds["type"] = data_source.get("type", ds.get("type", "excel"))
+            ds["status"] = data_source.get("status", "ready")
+            ds["lastUsed"] = data_source.get("lastUsed", datetime.now().isoformat())
+            if "sourceMode" in data_source:
+                ds["sourceMode"] = data_source.get("sourceMode")
+            if "localPath" in data_source:
+                ds["localPath"] = data_source.get("localPath")
+            if "folderPath" in data_source:
+                ds["folderPath"] = data_source.get("folderPath")
+            if "size" in data_source:
+                ds["size"] = data_source.get("size")
+            if "id" not in ds:
+                ds["id"] = data_source.get("id", file_id)
+
+            save_workspace_config(project_root, config)
+            return await get_workspace_config(config_path)
+
+    # 添加新数据源
+    new_source = {
+        "id": data_source.get("id", file_id),
+        "name": data_source.get("name", ""),
+        "fileId": file_id,
+        "type": data_source.get("type", "excel"),
+        "status": data_source.get("status", "ready"),
+        "addedAt": data_source.get("addedAt", datetime.now().isoformat()),
+        "lastUsed": data_source.get("lastUsed", datetime.now().isoformat()),
+        "alias": data_source.get("alias", ""),
+        "error": data_source.get("error", ""),
+        "sourceMode": data_source.get("sourceMode"),
+        "localPath": data_source.get("localPath"),
+        "folderPath": data_source.get("folderPath"),
+        "size": data_source.get("size"),
+    }
+
+    config.setdefault("data_sources", []).insert(0, new_source)
+    save_workspace_config(project_root, config)
+
+    return await get_workspace_config(config_path)
+
+
+@router.delete(
+    "/data-sources/{source_id}",
+    response_model=WorkspaceConfig,
+    summary="移除数据源",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+async def remove_data_source(source_id: str, config_path: str = Depends(get_project_config_path)) -> WorkspaceConfig:
+    """
+    移除数据源
+
+    适用于所有模式（Electron/CLI/Web）
+    """
+    project_root = _get_project_root(config_path)
+    config = load_workspace_config(project_root)
+
+    data_sources = config.get("data_sources", [])
+    config["data_sources"] = [ds for ds in data_sources if ds.get("id") != source_id]
+
+    save_workspace_config(project_root, config)
+    return await get_workspace_config(config_path)
+
+
+@router.put(
+    "/data-sources/{source_id}",
+    response_model=WorkspaceConfig,
+    summary="更新数据源",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+async def update_data_source(
+    source_id: str, data_source: dict[str, Any], config_path: str = Depends(get_project_config_path)
+) -> WorkspaceConfig:
+    """
+    @methoddesc 更新数据源
+
+    业务用途:
+    - 在工作区配置中按 id 查找数据源并就地合并更新
+    - 同步刷新 lastUsed 字段以反映最近访问时间
+    - 适用于所有运行模式（Electron/CLI/Web）
+
+    参数:
+        source_id: 数据源唯一标识
+        data_source: 包含待更新字段的字典
+        config_path: 项目配置路径（由依赖注入提供）
+
+    返回:
+        更新后的 WorkspaceConfig 完整配置
+    """
+    project_root = _get_project_root(config_path)
+    config = load_workspace_config(project_root)
+
+    for ds in config.get("data_sources", []):
+        if ds.get("id") == source_id:
+            ds.update(data_source)
+            ds["lastUsed"] = datetime.now().isoformat()
+            break
+
+    save_workspace_config(project_root, config)
+    return await get_workspace_config(config_path)
+
+
+@router.delete(
+    "/data-sources",
+    response_model=WorkspaceConfig,
+    summary="清空所有数据源",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+async def clear_all_data_sources(config_path: str = Depends(get_project_config_path)) -> WorkspaceConfig:
+    """
+    清空所有数据源
+
+    适用于所有模式（Electron/CLI/Web）
+    """
+    project_root = _get_project_root(config_path)
+    config = load_workspace_config(project_root)
+
+    config["data_sources"] = []
+    config["last_updated"] = datetime.now().isoformat()
+
+    save_workspace_config(project_root, config)
+    return await get_workspace_config(config_path)

app/api/routers/core/regex.py

@@ -0,0 +1,333 @@
+# 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 路由模块
+
+功能概述:
+- 将可视化模式片段解析为可执行的正则表达式
+- 执行正则表达式测试并返回匹配结果和命名组
+- 批量验证数据并提取命名组结果（用于前端正则节点预览）
+
+架构设计:
+- 模式解析：支持 static 和 param 两种片段类型，映射为对应正则
+- 正则验证：使用 Python re 模块编译和执行匹配
+- 提取模式：支持 full/partial/extract 三种匹配模式
+
+输入示例:
+    POST /utils/parse-pattern
+    {"parts": [{"type": "static", "text": "ID_"}, {"type": "param", "name": "id", "param_type": "int"}]}
+
+输出示例:
+    {"regex": "ID_(?P<id>\\d+)", "params": {"id": "int"}}
+"""
+
+import re
+from typing import Any, Literal
+
+from fastapi import APIRouter
+from pydantic import BaseModel, Field
+
+router = APIRouter(prefix="/api/latest/utils", tags=["Utilities"])
+
+
+class PatternPart(BaseModel):
+    """正则模式片段模型
+
+    用于描述正则表达式的组成部分，每个片段可以是固定文本（static）
+    或参数占位符（param）。
+
+    字段说明:
+        type: 片段类型，"static" 表示固定文本，"param" 表示参数占位符
+        text: 固定文本内容（仅 static 类型使用）
+        name: 参数名称（仅 param 类型使用，用于生成命名捕获组）
+        param_type: 参数数据类型（仅 param 类型使用，决定正则片段）
+    """
+
+    type: Literal["static", "param"]
+    text: str | None = None
+    name: str | None = None
+    param_type: str | None = None
+
+
+class ParsePatternRequest(BaseModel):
+    """解析模式请求模型
+
+    接收前端传来的模式片段列表，将其组合成完整的正则表达式。
+
+    字段说明:
+        parts: 模式片段列表，按顺序组合
+    """
+
+    parts: list[PatternPart]
+
+
+class ParsePatternResponse(BaseModel):
+    """解析模式响应模型
+
+    返回组合后的正则表达式和提取的参数信息。
+
+    字段说明:
+        regex: 组合后的完整正则表达式字符串
+        params: 参数名称到参数类型的映射字典
+    """
+
+    regex: str
+    params: dict[str, str]
+
+
+# 参数类型到正则片段的映射表
+# 根据参数类型选择对应的正则表达式片段
+PARAM_TYPE_REGEX_MAP = {
+    "int": r"\d+",  # 整数：一个或多个数字
+    "float": r"-?\d+(?:\.\d+)?",  # 浮点数：可选负号 + 数字 + 可选的小数部分
+    "str": r"\w+",  # 字符串：一个或多个单词字符
+    "word": r"\w+",  # 单词：与 str 相同
+    "non_space": r"\S+",  # 非空白字符：一个或多个非空白字符
+    "anything": r".+",  # 任意字符：一个或多个任意字符
+}
+
+
+@router.post(
+    "/parse-pattern",
+    response_model=ParsePatternResponse,
+    summary="将可视化模式片段解析为正则表达式",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def parse_pattern_to_regex(request: ParsePatternRequest) -> dict[str, Any]:
+    """将可视化模式片段解析为正则表达式
+
+    遍历请求中的每个片段：
+    - static 类型：转义文本中的特殊正则字符后直接拼接
+    - param 类型：根据 param_type 查找对应的正则片段，包装为命名捕获组 (?P<name>...)
+
+    Args:
+        request: 包含模式片段列表的请求对象
+
+    Returns:
+        包含组合后的正则表达式和参数信息的响应对象
+    """
+    regex_parts = []
+    params = {}
+    for part in request.parts:
+        if part.type == "static" and part.text:
+            # 对固定文本进行正则转义，防止特殊字符干扰正则语义
+            regex_parts.append(re.escape(part.text))
+        elif part.type == "param" and part.name and part.param_type:
+            # 根据参数类型获取对应的正则片段，默认为 \w+
+            regex_fragment = PARAM_TYPE_REGEX_MAP.get(part.param_type, r"\w+")
+            # 构建命名捕获组，如 (?P<id>\d+)
+            regex_parts.append(f"(?P<{part.name}>{regex_fragment})")
+            params[part.name] = part.param_type
+
+    final_regex = "".join(regex_parts)
+    return {"regex": final_regex, "params": params}
+
+
+class TestRegexRequest(BaseModel):
+    """正则测试请求模型
+
+    字段说明:
+        regex: 待测试的正则表达式字符串
+        test_string: 用于匹配测试的文本
+    """
+
+    regex: str
+    test_string: str
+
+
+class TestRegexResponse(BaseModel):
+    """正则测试响应模型
+
+    字段说明:
+        is_match: 是否匹配成功
+        groups: 捕获组结果字典（仅匹配成功时有值）
+        error: 错误信息（正则无效时返回）
+    """
+
+    is_match: bool
+    groups: dict[str, str] = Field(default_factory=dict)
+    error: str | None = None
+
+
+@router.post(
+    "/test-regex",
+    response_model=TestRegexResponse,
+    summary="测试正则表达式匹配",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def test_regex_matching(request: TestRegexRequest) -> dict[str, Any]:
+    """测试正则表达式匹配
+
+    编译用户提供的正则表达式，并在测试字符串中搜索匹配。
+    返回是否匹配以及所有命名捕获组的内容。
+
+    Args:
+        request: 包含正则表达式和测试字符串的请求对象
+
+    Returns:
+        包含匹配结果、捕获组和错误信息的响应对象
+    """
+    if not request.regex:
+        return {"is_match": False, "error": "正则表达式不能为空。"}
+    try:
+        # 编译正则表达式，如果格式错误会抛出 re.error
+        compiled_regex = re.compile(request.regex)
+        # 在测试字符串中搜索匹配（search 模式，不要求完全匹配）
+        match = compiled_regex.search(request.test_string)
+        if match:
+            return {"is_match": True, "groups": match.groupdict()}
+        else:
+            return {"is_match": False, "groups": {}}
+    except re.error as e:
+        return {"is_match": False, "error": f"无效的正则表达式: {e}"}
+
+
+class RegexValidateExtractRequest(BaseModel):
+    """批量正则验证与提取请求模型
+
+    对一批数据值执行正则匹配，并提取命名捕获组的结果。
+
+    字段说明:
+        regex_pattern: 正则表达式模式（必填）
+        regex_flags: 正则标志字符串，如 "i" 表示忽略大小写
+        case_sensitive: 是否区分大小写（默认 True）
+        match_mode: 匹配模式，"full" 完全匹配，"partial" 部分匹配，"extract" 提取
+        values: 待验证的数据值列表
+    """
+
+    regex_pattern: str = Field(min_length=1)
+    regex_flags: str = ""
+    case_sensitive: bool = True
+    match_mode: Literal["full", "partial", "extract"] = "full"
+    values: list[str] = Field(default_factory=list)
+
+
+class RegexValidateExtractData(BaseModel):
+    """批量正则验证与提取的结果数据模型
+
+    字段说明:
+        total_rows: 总数据行数
+        match_count: 匹配成功的数量
+        error_count: 匹配失败的数量
+        group_names: 命名捕获组名称列表
+        extracted_columns: 按组名组织的提取结果字典
+    """
+
+    total_rows: int
+    match_count: int
+    error_count: int
+    group_names: list[str] = Field(default_factory=list)
+    extracted_columns: dict[str, list[str]] = Field(default_factory=dict)
+
+
+class RegexValidateExtractResponse(BaseModel):
+    """批量正则验证与提取响应模型
+
+    字段说明:
+        success: 操作是否成功
+        data: 验证和提取的详细结果
+        error: 错误信息（失败时返回）
+    """
+
+    success: bool
+    data: RegexValidateExtractData | None = None
+    error: str | None = None
+
+
+@router.post(
+    "/regex/validate-extract",
+    response_model=RegexValidateExtractResponse,
+    summary="批量验证数据并提取正则命名组",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def validate_and_extract_regex(request: RegexValidateExtractRequest) -> dict[str, Any]:
+    """批量验证数据并提取正则命名组
+
+    对输入的一批数据值执行正则匹配：
+    - 根据 regex_flags 和 case_sensitive 设置编译标志
+    - 根据 match_mode 选择 match（完全匹配）或 search（部分匹配）
+    - 对每条数据执行匹配，统计成功/失败数量
+    - 提取所有命名捕获组的结果，按列组织
+
+    Args:
+        request: 包含正则模式、匹配模式和数据值的请求对象
+
+    Returns:
+        包含匹配统计和提取结果的响应对象
+    """
+    try:
+        # 初始化正则编译标志
+        flags = 0
+        if "i" in request.regex_flags.lower():
+            flags |= re.IGNORECASE  # 忽略大小写
+        if "m" in request.regex_flags.lower():
+            flags |= re.MULTILINE  # 多行模式
+        if "s" in request.regex_flags.lower():
+            flags |= re.DOTALL  # 点号匹配换行符
+        if not request.case_sensitive:
+            flags |= re.IGNORECASE  # 不区分大小写覆盖
+
+        # 编译正则表达式
+        compiled = re.compile(request.regex_pattern, flags)
+        # 获取所有命名捕获组的名称
+        group_names = list(compiled.groupindex.keys())
+        # 初始化提取结果字典，每个组名对应一个空列表
+        extracted_columns: dict[str, list[str]] = {name: [] for name in group_names}
+
+        match_count = 0
+        error_count = 0
+
+        # 遍历每条数据值进行匹配
+        for value in request.values:
+            value_str = "" if value is None else str(value)
+            if request.match_mode == "full":
+                # 完全匹配：从字符串开头开始匹配
+                match = compiled.match(value_str)
+            else:
+                # 部分匹配：在字符串中搜索匹配
+                match = compiled.search(value_str)
+
+            if match:
+                match_count += 1
+                groups = match.groupdict()
+                for name in group_names:
+                    extracted_columns[name].append("" if groups.get(name) is None else str(groups.get(name)))
+            else:
+                error_count += 1
+                # 未匹配时，该行的所有提取列填入空字符串
+                for name in group_names:
+                    extracted_columns[name].append("")
+
+        return {
+            "success": True,
+            "data": {
+                "total_rows": len(request.values),
+                "match_count": match_count,
+                "error_count": error_count,
+                "group_names": group_names,
+                "extracted_columns": extracted_columns,
+            },
+        }
+    except re.error as e:
+        return {"success": False, "error": f"无效的正则表达式: {e}"}
+    except Exception as e:
+        return {"success": False, "error": str(e)}