precis-cli 0.1.3__py3-none-any.whl

app/api/middleware/exception_handler.py

@@ -0,0 +1,126 @@
+# 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 请求处理过程中的未处理异常
+- 将异常转换为统一的 JSON 错误响应
+- 避免异常信息泄露，返回安全的内部服务器错误提示
+
+架构设计:
+- 继承 Starlette BaseHTTPMiddleware
+- 通过 dispatch 方法包装请求处理流程
+- 对 HTTPException 直接抛出，其他异常统一捕获并记录日志
+
+输入示例:
+    正常的 HTTP 请求进入中间件处理流程
+
+输出示例:
+    当发生未处理异常时返回:
+    {"error": "Internal Server Error", "detail": "An unexpected error occurred"}
+"""
+
+import logging
+import traceback
+from collections.abc import Awaitable, Callable
+
+from fastapi import HTTPException
+from fastapi.exceptions import RequestValidationError
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from app.shared.core.pydantic_messages import localize_pydantic_msg
+
+logger = logging.getLogger(__name__)
+
+
+async def request_validation_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """422 请求校验错误的全局 handler。
+
+    保持 FastAPI 默认的响应结构（detail 为 loc/msg/type 数组，前端按此解析），
+    仅把每条 msg 本地化为中文——否则 Pydantic 的英文校验消息
+    （"Input should be a valid integer" 等）会经前端原样展示给用户。
+
+    签名收窄说明：Starlette 的 add_exception_handler 要求
+    Callable[[Request, Exception], ...]（参数逆变），用具体异常类型作
+    参数注解会挂 mypy 全量检查，故收宽为 Exception 后 isinstance 收窄。
+
+    Args:
+        request: 当前请求
+        exc: FastAPI 请求体/参数校验错误
+
+    Returns:
+        422 JSONResponse，结构与 FastAPI 默认一致
+
+    Raises:
+        exc: 非 RequestValidationError 时原样上抛（注册绑定保证了不会走到）
+    """
+    if not isinstance(exc, RequestValidationError):
+        raise exc
+    errors = []
+    for err in exc.errors():
+        item = dict(err)
+        item["msg"] = localize_pydantic_msg(str(item.get("msg", "")))
+        errors.append(item)
+    return JSONResponse(status_code=422, content={"detail": errors})
+
+
+class ExceptionHandlerMiddleware(BaseHTTPMiddleware):
+    """
+    全局异常处理中间件
+
+    继承自 Starlette 的 BaseHTTPMiddleware，通过包装请求处理流程，
+    捕获所有未处理的异常并转换为统一的 JSON 错误响应。
+
+    处理策略:
+        - HTTPException: 直接向上抛出，由 FastAPI 的默认异常处理器处理
+        - 其他 Exception: 记录完整堆栈日志，返回安全的 500 错误响应（避免泄露敏感信息）
+
+    Attributes:
+        无额外属性，依赖父类 BaseHTTPMiddleware 的基础设施
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> Response:
+        """
+        分发并包装请求处理流程，捕获未处理异常
+
+        Args:
+            request: 当前 HTTP 请求对象，包含方法、路径、头信息等
+            call_next: 下一个中间件或路由处理器的可调用对象
+
+        Returns:
+            Response: 正常响应或异常时的 JSONResponse（500 状态码）
+
+        Raises:
+            HTTPException: FastAPI 的 HTTP 异常直接向上抛出，不做拦截
+        """
+        try:
+            # 调用下游中间件或路由处理器，获取正常响应
+            response = await call_next(request)
+            return response
+        except HTTPException:
+            # FastAPI 的 HTTPException 直接抛出，由上层默认处理器生成标准 HTTP 错误响应
+            raise
+        except Exception:
+            # 捕获所有未预料的异常，记录完整堆栈以便排查问题
+            logger.error(f"Unhandled exception: {traceback.format_exc()}")
+            # 返回安全的通用错误响应，避免将内部异常详情暴露给客户端
+            return JSONResponse(
+                status_code=500,
+                content={"error": "Internal Server Error", "detail": "服务器内部错误，请稍后重试"},
+            )

