precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/constraints/allowed_values.py

@@ -0,0 +1,211 @@
+# 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 允许值约束模块
+
+功能概述:
+- 实现 AllowedValuesConstraint 类
+- 验证列的值是否在允许的集合内
+
+架构设计:
+- 继承基类: 继承自 Constraint 抽象类
+- 集合验证: 使用 pandas isin() 方法检测非法值
+- 空值处理: 自动排除空值，不视为违规
+
+输入示例:
+    # 约束配置
+    constraint = AllowedValuesConstraint(
+        table="users",
+        column="status",
+        allowed_values={"active", "inactive", "pending"}
+    )
+
+    # 数据集输入
+    datasets = {
+        "users": DataFrame({
+            "id": [1, 2, 3, 4],
+            "status": ["active", "active", "pending", "deleted"]  # "deleted" 不在允许值中
+        })
+    }
+
+输出示例:
+    # 验证通过
+    {"errors": [], "info": {...}}
+
+    # 验证失败 (第4行 status 为 "deleted")
+    {
+        "errors": [
+            {
+                "error_type": "AllowedValuesViolation",
+                "table": "users",
+                "row_index": 3,
+                "column": "status",
+                "value": "deleted",
+                "message": "允许值约束冲突: 值 'deleted' 不在允许的集合 {'active', 'inactive', 'pending'} 中。"
+            }
+        ],
+        "info": {...}
+    }
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+import difflib
+from decimal import Decimal
+from typing import Any
+
+# 2. 第三方库导入
+import pandas as pd
+
+# 3. 项目内部导入
+from app.shared.domain.constraints.base import Constraint
+from app.shared.domain.constraints.key_normalization import integral_number_to_str
+
+
+class AllowedValuesConstraint(Constraint):
+    """
+    @classdesc 允许值约束
+
+    验证指定列中的每个值是否都存在于预定义的允许值集合中。
+    常用于枚举类型字段的校验，如状态码、性别、类型等。
+    """
+
+    def __init__(self, table: str, column: str, allowed_values: set[Any]):
+        """
+        @methoddesc 初始化允许值约束
+
+        参数:
+            table: 目标表名
+            column: 目标列名
+            allowed_values: 允许值的集合，列中的值必须属于此集合
+
+        抛出:
+            ValueError: 当 allowed_values 为空集合、table 为空或 column 为空时抛出
+        """
+        if not allowed_values:
+            raise ValueError("allowed_values 不能为空集合")
+
+        if not table or not table.strip():
+            raise ValueError("table 不能为空")
+
+        if not column or not column.strip():
+            raise ValueError("column 不能为空")
+
+        self.table = table
+        self.column = column
+        self.allowed_values = allowed_values
+
+    def _get_description(self) -> str:
+        """生成约束描述，如果允许值过多则只显示前5个"""
+        values_str = (
+            str(self.allowed_values) if len(self.allowed_values) <= 5 else f"{list(self.allowed_values)[:5]}..."
+        )
+        return f"允许值约束: {self.table}.{self.column} 允许值 {values_str}"
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """
+        @methoddesc 执行允许值验证
+
+        参数:
+            datasets: 数据集字典，键为表名，值为 pandas DataFrame
+            **kwargs: 额外的关键字参数（本方法不使用）
+
+        返回:
+            验证结果字典，包含 errors（错误列表）和 info（约束信息）
+
+        逻辑说明:
+            1. 检查目标表是否存在于数据集中
+            2. 检查目标列是否存在于目标表中
+            3. 使用 pandas 的 isin() 找出不在允许值集合中的行
+            4. 排除空值（空值不视为违规）
+            5. 为每个违规行生成错误记录
+        """
+        errors: list[dict[str, Any]] = []
+
+        # 步骤1: 检查目标表是否存在
+        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]
+
+        # 步骤2: 检查目标列是否存在
+        if self.column not in df.columns:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": f"允许值约束失败: 列 '{self.column}' 在表 '{self.table}' 中不存在。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 步骤3: 找出不在允许值集合中的行，同时排除空值
+        # 回归 D5: YAML 常以字符串配置枚举(前端下拉),但数值列解析后是 int,1 != "1" 导致
+        # isin 全 False → 全行误报。这里把列值与允许值都归一为字符串后再比较,使 "1" 与 1 等价。
+        # 修复: 含空值的整数列经 IntegerType.process_column 的 where(~failed, None) 后整列升为
+        # float64(1 → 1.0),astype(str) 得 "1.0" 与枚举 {"1","2"} 不匹配 → 合法值全列误报。
+        # 对 is_integer() 的 float 回收为整数字符串后再比较(与 scalars._to_int_str 同语义)。
+        # §1.11: Decimal 整数值(Decimal("1.0"))同样规整为整数字符串(对齐 FK 侧归一),
+        # 消除 decimal 列配 [1,2,3] 枚举时 "1.0" vs "1" 的整列误报。
+        def _norm_to_str(v: Any) -> str:
+            if isinstance(v, (float, Decimal)):
+                integral = integral_number_to_str(v)
+                if integral is not None:
+                    return integral
+            return str(v)
+
+        col_series = df[self.column]
+        # §1.4: 空串口径统一为"缺失值豁免"（推广 NotNull/Unique 现状）——全空白串不参与
+        # 枚举判定，"空串是否合法值"只由 NotNull 负责。数值列 astype(str) 不产生空串，无副作用。
+        non_null_mask = col_series.notna() & ~(col_series.astype(str).str.strip() == "")
+        # 仅对非空值做字符串化比较(NaN 已被 non_null_mask 排除,不参与 isin 判定)
+        str_col = col_series.map(_norm_to_str)
+        str_allowed = {_norm_to_str(v) for v in self.allowed_values}
+        invalid_mask = non_null_mask & ~str_col.isin(str_allowed)
+        invalid_rows = df[invalid_mask]
+
+        # 步骤4: 遍历所有违规行，生成错误记录
+        for row_tuple in invalid_rows[[self.column]].itertuples(index=True, name=None):
+            index = row_tuple[0]
+            value = row_tuple[1]
+            row_index = int(index) if index is not None else 0
+            error: dict[str, Any] = {
+                "error_type": "AllowedValuesViolation",
+                "table": self.table,
+                "row_index": row_index,
+                "column": self.column,
+                "value": value,
+                "message": f"允许值约束冲突: 值 '{value}' 不在允许的集合 {self.allowed_values} 中。",
+            }
+            # suggestion（可选）：值与某允许值高度相近时给"是否应为"提示，
+            # 支撑"修数据还是调规则"的判断；无明显相近项不给（宁缺毋滥）
+            close = difflib.get_close_matches(_norm_to_str(value), sorted(str_allowed), n=1, cutoff=0.6)
+            if close:
+                orig = next((v for v in self.allowed_values if _norm_to_str(v) == close[0]), close[0])
+                error["suggestion"] = f"值 '{value}' 与允许值 '{orig}' 相近，是否应为它？"
+            errors.append(error)
+
+        return {"errors": errors, "info": self.get_constraint_info()}

