precis-cli 0.1.3__py3-none-any.whl

app/api/models/project.py

@@ -0,0 +1,117 @@
+# 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/project.py
+"""
+@fileoverview 项目相关请求/响应模型
+
+功能概述:
+- 定义项目配置相关的 Pydantic 数据模型
+- 包含项目详情、路径配置、项目配置文件结构、通用响应等模型
+
+输入示例:
+    ProjectConfigModel(
+        project_id="my-project",
+        project_name="My Data Project",
+        paths=PathsModel(schemas="schemas/", constraints="constraints/")
+    )
+
+输出示例:
+    ProjectDetail(
+        project_id="my-project",
+        project_name="My Data Project",
+        schemas_count=5,
+        constraints_count=10
+    )
+"""
+
+from pydantic import BaseModel, Field
+
+
+class ProjectDetail(BaseModel):
+    """
+    用于描述当前活动项目的详细信息模型
+
+    该模型在项目概览或项目列表接口中使用，
+    展示项目的核心统计信息和基本标识。
+
+    Attributes:
+        project_id: 项目唯一标识符
+        project_name: 项目显示名称
+        schemas_count: 项目中定义的 Schema 数量
+        constraints_count: 项目中定义的约束规则数量
+        last_validated: 最后一次验证的时间戳（ISO 格式），预留字段
+    """
+
+    project_id: str  # 项目唯一标识符，用于区分不同项目
+    project_name: str  # 项目显示名称，面向用户的可读名称
+    schemas_count: int  # 项目中已定义的 Schema（表结构）数量
+    constraints_count: int  # 项目中已定义的约束规则数量
+    last_validated: str | None = None  # 最后一次执行校验的时间戳，ISO 8601 格式，可选
+
+
+class PathsModel(BaseModel):
+    """
+    定义项目中各类配置文件的路径配置模型
+
+    用于配置 Schema、Constraints、Patterns 等配置文件
+    相对于项目根目录的存放路径。
+
+    Attributes:
+        schemas: Schema 配置文件存放目录路径
+        constraints: Constraints 约束规则文件存放目录路径
+        patterns: Patterns 模式匹配规则文件存放目录路径（可选）
+    """
+
+    schemas: str = Field(..., title="表结构 (Schemas) 路径")  # Schema 配置文件相对于项目根目录的存放路径，必填
+    constraints: str = Field(
+        ..., title="约束规则 (Constraints) 路径"
+    )  # Constraints 约束规则文件相对于项目根目录的存放路径，必填
+    patterns: str | None = Field(
+        None, title="模式 (Patterns) 路径"
+    )  # Patterns 模式匹配规则文件相对于项目根目录的存放路径，可选
+
+
+class ProjectConfigModel(BaseModel):
+    """
+    定义 project.yaml 完整结构的数据模型
+
+    该模型对应项目根目录下的 project.yaml 配置文件，
+    包含项目的全局配置信息。
+
+    Attributes:
+        project_id: 项目唯一标识符
+        project_name: 项目显示名称
+        paths: 各类配置文件的路径设置（嵌套 PathsModel）
+    """
+
+    project_id: str = Field(..., title="项目ID")  # 项目唯一标识符，全局唯一，用于内部引用和目录命名
+    project_name: str = Field(..., title="项目名称")  # 项目显示名称，面向用户的可读名称
+    paths: PathsModel  # 嵌套路径配置模型，定义各类配置文件的存放位置
+
+
+class StandardResponse(BaseModel):
+    """
+    定义通用消息响应模型
+
+    用于简单的文本响应场景，如确认消息、状态更新等。
+
+    Attributes:
+        success: 操作是否成功，默认为 True
+        message: 响应消息内容
+    """
+
+    success: bool = True  # 操作是否成功，默认返回 True
+    message: str  # 响应消息内容，通常用于操作成功确认或状态说明

app/api/models/projects.py