app/api/middleware/request_logging.py

@@ -0,0 +1,97 @@
+# 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 请求的访问日志
+- 计算并输出请求处理耗时
+- 根据响应状态码分级输出日志（info/warning/error）
+
+架构设计:
+- 继承 Starlette BaseHTTPMiddleware
+- 在请求前后记录时间戳计算耗时
+- 使用 Python logging 模块分级输出
+
+输入示例:
+    正常的 HTTP 请求进入中间件处理流程
+
+输出示例:
+    日志输出: "GET /api/validation 200 15.32ms"
+"""
+
+import logging
+import time
+from collections.abc import Awaitable, Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+logger = logging.getLogger(__name__)
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """
+    请求日志记录中间件
+
+    继承自 Starlette 的 BaseHTTPMiddleware，在请求处理前后记录时间戳，
+    计算请求处理耗时，并根据响应状态码分级输出日志（info/warning/error）。
+
+    日志分级策略:
+        - 2xx/3xx: info 级别（正常请求）
+        - 4xx: warning 级别（客户端错误，如参数校验失败）
+        - 5xx: error 级别（服务器内部错误）
+
+    Attributes:
+        无额外属性，依赖父类 BaseHTTPMiddleware 的基础设施
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> Response:
+        """
+        分发并包装请求处理流程，记录访问日志和耗时
+
+        Args:
+            request: 当前 HTTP 请求对象，包含 method、url、headers 等信息
+            call_next: 下一个中间件或路由处理器的可调用对象
+
+        Returns:
+            Response: 下游处理返回的响应对象（原样返回，不做修改）
+        """
+        # 记录请求开始时间戳（秒级浮点数）
+        start_time = time.time()
+
+        # 调用下游中间件或路由处理器，获取响应
+        response = await call_next(request)
+
+        # 计算请求处理耗时，转换为毫秒（保留两位小数）
+        duration_ms = (time.time() - start_time) * 1000
+
+        # 拼接日志消息：方法 路径 状态码 耗时
+        log_msg = f"{request.method} {request.url.path} {response.status_code} {duration_ms:.2f}ms"
+
+        # 根据 HTTP 状态码分级输出日志：
+        # 5xx 表示服务器内部错误，使用 error 级别
+        if response.status_code >= 500:
+            logger.error(log_msg)
+        # 4xx 表示客户端错误（如 400 Bad Request, 422 Validation Error），使用 warning 级别
+        elif response.status_code >= 400:
+            logger.warning(log_msg)
+        # 2xx/3xx 表示正常响应，使用 info 级别
+        else:
+            logger.info(log_msg)
+
+        return response

app/api/middleware/token_auth.py

