precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/template/types.py

@@ -0,0 +1,114 @@
+# 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 模板数据模型定义
+
+功能概述:
+- 定义模板内部节点 (TemplateNode)
+- 定义模板文件根模型 (TemplateFile)
+
+架构设计:
+- TemplateFile 是 *.template.yaml 文件解析后的根 Pydantic 模型
+- 模板内节点 ID 为局部命名空间，展开时映射为全局 ID
+- 模板节点存完整默认值，无参数占位符替换机制
+- 展开后用户直接在画布上编辑内部节点
+
+输入示例:
+    TemplateFile(
+        id="age_check",
+        name="年龄校验",
+        nodes=[
+            TemplateNode(id="md1", kind="manualData", type="ManualData", column_name="age", rows=[["18"]]),
+            TemplateNode(id="check_range", kind="constraint", type="Range", input_from_node="md1", params={"min": 0, "max": 120}),
+        ],
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class TemplateNode(BaseModel):
+    """@classdesc 模板内部 DAG 节点
+
+    字段说明:
+        - id: 模板内局部 ID（展开时映射为 {instance_id}__{local_id}）
+        - kind: 节点类型分类（transform/constraint/regex/manualData）
+        - type: 具体类型名称（如 StringSplit/Range/NotNull 等）；manualData kind 时固定为 "ManualData"
+        - input_from_node: 上游节点 ID（仅支持模板内部节点引用）
+        - input_column: 输入列名
+        - params: 转换/约束参数（完整默认值）
+        - output_columns: 输出列名列表
+        - refs: 约束引用区
+        - enabled: 是否启用
+        - description: 描述
+        - column_name: manualData 专用 — 列名
+        - rows: manualData 专用 — 占位数据（二维字符串数组）
+        - column_data_type: manualData 专用 — 列数据类型
+    """
+
+    id: str
+    kind: Literal["transform", "constraint", "regex", "manualData"]
+    type: str
+    input_from_node: str | None = None
+    input_column: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+    output_columns: list[str] = Field(default_factory=list)
+    refs: dict[str, Any] = Field(default_factory=dict)
+    description: str | None = None
+    enabled: bool = True
+    # manualData 专用字段
+    column_name: str = ""
+    rows: list[list[str]] = Field(default_factory=list)
+    column_data_type: str = "string"
+
+
+class TemplateParameter(BaseModel):
+    """@classdesc 模板参数声明
+
+    字段说明:
+        - name: 参数名（对应节点值中的 {{name}} 占位符）
+        - default: 参数默认值（实例未提供该参数时使用）
+    """
+
+    name: str
+    default: Any = None
+
+
+class TemplateFile(BaseModel):
+    """@classdesc 模板定义文件根模型
+
+    对应 *.template.yaml 文件的结构。
+    展开时由 expander 将节点映射为标准的 TransformFile/ConstraintFile/RegexNodeFile/ManualDataFile。
+
+    字段说明:
+        - version: 配置版本号（固定为 2）
+        - id: 模板唯一标识
+        - name: 模板显示名称
+        - description: 模板描述
+        - parameters: 参数声明列表（展开时对节点值中的 {{param}} 占位符做替换）
+        - nodes: 内部 DAG 节点列表
+    """
+
+    version: int = Field(2, description="配置版本号（固定为 2）")
+    id: str = Field(..., description="模板唯一标识")
+    name: str = Field(..., description="模板显示名称")
+    description: str | None = Field(None, description="模板描述")
+    parameters: list[TemplateParameter] = Field(default_factory=list, description="参数声明列表")
+    nodes: list[TemplateNode] = Field(default_factory=list, description="内部 DAG 节点列表")

app/shared/core/project/transform/reader.py

@@ -0,0 +1,76 @@
+# 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 Transform 配置文件读取模块
+
+功能概述:
+- 读取并解析 .transform.yaml 配置文件
+- 使用 Pydantic 模型进行数据验证
+
+输入示例:
+    transform_path = Path("/path/to/project/transforms/split.yaml")
+
+    # 文件内容:
+    # version: 2
+    # id: split_name
+    # type: StringSplit
+    # enabled: true
+    # input_column: full_name
+    # params:
+    #   delimiter: " "
+    # output_columns: [first_name, last_name]
+
+输出示例:
+    TransformFile(
+        version=2,
+        id="split_name",
+        type="StringSplit",
+        enabled=True,
+        input_column="full_name",
+        params={"delimiter": " "},
+        output_columns=["first_name", "last_name"]
+    )
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .types import TransformFile
+
+
+def load_transform(transform_path: Path) -> TransformFile:
+    """@methoddesc 加载 Transform 配置文件
+
+    输入示例:
+        transform_path = Path("/path/to/project/transforms/split.yaml")
+
+    输出示例:
+        TransformFile(
+            version=2,
+            id="split_name",
+            type="StringSplit",
+            enabled=True,
+            input_column="full_name",
+            params={"delimiter": " "},
+            output_columns=["first_name", "last_name"]
+        )
+    """
+    with open(transform_path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+    return TransformFile.model_validate(raw)

app/shared/core/project/transform/types.py

@@ -0,0 +1,116 @@
+# 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 功能/转换节点配置模块
+
+功能概述:
+- 定义 Transform 节点的数据模型 (TransformFile)
+- 支持 StringSplit、RegexExtract、MathExpr、DateFormat 等转换类型
+- 使用 Pydantic BaseModel 进行数据验证
+
+架构设计:
+- 统一入口: TransformFile 作为所有功能节点的根模型
+- 类型区分: type 字段标识具体转换逻辑
+- 参数灵活: params 为 Dict，各子类型自行定义内部结构
+
+输入示例:
+    TransformFile(
+        version=2,
+        id="split_id_card",
+        type="StringSplit",
+        input_from_node="source_users_01",
+        input_column="id_card",
+        params={
+            "strategy": "fixed_position",
+            "ranges": [
+                {"name": "region_code", "start": 0, "end": 6},
+                {"name": "birth_date", "start": 6, "end": 14},
+            ]
+        },
+        output_columns=["region_code", "birth_date"]
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class TransformFile(BaseModel):
+    """
+    @classdesc 单条功能/转换节点文件内容。
+
+    支持类型（22 种）:
+    - 多列输出: StringSplit, RegexExtract
+    - 单列输出（行数不变）: MathExpr, DateFormat, Lookup, Strip, UpperCase, LowerCase,
+      Replace, FillNA, CastType, Concat, Substring, ConditionalAssign,
+      Digits, WeightedSum, Modulo, MapValue
+    - 行数改变: FilterRows, DropDuplicates, Aggregate, SortRows
+      （运行器已在 transforms/registry.py 注册；行位重排对约束错误 row_index
+      语义的影响见 docs/contracts/validate-json-v1.md）
+
+    输入接口:
+    - input_from_node: 上游节点 ID（优先）
+    - input_column: 上游节点中的目标列名
+
+    输出接口:
+    - output_columns: 转换后产生的列名列表
+    """
+
+    version: int = Field(2, description="配置版本号（固定为 2）")
+    id: str = Field(..., description="转换节点 ID（稳定标识）")
+    type: Literal[
+        "StringSplit",
+        "RegexExtract",
+        "MathExpr",
+        "DateFormat",
+        "Lookup",
+        "Strip",
+        "UpperCase",
+        "LowerCase",
+        "Replace",
+        "FillNA",
+        "FilterRows",
+        "DropDuplicates",
+        "CastType",
+        "Concat",
+        "Substring",
+        "Aggregate",
+        "ConditionalAssign",
+        "SortRows",
+        "Digits",
+        "WeightedSum",
+        "Modulo",
+        "MapValue",
+    ] = Field(..., description="转换类型")
+    enabled: bool = Field(True, description="是否启用")
+    description: str | None = Field(None, description="描述")
+
+    # 输入接口
+    input_from_node: str | None = Field(None, description="上游数据流节点 ID")
+    input_column: str | None = Field(None, description="上游节点中的目标列名")
+
+    # 功能参数（因类型而异，各子类型自行约定结构）
+    params: dict[str, Any] = Field(default_factory=dict, description="转换参数（因类型而异）")
+
+    # 输出定义
+    output_columns: list[str] = Field(default_factory=list, description="转换后产生的列名列表")
+
+
+# 兼容别名
+TransformFileV2 = TransformFile

app/shared/core/project/transform/writer.py

@@ -0,0 +1,84 @@
+# 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 Transform 节点写入模块
+
+功能概述:
+- 写入 *.transform.yaml 文件
+- 优化字段顺序，提升 YAML 可读性
+
+架构设计:
+- 唯一入口: 封装 Pydantic 模型到 YAML 文件的转换逻辑
+- 字段排序: 按重要程度分组（核心 / 可选 / 内部）
+- 一致性: 与 schema/writer.py、regex/writer.py 保持一致的排序策略
+
+输入示例:
+    transform = TransformFile(
+        version=2,
+        id="cast_price",
+        type="CastType",
+        input_column="price",
+        params={"target_type": "decimal"},
+        output_columns=["price"],
+    )
+
+输出示例:
+    save_transform(transform, "transforms/cast_price.transform.yaml")
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from app.shared.core.io.yaml import write_yaml_atomic
+
+from .types import TransformFile
+
+if TYPE_CHECKING:
+    from .types import TransformFile
+
+
+def save_transform(transform: TransformFile, transform_path: str | Path) -> None:
+    """
+    @methoddesc 保存 Transform 节点到 YAML 文件。
+
+    字段顺序优化（按重要程度分组）：
+    L1（核心）：type, description, params, input_from_node, input_column
+    L2（可选）：enabled, output_columns
+    L3（内部）：version, id
+
+    :param transform: TransformFile 对象，包含转换节点的完整配置
+    :param transform_path: 保存路径，可以是相对路径或绝对路径
+    :raises IOError: 文件写入失败时抛出
+    """
+    data = transform.model_dump()
+
+    ordered = {
+        # L1 - 核心字段
+        "type": data["type"],
+        "description": data.get("description"),
+        "input_from_node": data.get("input_from_node"),
+        "input_column": data.get("input_column"),
+        "params": data.get("params", {}),
+        # L2 - 可选配置
+        "enabled": data.get("enabled", True),
+        "output_columns": data.get("output_columns", []),
+        # L3 - 内部字段
+        "version": data["version"],
+        "id": data["id"],
+    }
+
+    write_yaml_atomic(Path(transform_path), ordered)

app/shared/core/pydantic_messages.py

@@ -0,0 +1,59 @@
+# 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 Pydantic 校验消息的中文本地化（单一事实源）
+
+Pydantic 的校验消息默认是英文（"Input should be a valid integer" 等），
+直接透给用户属于黑话。本模块提供常见消息的中文映射（子串替换，保留
+位置与字段等上下文），供 422 全局 handler 与 LLM 动作 spec 校验共用。
+未命中的消息保留原文，不会显示空白。
+"""
+
+from __future__ import annotations
+
+# 英文片段 → 中文（按出现顺序做子串替换）
+_PATTERNS: list[tuple[str, str]] = [
+    ("Input should be a valid integer", "应为整数"),
+    ("Input should be a valid number", "应为数字"),
+    ("Input should be a valid string", "应为文本"),
+    ("Input should be a valid boolean", "应为 true/false"),
+    ("Input should be a valid dictionary", "应为对象"),
+    ("Input should be a valid list", "应为列表"),
+    ("Input should be a valid date", "应为日期"),
+    ("Input should be a valid email address", "应为有效的邮箱地址"),
+    ("Input should be a valid URL", "应为有效的 URL"),
+    ("Field required", "缺少必填字段"),
+    ("Extra inputs are not permitted", "存在不允许的多余字段"),
+    ("Input should be greater than or equal to", "不能小于"),
+    ("Input should be less than or equal to", "不能大于"),
+    ("String should have at least 1 character", "内容不能为空"),
+    ("Input should be a valid enumeration value", "取值不在允许范围内"),
+    ("Unable to extract tag using discriminator", "数据结构与预期的不一致"),
+]
+
+
+def localize_pydantic_msg(msg: str) -> str:
+    """将一条 Pydantic 校验消息中的常见英文片段替换为中文。
+
+    Args:
+        msg: Pydantic 的 msg 字段原文
+
+    Returns:
+        本地化后的消息（未命中的片段保持原文）
+    """
+    for en, zh in _PATTERNS:
+        msg = msg.replace(en, zh)
+    return msg

app/shared/core/reporter/__init__.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 校验结果多渠道报告器模块包入口
+
+功能概述:
+- 提供数据校验结果的多渠道报告能力
+- 支持本地文件、邮件、企业微信、飞书、钉钉等多种报告渠道
+- 通过 ReportService 统一管理和调度所有报告器
+
+架构设计:
+- 策略模式 (Strategy Pattern): 各报告器继承自 Reporter 抽象基类，实现统一的 configure() 和 report() 接口
+- 注册表模式: ReportService 维护报告者注册表，根据配置动态激活对应的报告器
+- 统一入口: 外部通过 ReportService 调用，无需关心底层具体报告器的实现细节
+
+输入示例:
+    通过 ReportService 传入错误列表:
+    errors = [
+        {
+            "error_type": "TypeValidationError",
+            "row_index": 2,
+            "column": "age",
+            "value": "abc",
+            "error_message": "必须是整数"
+        }
+    ]
+
+输出示例:
+    各报告器将错误信息发送到对应渠道:
+    - 本地文件: 生成 JSON 日志文件到 logs/error_report_20240115_143052.json
+    - 邮件: 发送 HTML 格式邮件到指定收件箱
+    - 企业微信/飞书/钉钉: 推送 Markdown/卡片消息到对应应用
+"""