@@ -0,0 +1,80 @@
+# 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.
+"""项目管理 API 模型：项目扫描、打开、创建、关闭与当前项目查询的请求/响应定义。"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class ProjectInfo(BaseModel):
+    """扫描返回的单个项目信息。"""
+
+    name: str
+    path: str
+    schema_count: int
+    constraint_count: int
+    last_modified: str
+
+
+class ScanResponse(BaseModel):
+    """项目扫描端点的响应。"""
+
+    work_dir: str
+    projects: list[ProjectInfo]
+
+
+class OpenProjectRequest(BaseModel):
+    """打开项目的请求体。"""
+
+    path: str
+
+
+class OpenProjectResponse(BaseModel):
+    """打开项目的响应。"""
+
+    success: bool
+    name: str
+    path: str
+
+
+class CreateProjectRequest(BaseModel):
+    """创建新项目脚手架的请求体。"""
+
+    path: str
+    name: str
+
+
+class CreateProjectResponse(BaseModel):
+    """创建项目的响应。"""
+
+    success: bool
+    name: str
+    path: str
+
+
+class CurrentProjectResponse(BaseModel):
+    """当前项目查询的响应。"""
+
+    has_current: bool
+    path: str | None = None
+    name: str | None = None
+
+
+class CloseProjectResponse(BaseModel):
+    """关闭项目的响应。"""
+
+    success: bool

app/api/models/schema.py

@@ -0,0 +1,121 @@
+# 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/schema.py
+"""
+@fileoverview Schema 相关请求/响应模型
+
+功能概述:
+- 定义 Schema 文件操作相关的 Pydantic 数据模型
+- 包含 Schema 保存请求/响应、表头行变更请求/响应等模型
+
+输入示例:
+    SchemaSaveRequest(
+        action="save_schema",
+        schema_name="users",
+        yaml_content="version: 2\nid: users\n...",
+        saved_at="2024-01-01T00:00:00Z"
+    )
+
+输出示例:
+    SchemaSaveResponse(
+        success=True,
+        message="Schema saved successfully",
+        schema_name="users",
+        saved_at="2024-01-01T00:00:00Z"
+    )
+"""
+
+from pydantic import BaseModel, Field
+
+
+class SchemaSaveRequest(BaseModel):
+    """
+    Schema 保存请求模型
+
+    前端保存 Schema 配置文件时发送的请求体。
+
+    Attributes:
+        action: 操作类型，固定为 'save_schema'
+        schema_name: Schema 名称（不含 .yaml 后缀）
+        yaml_content: YAML 格式的 Schema 内容
+        saved_at: 保存时间（ISO 格式时间戳）
+    """
+
+    action: str = Field(..., description="操作类型，固定为'save_schema'")
+    schema_name: str = Field(..., description="Schema名称")
+    yaml_content: str = Field(..., description="YAML格式的Schema内容")
+    saved_at: str = Field(..., description="保存时间")
+
+
+class SchemaSaveResponse(BaseModel):
+    """
+    Schema 保存响应模型
+
+    Schema 保存操作的结果响应。
+
+    Attributes:
+        success: 保存是否成功
+        message: 保存结果消息
+        schema_name: Schema 名称
+        saved_at: 保存时间
+    """
+
+    success: bool = Field(..., description="保存是否成功")
+    message: str = Field(..., description="保存结果消息")
+    schema_name: str = Field(..., description="Schema名称")
+    saved_at: str = Field(..., description="保存时间")
+
+
+class HeaderRowChangedRequest(BaseModel):
+    """
+    表头行变更请求模型
+
+    用户在 UI 中修改数据表的表头行位置时发送的请求。
+
+    Attributes:
+        action: 操作类型，固定为 'header_row_changed'
+        node_id: 源预览节点 ID
+        header_row: 新的表头行索引（0 表示第一行）
+        old_header_row: 旧的表头行索引
+        row_data: 表头行数据（可选）
+        schema_name: 关联的 Schema 名称（可选）
+    """
+
+    action: str = Field(..., description="操作类型，固定为'header_row_changed'")
+    node_id: str = Field(..., description="源预览节点ID")
+    header_row: int | None = Field(None, description="新的表头行索引")
+    old_header_row: int | None = Field(None, description="旧的表头行索引")
+    row_data: dict | None = Field(None, description="表头行数据")
+    schema_name: str | None = Field(None, description="关联的Schema名称")
+
+
+class HeaderRowChangedResponse(BaseModel):
+    """
+    表头行变更响应模型
+
+    表头行变更操作的结果响应。
+
+    Attributes:
+        success: 更新是否成功
+        message: 更新结果消息
+        schema_name: 关联的 Schema 名称（可选）
+        updated_at: 更新时间（可选）
+    """
+
+    success: bool = Field(..., description="更新是否成功")
+    message: str = Field(..., description="更新结果消息")
+    schema_name: str | None = Field(default=None, description="关联的Schema名称")
+    updated_at: str | None = Field(default=None, description="更新时间")

app/api/models/v2_responses.py

@@ -0,0 +1,46 @@
+# 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 V2 配置响应模型
+
+功能概述:
+- 定义 V2 项目配置 API 响应相关的 Pydantic 数据模型
+- 将内部配置模型与 API 响应契约解耦，保持 API 兼容性
+
+输入示例:
+    内部 ProjectManifestV2 模型实例
+
+输出示例:
+    ManifestResponse(
+        version=2,
+        project=ProjectInfo(id="proj", name="Project"),
+        schemas=[...],
+        constraints=[...]
+    )
+"""
+
+from app.shared.core.project.manifest.types import ProjectManifestV2
+
+
+class ManifestResponse(ProjectManifestV2):
+    """
+    /manifest GET 的 API 响应模型。
+
+    当前继承自 ProjectManifestV2 以保持兼容性，
+    后续可按需添加/移除字段，或在此做数据转换。
+    """
+
+    pass