@@ -0,0 +1,215 @@
+# 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 一次性 token 放行中间件（打包模式 CORS 纵深防御）
+
+功能概述:
+- Electron 打包模式每次启动后端生成随机 token：主进程经环境变量 PRECIS_API_TOKEN
+  注入本进程，并经 IPC 下发给本应用渲染进程；渲染进程随请求携带 X-Precis-Auth 头
+- 对携带有效 token 的请求放行 CORS：
+  * 预检 OPTIONS（Origin 为 null/空/非常规本机源）直接代答 200 预检响应
+  * 实际请求在响应缺少 Access-Control-Allow-Origin 时补写回显 Origin 的 CORS 头
+- 无效/缺失 token 的请求不介入，交由 CORSMiddleware 既有规则处理
+  （null Origin 仍被拒绝，本机源正常放行）
+
+威胁模型:
+- 后端无鉴权且存在文件读取端点，监听 127.0.0.1 动态端口；浏览器中的恶意网页可用
+  sandboxed iframe（Origin 恒为 null）+ 端口扫描对任意本机端口发跨域请求，若后端
+  对 null Origin 一律回写 ACAO，响应即可被该网页读取（本机数据泄露）
+- 旧方案（PRECIS_ALLOW_NULL_ORIGIN=1 全局放行）对本应用页面与恶意网页不加区分；
+  新方案下恶意网页拿不到 token（IPC 仅本应用渲染进程可达），其 null Origin 请求
+  依旧被 CORS 拒绝——token 成为"本应用页面"的身份凭据
+- token 比较使用 hmac.compare_digest，避免逐字节比较的时序侧信道
+
+生效条件:
+- 仅当 PRECIS_API_TOKEN 已配置（Electron spawn 后端时注入）时介入；Web / 开发模式
+  （未配置）完全直通，既有 localhost CORS 行为不变
+- PRECIS_ALLOW_NULL_ORIGIN 兼容开关保留（见 DynamicPortCORSMiddleware 原逻辑），
+  打包模式不再注入该变量
+
+架构设计:
+- 纯 ASGI 中间件（不继承 BaseHTTPMiddleware）：无请求体/响应体解析开销，
+  且预检代答只需两个 ASGI send 消息即可完成
+"""
+
+import hmac
+import os
+import re
+from collections.abc import MutableMapping
+from typing import Any
+
+from starlette.datastructures import Headers
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+# 携带 token 的自定义请求头（渲染进程 httpClient / sseClient 统一注入）
+AUTH_HEADER_NAME = "X-Precis-Auth"
+
+# "常规本机源"：http(s)://127.0.0.1[:port] 或 http(s)://localhost[:port]。
+# 这类 Origin 交给 CORSMiddleware 既有规则放行（动态端口正则），无需 token 代答。
+_LOCAL_ORIGIN_RE = re.compile(r"^https?://(127\.0\.0\.1|localhost)(:\d+)?$", re.IGNORECASE)
+
+# 预检代答回写的允许头列表（本应用实际使用的全部自定义头 + 常规 Content-Type）
+_ALLOWED_HEADERS = "X-Precis-Auth, X-Project-Config-Path, Content-Type"
+# 预检代答回写的允许方法列表
+_ALLOWED_METHODS = "GET, POST, PUT, DELETE, OPTIONS"
+
+
+class TokenOriginAuthMiddleware:
+    """
+    一次性 token 放行中间件（纯 ASGI）
+
+    处理流程:
+    1. 非 HTTP scope 或未配置 PRECIS_API_TOKEN → 完全直通
+    2. X-Precis-Auth 与环境 token 不等（含缺失）→ 完全直通
+       （null Origin 预检/请求由 CORSMiddleware 按既有规则拒绝）
+    3. OPTIONS 预检 + 非常规本机源 + 预检声明携带 X-Precis-Auth → 直接代答 200
+    4. 其余有效 token 请求 → 透传，响应缺少 ACAO 头时补写回显 Origin 的 CORS 头
+
+    补写时机说明:
+    - 本中间件在 add_middleware 顺序上位于 CORSMiddleware 之后添加（先执行，外层），
+      能看到 CORS 中间件处理后的响应头；仅当其未回写 ACAO（即 Origin 未被放行，
+      如 null Origin）时才补写，避免与 app://. / localhost 等 Origin 的既有
+      ACAO 头重复（重复 ACAO 头会被浏览器判定为 CORS 失败）
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        # 非 HTTP scope（websocket/lifespan）直接透传
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # token 逐请求读取（与 PRECIS_ALLOW_NULL_ORIGIN 的读取时机一致），
+        # 未配置即 Web / 开发模式，中间件完全直通
+        token = os.environ.get("PRECIS_API_TOKEN", "").strip()
+        if not token:
+            await self.app(scope, receive, send)
+            return
+
+        headers = Headers(scope=scope)
+        origin = headers.get("origin", "")
+        request_token = headers.get(AUTH_HEADER_NAME, "")
+
+        # token 比较走 compare_digest 防时序侧信道；编码为 bytes 以兼容任意请求头值
+        if not hmac.compare_digest(request_token.encode("utf-8"), token.encode("utf-8")):
+            # 无效/缺失 token：不介入。null Origin 的预检与实际请求由
+            # CORSMiddleware 按既有规则拒绝（不回写任何 CORS 头 / 预检 400）
+            await self.app(scope, receive, send)
+            return
+
+        # 预检代答：仅针对"非常规本机源"（null/空/app:// 等无法被既有 CORS 规则
+        # 放行的 Origin），且预检请求声明将携带 X-Precis-Auth 头。常规本机源的
+        # 预检直接透传，由 CORSMiddleware 按既有规则应答（行为不变）。
+        if (
+            scope["method"] == "OPTIONS"
+            and not _LOCAL_ORIGIN_RE.match(origin)
+            and self._preflight_declares_auth_header(headers)
+        ):
+            await self._send_preflight(send, origin)
+            return
+
+        # OPTIONS 一律透传，不再补写头：预检要么已被上面代答放行，要么由
+        # CORSMiddleware 按既有规则应答（本机源放行；携带有效 token 但未声明
+        # X-Precis-Auth 的非本机源预检被拒绝 400）——拒绝响应必须保持无 ACAO，
+        # 否则"拒绝"语义被破坏且响应头自相矛盾。
+        if scope["method"] == "OPTIONS":
+            await self.app(scope, receive, send)
+            return
+
+        # 有效 token 的实际请求：透传给下游（CORS + 路由），响应缺少 ACAO 时补写
+        await self._call_with_cors_echo(scope, receive, send, origin)
+
+    @staticmethod
+    def _preflight_declares_auth_header(headers: Headers) -> bool:
+        """
+        @methoddesc 判断预检请求的 Access-Control-Request-Headers 是否声明了 token 头
+
+        业务用途:
+        - 浏览器预检会列出实际请求将携带的非简单头；仅当其中包含 X-Precis-Auth
+          时才需要代答（实际请求才能真正带上 token）
+
+        参数:
+            headers: ASGI 请求头（大小写不敏感访问）
+
+        返回:
+            True 表示预检声明将携带 X-Precis-Auth 头
+        """
+        declared = headers.get("access-control-request-headers", "")
+        declared_names = {name.strip().lower() for name in declared.split(",") if name.strip()}
+        return AUTH_HEADER_NAME.lower() in declared_names
+
+    @staticmethod
+    async def _send_preflight(send: Send, origin: str) -> None:
+        """
+        @methoddesc 直接代答 CORS 预检（200 + 回显 Origin 的放行头）
+
+        业务用途:
+        - null Origin 的预检会被 CORSMiddleware 拒绝（400），本应用打包模式页面
+          （app:// 协议）恰是 null Origin，故对携带有效 token 的预检在此代答放行
+
+        参数:
+            send: ASGI send 可调用对象
+            origin: 请求 Origin 原样回显（null / app://. 等）
+        """
+        response_headers = [
+            (b"access-control-allow-origin", origin.encode("latin-1")),
+            (b"access-control-allow-headers", _ALLOWED_HEADERS.encode("latin-1")),
+            (b"access-control-allow-methods", _ALLOWED_METHODS.encode("latin-1")),
+            (b"access-control-allow-credentials", b"true"),
+            (b"vary", b"Origin"),
+            (b"content-length", b"0"),
+        ]
+        await send({"type": "http.response.start", "status": 200, "headers": response_headers})
+        await send({"type": "http.response.body", "body": b""})
+
+    async def _call_with_cors_echo(self, scope: Scope, receive: Receive, send: Send, origin: str) -> None:
+        """
+        @methoddesc 透传请求，并在响应缺少 ACAO 头时补写回显 Origin 的 CORS 头
+
+        业务用途:
+        - 有效 token 的实际请求（如 null Origin 的 GET）路由层正常处理，但
+          CORSMiddleware 不会为 null Origin 回写 ACAO，浏览器会拦截响应读取；
+          此处在响应阶段补写 ACAO（回显 Origin）+ Allow-Credentials。
+          对路由返回的 4xx/5xx 同样补写——前端需要能读到错误响应体
+
+        参数:
+            scope/receive/send: 标准 ASGI 三元组
+            origin: 请求 Origin（无 Origin 头时为空串，此时不补写任何 CORS 头）
+
+        [去重说明]
+        - allow_credentials=True 时 CORSMiddleware 对所有实际请求都会回写
+          access-control-allow-credentials（即使 Origin 未放行），因此每个待补写头
+          都必须先做存在性检查——重复的 CORS 头会被浏览器判定为 CORS 检查失败
+        """
+
+        async def send_wrapper(message: MutableMapping[str, Any]) -> None:
+            if message["type"] == "http.response.start" and origin:
+                response_headers: list[tuple[bytes, bytes]] = list(message.get("headers", []))
+                header_names = {key.decode("latin-1").lower() for key, _ in response_headers}
+                if "access-control-allow-origin" not in header_names:
+                    additions: list[tuple[bytes, bytes]] = [(b"access-control-allow-origin", origin.encode("latin-1"))]
+                    if "access-control-allow-credentials" not in header_names:
+                        additions.append((b"access-control-allow-credentials", b"true"))
+                    if "vary" not in header_names:
+                        additions.append((b"vary", b"Origin"))
+                    response_headers.extend(additions)
+                    message = dict(message)
+                    message["headers"] = response_headers
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)