app/shared/domain/constraints/base.py

@@ -0,0 +1,141 @@
+# 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 约束抽象基类模块
+
+功能概述:
+- 定义所有约束类型的抽象基类 (Constraint)
+- 提供统一的约束接口和方法
+
+架构设计:
+- 抽象基类: 定义 validate() 抽象方法
+- 子类实现: 每个具体约束类型实现自己的验证逻辑
+- 信息获取: 提供 get_constraint_info() 获取约束元信息
+
+输入示例:
+    # datasets 输入 (多个 DataFrame 的字典)
+    datasets = {
+        "users": DataFrame({
+            "id": [1, 2, 3],
+            "username": ["alice", "bob", None],
+            "email": ["alice@test.com", "bob@test.com", "charlie@test.com"]
+        }),
+        "orders": DataFrame({
+            "id": [1, 2, 3],
+            "user_id": [1, 2, 1]
+        })
+    }
+
+输出示例:
+    # validate() 返回结果
+    {
+        "errors": []
+    }
+
+    # 或验证失败
+    {
+        "errors": [
+            {"row": 2, "column": "username", "message": "列 'username' 不能为空"}
+        ]
+    }
+
+    # get_constraint_info() 返回结果
+    {
+        "constraint_type": "NotNullConstraint",
+        "table": "users",
+        "description": "NotNull 约束"
+    }
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+from abc import ABC, abstractmethod
+from typing import Any
+
+# 2. 第三方库导入
+import pandas as pd
+
+
+class Constraint(ABC):
+    """
+    @classdesc 约束抽象基类
+
+    所有约束类的基类，定义统一的约束接口。
+    子类必须实现 validate() 方法，用于执行具体的验证逻辑。
+    """
+
+    @abstractmethod
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """
+        @methoddesc 执行约束验证
+
+        抽象方法，子类必须实现具体的验证逻辑。
+
+        Args:
+            datasets: 数据集字典，键为表名，值为对应的 pandas DataFrame。
+                      包含验证所需的全部数据，子类从中读取目标表进行校验。
+            **kwargs: 额外的关键字参数，供子类按需使用。
+                      例如：上下文信息、配置参数等。
+
+        Returns:
+            验证结果字典，通常包含以下字段:
+                - errors: 错误列表，每个元素是一个描述错误的字典，包含 row、column、message 等键
+                - info: 约束的基本信息（通过 get_constraint_info() 获取）
+
+        Raises:
+            子类实现中可根据需要抛出异常，但推荐将错误收集到 errors 列表中返回。
+
+        注意:
+            子类必须重写此方法，否则无法实例化。
+        """
+
+        pass
+
+    def get_constraint_info(self) -> dict[str, Any]:
+        """
+        @methoddesc 获取约束的基本信息
+
+        返回约束的类型、作用表和描述等元信息，用于日志记录和错误报告。
+
+        Returns:
+            包含以下字段的字典:
+                - constraint_type: 约束类名
+                - table: 约束作用的表名（优先取 self.table，否则取 self.from_table）
+                - description: 约束的描述信息
+        """
+
+        # 构建约束元信息字典
+        # table 字段的取值优先级：self.table > self.from_table > None
+        # 不同约束子类可能使用不同属性名存储目标表名，此处做兼容处理
+        return {
+            "constraint_type": self.__class__.__name__,
+            "table": getattr(self, "table", getattr(self, "from_table", None)),
+            "description": self._get_description(),
+        }
+
+    def _get_description(self) -> str:
+        """
+        @methoddesc 获取约束的描述信息
+
+        默认实现返回 "{类名} 约束"，子类可重写以提供更具体的描述。
+
+        Returns:
+            约束的描述字符串
+        """
+
+        # 默认描述格式：直接使用类名拼接，子类可覆盖以提供业务语义更明确的描述
+        return f"{self.__class__.__name__} 约束"

