precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/constraints/scripted.py

@@ -0,0 +1,276 @@
+# 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 脚本化约束模块
+
+功能概述:
+- 实现 ScriptedConstraint 类
+- 通过 Python 表达式定义自定义验证逻辑
+- 允许执行复杂的业务规则验证
+
+架构设计:
+- 继承基类: 继承自 Constraint 抽象类
+- 安全控制: 需要显式开启 allow_unsafe_eval 才能执行
+- 表达式验证: 使用 simpleeval 库执行表达式，提供沙箱环境
+
+输入示例:
+    # 约束配置 - 验证手机号格式
+    constraint1 = ScriptedConstraint(
+        table="users",
+        name="valid_phone",
+        expression="re_match(r'^1[3-9]\\d{9}$', str(value))",
+        column="phone"
+    )
+
+    # 约束配置 - 验证复杂业务规则
+    constraint2 = ScriptedConstraint(
+        table="orders",
+        name="valid_discount",
+        expression="value <= row['total_amount'] * 0.5",
+        column="discount"
+    )
+
+输出示例:
+    # 验证失败
+    {
+        "errors": [
+            {
+                "error_type": "ScriptedConstraintViolation",
+                "table": "users",
+                "row_index": 0,
+                "column": "phone",
+                "value": "12345",
+                "message": "脚本约束冲突: 表达式 're_match(r'^1[3-9]\\d{9}$', str(value))' 验证失败。"
+            }
+        ],
+        "info": {...}
+    }
+
+原理说明:
+    表达式上下文:
+    - value: 当前单元格的值
+    - row: 当前行的数据 (字典形式)
+    - re_match: 正则匹配函数，接收 pattern 和 string，返回是否匹配
+    - len, sum, max, min 等基础函数
+
+    安全警告:
+    - 默认禁用脚本约束，需要设置 allow_unsafe_eval=True
+    - simpleeval 提供了比原生 eval() 更严格的沙箱环境
+    - 仍需谨慎使用，避免执行恶意代码
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+import logging
+import os
+import re
+import time
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_server_allow_unsafe_eval() -> bool:
+    """读取服务端总开关 PRECIS_ALLOW_UNSAFE_EVAL（启动时读一次，运行时不变）。
+
+    B-sec6: 取值 "1"/"true"/"yes"（不区分大小写）视为开启，其余（含未设置）视为关闭。
+    """
+    raw = os.environ.get("PRECIS_ALLOW_UNSAFE_EVAL", "").strip().lower()
+    return raw in ("1", "true", "yes")
+
+
+# 模块级缓存：进程启动时读一次，避免每行约束重复读环境变量。
+_SERVER_ALLOW_UNSAFE_EVAL: bool = _resolve_server_allow_unsafe_eval()
+
+# 2. 第三方库导入
+import numpy as np
+import pandas as pd
+from simpleeval import SimpleEval
+
+# 3. 项目内部导入
+from app.shared.domain.constraints.base import Constraint
+
+
+class ScriptedConstraint(Constraint):
+    """
+    @classdesc 脚本化约束
+
+    通过 Python 表达式定义自定义验证逻辑。
+    每行数据独立执行表达式，表达式返回 True 表示通过，False 表示失败。
+    """
+
+    def __init__(self, table: str, name: str, expression: str, column: str | None = None):
+        """
+        @methoddesc 初始化脚本化约束
+
+        参数:
+            table: 目标表名
+            name: 约束规则名称，用于错误消息中标识
+            expression: Python 表达式字符串，在每一行上执行
+            column: 目标列名，可选。如果指定，该列的值会作为 value 变量传入表达式
+        """
+        self.table = table
+        self.name = name
+        self.expression = expression
+        self.column = column
+
+    def _get_description(self) -> str:
+        """生成脚本约束描述"""
+        return f"脚本约束: {self.table}.{self.name}"
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """
+        @methoddesc 执行脚本化验证
+
+        参数:
+            datasets: 数据集字典，键为表名，值为 pandas DataFrame
+            **kwargs: 额外的关键字参数，必须包含 allow_unsafe_eval=True 才能执行
+
+        返回:
+            验证结果字典，包含 errors（错误列表）和 info（约束信息）
+
+        逻辑说明:
+            1. 检查 allow_unsafe_eval 是否开启，未开启则跳过
+            2. 检查目标表是否存在
+            3. 配置 simpleeval 沙箱环境，注册安全的基础函数
+            4. 遍历每一行数据，构建表达式执行上下文
+            5. 执行表达式并检查结果
+            6. 如果结果不是布尔值，记录定义错误
+            7. 如果结果为 False，记录业务逻辑违规
+            8. 如果表达式执行抛出异常，记录执行错误
+        """
+        errors: list[dict[str, Any]] = []
+
+        # 安全检查: 必须显式开启 allow_unsafe_eval 才能执行脚本约束
+        # 【安全加固】使用 is True 严格检查，防止 numpy bool 等意外 truthy 值绕过
+        #
+        # B-sec6: 请求体的 allow_unsafe_eval 不再单独决定执行权——叠加服务端总开关
+        # PRECIS_ALLOW_UNSAFE_EVAL（默认 False）。只有"服务端允许 AND 请求体也开启"
+        # 才真正执行。这样即便不可信客户端在请求体里设 true，服务端未授权时仍被拒。
+        # 读取缓存的模块级常量，避免每行重复读环境变量。
+        client_allowed = kwargs.get("allow_unsafe_eval") is True
+        if not (_SERVER_ALLOW_UNSAFE_EVAL and client_allowed):
+            errors.append(
+                {
+                    "error_type": "PermissionError",
+                    "table": self.table,
+                    "message": f"脚本约束「{self.name}」已跳过：项目设置中的『允许执行脚本 eval』尚未开启。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 检查目标表是否存在
+        if self.table not in datasets:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": f"脚本约束失败: 表 '{self.table}' 不在数据集中。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        df = datasets[self.table]
+
+        # ============================================================================
+        # 配置 simpleeval 沙箱环境
+        # ============================================================================
+        # B-sec5: 复用共享沙箱白名单（app.shared.domain.eval_sandbox），
+        # 与 MathExpr 转换保持单一事实源，避免两处白名单漂移。
+        from app.shared.domain.eval_sandbox import SAFE_FUNCTIONS
+
+        base_functions = dict(SAFE_FUNCTIONS)
+
+        # 遍历每一行数据执行表达式
+        # D6: deadline 检查点。逐行约束内部必须有中断点,否则百万行表跑几十秒,
+        # timeout_seconds 形同虚设(原 engine 只在约束之间检查)。每 200 行查一次(避免
+        # 每行调 time.monotonic 的开销),超时则中断循环并返回 Timeout 标记。
+        deadline = kwargs.get("deadline")
+        check_interval = 200
+        for i, (index, row_dict) in enumerate(df.to_dict("index").items()):
+            if deadline is not None and i % check_interval == 0 and time.monotonic() > deadline:
+                errors.append(
+                    {
+                        "error_type": "Timeout",
+                        "stage": "constraint",
+                        "table": self.table,
+                        "message": (f"脚本约束 '{self.name}' 执行超时,已在第 {i} 行中断,剩余 {len(df) - i} 行未校验。"),
+                    }
+                )
+                logger.warning(f"脚本约束 '{self.name}' 超时中断: 已处理 {i}/{len(df)} 行")
+                return {"errors": errors, "info": self.get_constraint_info()}
+            row_index = int(index) if index is not None else 0
+
+            # 获取当前单元格的值（如果指定了 column）
+            cell_value = row_dict.get(self.column) if self.column else None
+
+            # 创建 simpleeval 求值器，注入 row 和 value 变量
+            evaluator = SimpleEval(names={"row": row_dict, "value": cell_value})
+            # 注册基础函数
+            evaluator.functions.update(base_functions)
+            # 注册正则匹配函数 re_match(pattern, string)
+            # §1.9: 对齐 regex 约束 fullmatch 严格语义——原 re.match 是前缀匹配且 $ 容忍尾随换行，
+            # 同一模式在两套"匹配"下判定相反
+            evaluator.functions["re_match"] = lambda p, s: re.fullmatch(p, s) is not None
+
+            try:
+                # 执行表达式
+                result = evaluator.eval(self.expression)
+
+                # 检查结果类型: 必须是布尔值
+                if not isinstance(result, (bool, np.bool_)):
+                    errors.append(
+                        {
+                            "error_type": "ScriptCheckDefinitionError",
+                            "table": self.table,
+                            "row_index": int(row_index),
+                            "message": f"规则 '{self.name}' 的表达式没有返回布尔值(True/False),而是返回了 {type(result).__name__}。",
+                        }
+                    )
+                    continue
+
+                # 结果为 False 表示验证失败
+                if not bool(result):
+                    errors.append(
+                        {
+                            "error_type": "BusinessLogicViolation",
+                            "table": self.table,
+                            "row_index": int(row_index),
+                            "value": f"整行数据: {row_dict}",
+                            "message": f"业务逻辑检查失败: '{self.name}'",
+                        }
+                    )
+            except Exception as e:
+                # 表达式执行过程中抛出异常
+                # 记录详细异常信息到日志，但向用户返回脱敏后的通用错误消息
+                logger.warning(
+                    f"脚本约束执行错误: 规则='{self.name}', 表='{self.table}', "
+                    f"行={row_index}, 表达式='{self.expression}', 错误={e}",
+                    exc_info=True,
+                )
+                errors.append(
+                    {
+                        "error_type": "ScriptCheckExecutionError",
+                        "table": self.table,
+                        "row_index": int(row_index),
+                        "message": f"执行规则 '{self.name}' 时发生错误，请检查表达式语法或数据类型。",
+                        "expression": self.expression,
+                    }
+                )
+
+        return {"errors": errors, "info": self.get_constraint_info()}

app/shared/domain/constraints/unique.py

@@ -0,0 +1,233 @@
+# 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 唯一性约束模块
+
+功能概述:
+- 实现 UniqueConstraint 类
+- 验证列或列组合的值是否唯一
+- 支持单列唯一和联合唯一 (多列组合唯一)
+
+架构设计:
+- 继承基类: 继承自 Constraint 抽象类
+- 联合唯一: 支持多列组合的唯一性检查
+- 重复检测: 使用 pandas duplicated() 方法
+
+输入示例:
+    # 约束配置 - 单列唯一
+    constraint1 = UniqueConstraint(table="users", column="email")
+
+    # 约束配置 - 联合唯一
+    constraint2 = UniqueConstraint(
+        table="orders",
+        columns=["user_id", "product_id"]  # 同一用户对同一产品只能下一单
+    )
+
+    # 数据集输入
+    datasets = {
+        "users": DataFrame({
+            "id": [1, 2, 3],
+            "email": ["alice@test.com", "bob@test.com", "alice@test.com"]  # 重复 email
+        }),
+        "orders": DataFrame({
+            "id": [1, 2, 3],
+            "user_id": [1, 1, 1],
+            "product_id": [100, 100, 100]  # 重复 (user_id, product_id) 组合
+        })
+    }
+
+输出示例:
+    # 单列唯一性验证失败 (第3行 email 重复)
+    {
+        "errors": [
+            {
+                "error_type": "UniqueViolation",
+                "table": "users",
+                "row_index": 2,
+                "columns": ["email"],
+                "value": "alice@test.com",
+                "message": "唯一性冲突: 值 'alice@test.com' 在列 'email' 中不唯一。"
+            }
+        ],
+        "info": {...}
+    }
+
+    # 联合唯一性验证失败 (第2、3行重复)
+    {
+        "errors": [
+            {
+                "error_type": "UniqueViolation",
+                "table": "orders",
+                "row_index": 1,
+                "columns": ["user_id", "product_id"],
+                "value": {"user_id": 1, "product_id": 100},
+                "message": "唯一性冲突: 值 '{'user_id': 1, 'product_id': 100}' 在列 'user_id, product_id' 中不唯一。"
+            }
+        ],
+        "info": {...}
+    }
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+from typing import Any
+
+# 2. 第三方库导入
+import pandas as pd
+
+# 3. 项目内部导入
+from app.shared.domain.constraints.base import Constraint
+
+
+class UniqueConstraint(Constraint):
+    """
+    @classdesc 唯一性约束
+
+    验证指定列或列组合中的值是否唯一。
+    支持单列唯一（如 email 不重复）和联合唯一（如 user_id + product_id 组合不重复）。
+    """
+
+    def __init__(self, table: str, column: str | list[str]):
+        """
+        @methoddesc 初始化唯一性约束
+
+        参数:
+            table: 目标表名
+            column: 目标列名，可以是字符串（单列）或字符串列表（联合唯一）
+
+        抛出:
+            ValueError: 当 table 为空、column 为空或列表中包含空值时抛出
+        """
+        if not table or not table.strip():
+            raise ValueError("table 不能为空")
+
+        # 统一将 column 转为列表，方便后续处理
+        if isinstance(column, str):
+            if not column.strip():
+                raise ValueError("column 不能为空")
+            columns = [column]
+        else:
+            if not column:
+                raise ValueError("column 列表不能为空")
+            if not all(c and c.strip() for c in column):
+                raise ValueError("column 列表中包含空值")
+            columns = list(column)
+
+        self.table = table
+        self.columns = columns
+
+    def _get_description(self) -> str:
+        """生成唯一性约束描述"""
+        columns_str = ", ".join(self.columns) if isinstance(self.columns, list) else self.columns
+        return f"唯一性约束: {self.table}.{columns_str}"
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """
+        @methoddesc 执行唯一性验证
+
+        参数:
+            datasets: 数据集字典，键为表名，值为 pandas DataFrame
+            **kwargs: 额外的关键字参数（本方法不使用）
+
+        返回:
+            验证结果字典，包含 errors（错误列表）和 info（约束信息）
+
+        逻辑说明:
+            1. 检查目标表是否存在于数据集中
+            2. 检查 columns 列表是否为空
+            3. 检查每个列是否都存在于目标表中
+            4. 使用 pandas duplicated() 找出重复的行（keep=False 表示所有重复行都标记）
+            5. 为每个重复行生成错误记录
+        """
+        errors: list[dict[str, Any]] = []
+
+        # 检查目标表是否存在
+        if self.table not in datasets:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.columns[0] if self.columns else None,
+                    "message": f"唯一约束失败: 表 '{self.table}' 不在提供的数据集中。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        df = datasets[self.table]
+
+        # 检查是否指定了列
+        if not self.columns:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": None,
+                    "message": "唯一约束配置错误: 未指定任何列。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 检查每个列是否存在于表中
+        for col in self.columns:
+            if col not in df.columns:
+                errors.append(
+                    {
+                        "error_type": "ConstraintConfigError",
+                        "table": self.table,
+                        "column": col,
+                        "message": f"唯一约束失败: 列 '{col}' 在表 '{self.table}' 中不存在。",
+                    }
+                )
+                return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 使用 duplicated() 找出重复的行
+        # keep=False 表示将所有重复的行都标记为重复（包括第一次出现的）
+        # 回归 #4 修复:SQL 及主流数据质量工具的唯一性语义豁免 NULL。原实现裸调用
+        # duplicated(keep=False) 会把 NaN 视为彼此相等,可空唯一列的多个空值全部误报
+        # UniqueViolation: 值 'None' 不唯一。这里先剔除"任一唯一列含空值"的行,
+        # 使空值组合不再参与重复判定(与 SQL 行为一致)。
+        # 空字符串口径对齐: NotNull 与各 process_column 均把 ""/"  " 视为空,
+        # 唯一约束若把空串当普通值会与其打架(同列一处报"为空"一处报"不唯一")。
+        # 故空/全空白字符串同样豁免唯一性判定。astype(str) 对数值列不会产生空串,无副作用。
+        null_mask = df[self.columns].isna().any(axis=1)
+        blank_mask = (
+            df[self.columns].apply(lambda col: col.map(lambda v: isinstance(v, str) and v.strip() == "")).any(axis=1)
+        )
+        df_non_null = df[~(null_mask | blank_mask)]
+        duplicates = df_non_null[df_non_null.duplicated(subset=self.columns, keep=False)]
+
+        # 遍历所有重复行，生成错误记录
+        for row_tuple in duplicates[self.columns].itertuples(index=True, name=None):
+            index = row_tuple[0]
+            # 如果是多列联合唯一，value 用字典表示；如果是单列，直接用值
+            if len(self.columns) > 1:
+                value = dict(zip(self.columns, row_tuple[1:]))
+            else:
+                value = row_tuple[1]
+            row_index = int(index) if index is not None else 0
+            errors.append(
+                {
+                    "error_type": "UniqueViolation",
+                    "table": self.table,
+                    "row_index": row_index,
+                    "columns": self.columns,
+                    "value": value,
+                    "message": f"唯一性冲突: 值 '{value}' 在列 '{', '.join(self.columns)}' 中不唯一。",
+                }
+            )
+
+        return {"errors": errors, "info": self.get_constraint_info()}