app/api/models/__init__.py

@@ -0,0 +1,151 @@
+# 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/models/__init__.py
+"""
+@fileoverview API 模型包入口
+
+功能概述:
+- 作为 API 数据模型的统一出口，聚合所有子模块的模型定义
+- 通过从子模块导入再导出的方式，保持向后兼容性
+- 定义 __all__ 公开 API 列表
+
+输入示例:
+    from app.api.models import ProjectDetail, WorkspaceConfig, FullValidationResponse
+
+输出示例:
+    可直接访问所有聚合的模型类：
+    - ProjectDetail, ProjectConfigModel, PathsModel, StandardResponse
+    - EndpointModel, ConnectionRuleModel, ConnectionRuleConfigModel, ConnectionRulesModel
+    - ExternalDataSource, WorkspaceConfig, UIPreferences
+    - SchemaSaveRequest, SchemaSaveResponse, HeaderRowChangedRequest
+    - ValidationRequest, ValidationResponse, ValidationType
+    - FullValidationRequest, FullValidationResponse, FullValidationSummary
+"""
+
+# 从各子模块导入模型，保持向后兼容
+# ============================================================================
+# 项目配置模型
+# ============================================================================
+# ============================================================================
+# 连接规则模型
+# ============================================================================
+from .connection_rules import (
+    ConnectionRuleConfigModel,
+    ConnectionRuleModel,
+    ConnectionRulesModel,
+    EndpointModel,
+)
+
+# ============================================================================
+# 全量校验模型
+# ============================================================================
+from .full_validation import (
+    FullValidationErrorItem,
+    FullValidationOptions,
+    FullValidationRequest,
+    FullValidationResponse,
+    FullValidationSummary,
+    ValidationPassedItem,
+    ValidationStatistics,
+)
+
+# ============================================================================
+# 数据预览模型
+# ============================================================================
+# 注：FilePreviewResponse 定义在 app/api.routers.preview.models（路由侧实际使用的超集版本）
+from .project import (
+    PathsModel,
+    ProjectConfigModel,
+    ProjectDetail,
+    StandardResponse,
+)
+
+# ============================================================================
+# Schema 操作模型
+# ============================================================================
+from .schema import (
+    HeaderRowChangedRequest,
+    HeaderRowChangedResponse,
+    SchemaSaveRequest,
+    SchemaSaveResponse,
+)
+
+# ============================================================================
+# 校验模型
+# ============================================================================
+from .validation import (
+    InlineValidationRequest,
+    RegexValidationErrorRow,
+    RegexValidationRequest,
+    RegexValidationResponse,
+    RegexValidationResult,
+    ValidationErrorRow,
+    ValidationRequest,
+    ValidationResponse,
+    ValidationResult,
+    ValidationType,
+)
+
+# ============================================================================
+# 工作区模型
+# ============================================================================
+from .workspace import (
+    ExternalDataSource,
+    UIPreferences,
+    WorkspaceConfig,
+)
+
+# 定义公开的 API 列表
+__all__ = [
+    # 项目配置模型
+    "ProjectDetail",
+    "PathsModel",
+    "ProjectConfigModel",
+    "StandardResponse",
+    # 连接规则模型
+    "EndpointModel",
+    "ConnectionRuleConfigModel",
+    "ConnectionRuleModel",
+    "ConnectionRulesModel",
+    # 工作区模型
+    "ExternalDataSource",
+    "UIPreferences",
+    "WorkspaceConfig",
+    # Schema 操作模型
+    "SchemaSaveRequest",
+    "SchemaSaveResponse",
+    "HeaderRowChangedRequest",
+    "HeaderRowChangedResponse",
+    # 校验模型
+    "InlineValidationRequest",
+    "RegexValidationRequest",
+    "RegexValidationResponse",
+    "RegexValidationResult",
+    "RegexValidationErrorRow",
+    "ValidationRequest",
+    "ValidationResponse",
+    "ValidationResult",
+    "ValidationErrorRow",
+    "ValidationType",
+    # 全量校验模型
+    "FullValidationRequest",
+    "FullValidationOptions",
+    "FullValidationSummary",
+    "FullValidationErrorItem",
+    "FullValidationResponse",
+    "ValidationPassedItem",
+    "ValidationStatistics",
+]