app/shared/domain/constraints/charset.py

@@ -0,0 +1,337 @@
+# 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 字符集约束模块
+
+功能概述:
+- 实现 CharsetConstraint 类
+- 验证指定列的值是否符合指定的字符集编码要求
+- 支持 ASCII 和中文两种模式
+
+架构设计:
+- 继承基类: 继承自 Constraint 抽象类
+- 模式匹配: 针对不同字符集模式实现专用检测方法
+- Unicode 范围: 使用 Unicode 码点范围判断字符类型
+
+输入示例:
+    # 约束配置
+    constraint = CharsetConstraint(
+        table="users",
+        column="username",
+        charset_mode="ascii"  # 或 "chinese"
+    )
+
+    # 数据集输入
+    datasets = {
+        "users": DataFrame({
+            "id": [1, 2, 3],
+            "username": ["alice", "bob", "张三"]  # "张三" 不符合 ASCII
+        })
+    }
+
+输出示例:
+    # 验证通过
+    {
+        "errors": [],
+        "info": {
+            "constraint_type": "CharsetConstraint",
+            "table": "users",
+            "description": "字符集约束: users.username (ASCII)"
+        }
+    }
+
+    # 验证失败 (第3行 username 为中文)
+    {
+        "errors": [
+            {
+                "error_type": "CharsetViolation",
+                "table": "users",
+                "row_index": 2,
+                "column": "username",
+                "value": "张三",
+                "message": "字符集约束冲突: 值 '张三' 包含非ASCII字符。"
+            }
+        ],
+        "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 CharsetConstraint(Constraint):
+    """
+    @classdesc 字符集约束
+
+    验证数据列中的值是否符合指定的字符集编码要求。
+    支持 ASCII(纯英文字符)、中文(纯中文字符)和中文混合(CJK + ASCII 字母/数字/常见标点)三种模式。
+
+    业务场景:
+    - 用户名、账号等字段要求纯 ASCII 字符
+    - 姓名、地址等字段要求纯中文字符
+    - 说明、备注等字段允许中文与英文数字及常见标点混合
+    """
+
+    # 中文混合模式下允许的 ASCII 常见标点符号
+    _CHINESE_MIXED_PUNCTUATION = frozenset(" .,;:!?()[]{}'\"`-_/\\@#$%&*+=<>|~^")
+
+    def __init__(self, table: str, column: str, charset_mode: str = "ascii", description: str | None = None):
+        """
+        @methoddesc 初始化字符集约束
+
+        参数:
+            table: 目标表名
+            column: 目标列名
+            charset_mode: 字符集模式，可选 "ascii" 或 "chinese"，默认为 "ascii"
+            description: 自定义描述信息，可选
+        """
+        self.table = table
+        self.column = column
+        self.charset_mode = charset_mode
+        self.description = description
+
+    def _get_description(self) -> str:
+        """根据字符集模式生成描述字符串"""
+        if self.description:
+            return self.description
+        charset_name_map = {
+            "ascii": "ASCII",
+            "chinese": "中文",
+            "chinese_mixed": "中文混合",
+        }
+        charset_name = charset_name_map.get(self.charset_mode, "未知")
+        return f"字符集约束: {self.table}.{self.column} ({charset_name})"
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """
+        @methoddesc 执行字符集验证
+
+        参数:
+            datasets: 数据集字典，键为表名，值为 pandas DataFrame
+            **kwargs: 额外的关键字参数（本方法不使用）
+
+        返回:
+            验证结果字典，包含 errors（错误列表）和 info（约束信息）
+
+        逻辑说明:
+            1. 检查目标表是否存在
+            2. 检查目标列是否存在
+            3. 遍历该列的每个非空值
+            4. 调用 _check_charset() 检查值是否符合指定字符集
+            5. 为每个不符合的值生成错误记录
+        """
+        errors: list[dict[str, Any]] = []
+
+        # 检查目标表是否存在
+        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]
+
+        # 检查目标列是否存在
+        if self.column not in df.columns:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": f"字符集约束失败: 列 '{self.column}' 在表 '{self.table}' 中不存在。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 根据模式确定显示名称（用于错误消息）
+        charset_name_map = {
+            "ascii": "ASCII",
+            "chinese": "中文",
+            "chinese_mixed": "中文混合",
+        }
+        charset_name = charset_name_map.get(self.charset_mode, self.charset_mode)
+
+        # 回归 D3: 未识别的 charset_mode 必须报配置错误。原实现 _check_charset 对未识别
+        # mode 返回 True → 约束永远通过、零提示,用户以为字符集被强制了实际没有(拼错如
+        # chinese_mix 静默失效)。合法模式集合与 _check_charset 的分支保持一致。
+        valid_modes = {"ascii", "chinese", "chinese_mixed"}
+        if self.charset_mode not in valid_modes:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": (
+                        f"字符集约束配置错误: 未知的字符集模式 '{self.charset_mode}',"
+                        f"支持的模式为: {', '.join(sorted(valid_modes))}。"
+                    ),
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 遍历该列所有值，逐行检查
+        for row_tuple in df[[self.column]].itertuples(index=True, name=None):
+            index = row_tuple[0]
+            cell_value = row_tuple[1]
+
+            # 跳过空值（NaN 或 None），空值不视为字符集违规
+            if pd.isna(cell_value) or cell_value is None:
+                continue
+
+            # 将值转换为字符串进行检查
+            cell_value_str = str(cell_value)
+            if not cell_value_str:
+                continue
+
+            # 检查是否符合指定字符集
+            is_valid = self._check_charset(cell_value_str, self.charset_mode)
+            if not is_valid:
+                errors.append(
+                    {
+                        "error_type": "CharsetViolation",
+                        "table": self.table,
+                        "row_index": int(index) if index is not None else 0,
+                        "column": self.column,
+                        "value": cell_value_str,
+                        "message": f"字符集约束冲突: 值 '{cell_value_str}' 包含非{charset_name}字符。",
+                    }
+                )
+
+        return {"errors": errors, "info": self.get_constraint_info()}
+
+    def _check_charset(self, value: str, mode: str) -> bool:
+        """
+        检查字符串是否符合指定字符集
+
+        参数:
+            value: 要检查的字符串
+            mode: 字符集模式，"ascii"、"chinese" 或 "chinese_mixed"
+
+        返回:
+            True 表示符合指定字符集，False 表示不符合
+        """
+        if mode == "ascii":
+            return self._is_ascii(value)
+        elif mode == "chinese":
+            return self._is_chinese(value)
+        elif mode == "chinese_mixed":
+            return self._is_chinese_mixed(value)
+        return True
+
+    def _is_ascii(self, value: str) -> bool:
+        """
+        检查字符串是否为纯 ASCII 字符
+
+        原理: 尝试用 ASCII 编码对字符串进行编码，如果成功则说明是纯 ASCII。
+        如果包含非 ASCII 字符（如中文），则会抛出 UnicodeEncodeError。
+
+        参数:
+            value: 要检查的字符串
+
+        返回:
+            True 表示纯 ASCII，False 表示包含非 ASCII 字符
+        """
+        try:
+            value.encode("ascii")
+            return True
+        except UnicodeEncodeError:
+            return False
+
+    def _is_chinese_char(self, char: str) -> bool:
+        """判断单个字符是否属于中文相关 Unicode 区块（CJK 及中文标点）。"""
+        if "\u4e00" <= char <= "\u9fff":
+            return True
+        if "\u3400" <= char <= "\u4dbf":
+            return True
+        # §1.22: CJK 兼容表意文字区（Big5/GB 遗留编码转换产物常见），
+        # 原判定缺失导致该区汉字被整列报"包含非中文字符"
+        if "\uf900" <= char <= "\ufaff":
+            return True
+        if "\U00020000" <= char <= "\U0002a6df":
+            return True
+        if "\U0002a700" <= char <= "\U0002b73f":
+            return True
+        if "\U0002b740" <= char <= "\U0002b81f":
+            return True
+        if "\U0002b820" <= char <= "\U0002ceaf":
+            return True
+        if "\u3000" <= char <= "\u303f":
+            return True
+        if "\uff00" <= char <= "\uffef":
+            return True
+        return False
+
+    def _is_chinese(self, value: str) -> bool:
+        """
+        检查字符串是否为纯中文字符
+
+        原理: 遍历字符串中的每个字符，检查其 Unicode 码点是否落在
+        中日韩统一表意文字（CJK）及其扩展区、以及中文标点符号的范围内。
+
+        支持的 Unicode 区块:
+            - \u4e00-\u9fff: 基本汉字
+            - \u3400-\u4dbf: 扩展A区
+            - \U00020000-\U0002a6df: 扩展B区
+            - \U0002a700-\U0002b73f: 扩展C区
+            - \U0002b740-\U0002b81f: 扩展D区
+            - \U0002b820-\U0002ceaf: 扩展E区
+            - \u3000-\u303f: 中文标点符号（CJK Symbols and Punctuation）
+            - \uff00-\uffef: 全角字符（Halfwidth and Fullwidth Forms）
+
+        参数:
+            value: 要检查的字符串
+
+        返回:
+            True 表示所有字符都在中文相关 Unicode 区块内，False 表示包含其他字符
+        """
+        for char in value:
+            if not self._is_chinese_char(char):
+                return False
+        return len(value) > 0
+
+    def _is_chinese_mixed(self, value: str) -> bool:
+        """
+        检查字符串是否为中文混合字符
+
+        允许 CJK 中文相关字符，以及 ASCII 字母、数字和常见标点符号。
+
+        参数:
+            value: 要检查的字符串
+
+        返回:
+            True 表示符合中文混合字符集，False 表示包含其他字符
+        """
+        for char in value:
+            if self._is_chinese_char(char):
+                continue
+            if char.isascii() and (char.isalnum() or char in self._CHINESE_MIXED_PUNCTUATION):
+                continue
+            return False
+        return len(value) > 0