app/api/models/validation.py

@@ -0,0 +1,303 @@
+# 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/validation.py
+"""
+@fileoverview 校验请求/响应模型
+
+功能概述:
+- 定义数据校验相关的 Pydantic 数据模型
+- 包含正则校验请求/响应、统一校验请求/响应、校验类型枚举等
+
+输入示例:
+    RegexValidationRequest(
+        regex_pattern="^1[3-9]\\d{9}$",
+        match_mode="full",
+        target_column_name="phone",
+        source_file_path="data/users.xlsx"
+    )
+
+输出示例:
+    ValidationResponse(
+        success=True,
+        validation_type="regex",
+        data=ValidationResult(
+            is_valid=False,
+            error_count=3,
+            total_rows=100,
+            error_rows=[...]
+        )
+    )
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class RegexValidationRequest(BaseModel):
+    """
+    正则表达式校验请求模型
+
+    用于对数据列进行正则表达式模式匹配校验。
+
+    Attributes:
+        regex_pattern: 正则表达式模式
+        regex_flags: 正则表达式标志（如 g, i, m）
+        match_mode: 匹配模式（full/partial/extract）
+        case_sensitive: 是否大小写敏感
+        target_column_name: 目标列名
+        source_file_path: 数据源文件路径
+        sheet_name: Excel 工作表名称（可选）
+    """
+
+    regex_pattern: str = Field(..., description="正则表达式模式")  # 用于匹配的正则表达式字符串，必填
+    regex_flags: str | None = Field(None, description="正则表达式标志")  # 正则标志（如 g, i, m），可选
+    match_mode: str = Field(
+        default="full", description="匹配模式: full/partial/extract"
+    )  # 匹配模式：full（全匹配）、partial（部分匹配）、extract（提取）
+    case_sensitive: bool = Field(
+        default=True, description="是否大小写敏感"
+    )  # True 表示区分大小写，False 表示忽略大小写
+    target_column_name: str = Field(..., description="目标列名")  # 需要进行正则校验的数据列名称，必填
+    source_file_path: str = Field(
+        ..., description="数据源文件路径"
+    )  # 数据源文件（Excel/CSV/JSON）的绝对或相对路径，必填
+    sheet_name: str | None = Field(None, description="Excel工作表名称")  # 当数据源为 Excel 时指定工作表名称，可选
+
+
+class RegexValidationErrorRow(BaseModel):
+    """
+    正则校验错误行模型
+
+    记录正则校验失败的具体行信息。
+
+    Attributes:
+        row_index: 行索引（从 0 开始）
+        cell_value: 单元格原始值
+    """
+
+    row_index: int = Field(..., description="行索引")  # 数据行在源文件中的索引位置，从 0 开始计数
+    cell_value: str = Field(..., description="单元格值")  # 该校验失败的单元格原始值
+
+
+class RegexValidationResult(BaseModel):
+    """
+    正则表达式校验结果模型
+
+    包含正则校验的详细结果信息。
+
+    Attributes:
+        is_valid: 校验是否通过
+        error_count: 错误行数量
+        total_rows: 总行数
+        match_count: 匹配行数量
+        error_rows: 错误行列表
+        validation_time: 校验耗时时间戳
+    """
+
+    is_valid: bool = Field(..., description="校验是否通过")  # True 表示全部通过，False 表示存在错误行
+    error_count: int = Field(..., description="错误数量")  # 校验失败的行数
+    total_rows: int = Field(..., description="总行数")  # 参与校验的数据总行数（不含表头）
+    match_count: int = Field(..., description="匹配数量")  # 正则匹配成功的行数
+    error_rows: list[RegexValidationErrorRow] = Field(default=[], description="错误行列表")  # 校验失败的详细行信息列表
+    validation_time: str = Field(..., description="校验时间")  # 校验执行完成的时间戳，ISO 8601 格式
+
+
+class RegexValidationResponse(BaseModel):
+    """
+    正则表达式校验响应模型
+
+    正则校验接口的标准响应格式。
+
+    Attributes:
+        success: 请求是否成功
+        data: 校验结果详情
+        error: 错误信息（如果有）
+        schema_name: 关联的 Schema 名称（可选）
+        updated_at: 更新时间（可选）
+    """
+
+    success: bool = Field(..., description="请求是否成功")  # True 表示请求处理成功，False 表示接口层面出错
+    data: RegexValidationResult | None = Field(None, description="校验结果")  # 校验成功时返回的详细结果，失败时为 None
+    error: str | None = Field(None, description="错误信息")  # 请求处理失败时的错误描述，成功时为 None
+    schema_name: str | None = Field(
+        default=None, description="Schema名称"
+    )  # 关联的 Schema 名称，用于前端展示上下文，可选
+    updated_at: str | None = Field(default=None, description="更新时间")  # 响应生成的时间戳，ISO 8601 格式，可选
+
+
+# 统一使用 services 层的 ValidationType 作为唯一真相源
+# API 层不再维护独立的校验类型定义，避免与服务层不一致
+from app.shared.services.validation.types import ValidationType  # noqa: F401
+
+
+class ValidationRequest(BaseModel):
+    """
+    统一校验请求模型
+
+    用于通用数据校验接口的请求体。
+    支持多种校验类型，通过 validation_type 字段指定。
+
+    Attributes:
+        validation_type: 校验类型（regex/unique/not_null/allowed_values/conditional/scripted）
+        target_column_name: 目标列名
+        source_file_path: 数据源文件路径
+        sheet_name: Excel 工作表名称（可选）
+        header_row: 表头行索引，0 表示第一行（可选）
+        validation_config: 校验特定配置（字典）
+        allow_unsafe_eval: 是否允许执行脚本化校验（eval 模式）
+    """
+
+    validation_type: str = Field(
+        ..., description="校验类型: regex/unique/not_null/allowed_values/conditional/scripted"
+    )  # 指定要执行的校验类型，必填
+    target_column_name: str = Field(..., description="目标列名")  # 需要校验的数据列名称，必填
+    source_file_path: str = Field(
+        ..., description="数据源文件路径"
+    )  # 数据源文件（Excel/CSV/JSON）的绝对或相对路径，必填
+    sheet_name: str | None = Field(None, description="Excel工作表名称")  # 当数据源为 Excel 时指定工作表名称，可选
+    header_row: int | None = Field(
+        None, description="表头行索引，0表示第一行"
+    )  # 指定表头所在行索引，0 表示第一行，可选
+    validation_config: dict | None = Field(
+        default={}, description="校验特定配置"
+    )  # 各类校验的特定配置参数（如 allowed_values 的值列表），默认为空字典
+    allow_unsafe_eval: bool = Field(
+        False, description="是否允许执行脚本化校验（eval模式）"
+    )  # True 允许执行脚本化校验（存在安全风险），默认关闭
+    column_data_type: str | None = Field(
+        None, description="目标列在 Schema 中声明的数据类型（如 string/integer/decimal）"
+    )  # 用于单节点校验时按 Schema 类型转换目标列，保持与全量校验行为一致
+    json_path: str | None = Field(
+        None, description="JSON 数据源的 JSONPath 表达式（可选）"
+    )  # 用于从嵌套 JSON 中提取目标记录数组
+    json_format: Literal["array", "lines", "object"] | None = Field(
+        None, description="JSON 数据源格式：array | lines | object（可选,auto 已废弃）"
+    )  # 用于指定 JSON 文件的解析方式
+    record_path: str | None = Field(
+        None, description="JSON 数据源的 record_path，用于展开嵌套数组（可选）"
+    )  # 用于将嵌套 JSON 数组扁平化为 DataFrame 行
+
+    def to_source_config(self) -> dict[str, Any] | None:
+        """构建 JSON 数据源配置字典，仅在有 JSON 相关字段时返回。"""
+        cfg: dict[str, Any] = {}
+        if self.json_path is not None:
+            cfg["json_path"] = self.json_path
+        if self.json_format is not None:
+            cfg["json_format"] = self.json_format
+        if self.record_path is not None:
+            cfg["record_path"] = self.record_path
+        return cfg if cfg else None
+
+
+class InlineValidationRequest(BaseModel):
+    """
+    行内数据校验请求模型
+
+    用于纯数据节点（TransformOutput / ManualData）的行内校验接口。
+    直接接收行数据，无需文件路径。
+
+    Attributes:
+        validation_type: 校验类型（not_null/unique/allowed_values/range/charset/scripted/foreign_key 等）
+        target_column_name: 目标列名
+        rows: 行数据二维数组，默认第一行为表头（与 TransformOutput/ManualData 的 rows 结构一致）
+        column_names: 列名列表，当提供时 rows 全部视为数据行（覆盖默认的第一行表头行为）
+        validation_config: 校验特定配置（字典）
+        allow_unsafe_eval: 是否允许执行脚本化校验（eval 模式）
+    """
+
+    validation_type: str = Field(
+        ..., description="校验类型"
+    )  # 指定要执行的校验类型（如 not_null/unique/range 等），必填
+    target_column_name: str = Field(..., description="目标列名")  # 需要校验的数据列名称，必填
+    rows: list[list[Any]] = Field(
+        ..., description="行数据，默认第一行为表头"
+    )  # 二维数组形式的行数据，默认第一行为表头，后续行为数据
+    column_names: list[str] = Field(
+        default=[], description="列名列表（提供时 rows 全部视为数据行）"
+    )  # 显式指定列名时，rows 全部视为数据行（不再将第一行作为表头）
+    validation_config: dict | None = Field(
+        default={}, description="校验特定配置"
+    )  # 各类校验的特定配置参数，默认为空字典
+    allow_unsafe_eval: bool = Field(
+        False, description="是否允许执行脚本化校验（eval模式）"
+    )  # True 允许执行脚本化校验（存在安全风险），默认关闭
+    column_data_type: str | None = Field(
+        None, description="目标列在 Schema 中声明的数据类型（如 string/integer/decimal）"
+    )  # 用于单节点校验时按 Schema 类型转换目标列，保持与全量校验行为一致
+
+
+class ValidationErrorRow(BaseModel):
+    """
+    校验错误行模型
+
+    记录数据校验失败的具体行信息。
+
+    Attributes:
+        row_index: 行索引（从 0 开始）
+        cell_value: 单元格原始值
+        error_message: 错误描述信息（可选）
+    """
+
+    row_index: int = Field(..., description="行索引")  # 数据行在源文件或行内数据中的索引位置，从 0 开始计数
+    cell_value: str = Field(..., description="单元格值")  # 该校验失败的单元格原始值
+    error_message: str | None = Field(
+        None, description="错误信息"
+    )  # 校验失败的具体错误描述，如"值不在允许列表中"，可选
+
+
+class ValidationResult(BaseModel):
+    """
+    校验结果模型
+
+    包含通用校验的详细结果信息。
+
+    Attributes:
+        is_valid: 校验是否通过
+        error_count: 错误行数量
+        total_rows: 总行数
+        match_count: 匹配行数量（可选）
+        error_rows: 错误行列表
+        validation_time: 校验耗时
+    """
+
+    is_valid: bool = Field(..., description="校验是否通过")  # True 表示全部通过，False 表示存在错误行
+    error_count: int = Field(..., description="错误数量")  # 校验失败的行数
+    total_rows: int = Field(..., description="总行数")  # 参与校验的数据总行数（不含表头）
+    match_count: int | None = Field(None, description="匹配数量")  # 匹配成功的行数（部分校验类型适用，如 regex），可选
+    error_rows: list[ValidationErrorRow] = Field(default=[], description="错误行列表")  # 校验失败的详细行信息列表
+    validation_time: str = Field(..., description="校验耗时")  # 校验执行耗时，通常以毫秒或秒为单位的字符串
+
+
+class ValidationResponse(BaseModel):
+    """
+    统一校验响应模型
+
+    校验接口的标准响应格式。
+
+    Attributes:
+        success: 请求是否成功
+        validation_type: 执行的校验类型
+        data: 校验结果详情
+        error: 错误信息（如果有）
+    """
+
+    success: bool = Field(..., description="请求是否成功")  # True 表示请求处理成功，False 表示接口层面出错
+    validation_type: str = Field(
+        ..., description="执行的校验类型"
+    )  # 实际执行的校验类型标识，与请求中的 validation_type 对应
+    data: ValidationResult | None = Field(None, description="校验结果")  # 校验成功时返回的详细结果，失败时为 None
+    error: str | None = Field(None, description="错误信息")  # 请求处理失败时的错误描述，成功时为 None