app/api/models/connection_rules.py

@@ -0,0 +1,98 @@
+# 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/models/connection_rules.py
+"""
+@fileoverview 连接规则 API 模型
+
+功能概述:
+- 定义连接规则相关的 Pydantic 模型
+- 被 connection_rules 路由及外部调用方复用
+
+输入示例:
+    {
+        "version": "1.0",
+        "rules": [
+            {
+                "id": "schema_to_constraint",
+                "name": "Schema -> Constraint",
+                "source": {"node_types": ["SchemaNode"]},
+                "target": {"node_types": ["ConstraintNode"]}
+            }
+        ]
+    }
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class EndpointModel(BaseModel):
+    """
+    连接端点模型。
+
+    定义连接规则中源端点或目标端点允许连接的节点类型和 handle。
+    - node_types: 允许连接的节点类型列表，如 ["SchemaNode", "ConstraintNode"]
+    - handles: 可选，限制只允许特定的 handle ID 建立连接
+    """
+
+    node_types: list[str] = Field(..., description="允许的节点类型列表")
+    handles: list[str] | None = Field(default=None, description="允许的 handle ID 列表")
+
+
+class ConnectionRuleConfigModel(BaseModel):
+    """
+    连接规则配置模型。
+
+    定义单条连接规则的附加行为：
+    - allow_multiple: 是否允许一个源端点同时连接多个目标端点
+    - validation_mode: 验证严格程度，strict 表示完全匹配，loose 表示允许模糊匹配
+    """
+
+    allow_multiple: bool | None = Field(default=True, description="是否允许多个连接")
+    validation_mode: str | None = Field(default="strict", description="验证模式: strict/loose")
+
+
+class ConnectionRuleModel(BaseModel):
+    """
+    单条连接规则模型。
+
+    定义画布中哪类节点可以连接到哪类节点：
+    - id: 规则的唯一标识，用于前端快速查找和调试
+    - name: 规则的显示名称，供用户阅读
+    - source: 源端点定义（哪些节点可以作为连接起点）
+    - target: 目标端点定义（哪些节点可以作为连接终点）
+    - config: 可选的附加配置（如是否允许多连、验证模式）
+    """
+
+    id: str = Field(..., description="规则唯一标识")
+    name: str = Field(..., description="规则名称")
+    source: EndpointModel = Field(..., description="源端点定义")
+    target: EndpointModel = Field(..., description="目标端点定义")
+    config: ConnectionRuleConfigModel | None = Field(default=None, description="规则配置")
+
+
+class ConnectionRulesModel(BaseModel):
+    """
+    连接规则集合模型。
+
+    作为 connection-rules.precis.yaml 文件的根对象：
+    - version: 规则文件格式版本，便于后续格式升级时做兼容处理
+    - rules: 具体的连接规则列表，按顺序依次匹配
+    """
+
+    version: str = Field(default="1.0", description="规则文件版本")
+    rules: list[ConnectionRuleModel] = Field(default=[], description="规则列表")