precis-cli 0.1.3__py3-none-any.whl

app/shared/services/validation/service.py

@@ -0,0 +1,418 @@
+# 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 统一校验服务模块
+
+功能概述:
+- 提供所有数据校验的统一入口 UnifiedValidationService
+- 采用注册表模式管理校验器,支持动态注册和获取
+- 模块加载时自动注册所有内置校验器
+- 支持 REGEX、UNIQUE、NOT_NULL、ALLOWED_VALUES、RANGE、FOREIGN_KEY 等校验类型
+- 统一的 ValidationResult 返回格式简化调用方处理
+
+架构设计:
+- 注册表模式(Registry Pattern): 解耦校验器与调用方
+- 类方法实现: register_validator、get_validator、validate 均为类方法
+- 校验器在模块导入时自动注册,服务立即可用
+- 新增校验器只需注册,无需修改核心服务代码
+
+输入示例:
+    import pandas as pd
+    df = pd.DataFrame({
+        "email": ["test@example.com", "invalid-email", "user@domain.com"]
+    })
+    result = UnifiedValidationService.validate(
+        validation_type="regex",
+        df=df,
+        column="email",
+        regex_pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
+    )
+
+输出示例:
+    ValidationResult(
+        is_valid=False,
+        error_count=1,
+        total_rows=3,
+        error_rows=[
+            {"row_index": 1, "cell_value": "invalid-email",
+             "error_message": "值不符合正则表达式模式"}
+        ],
+        validation_time="0.015s"
+    )
+"""
+
+import logging
+from typing import Any
+
+import pandas as pd
+
+from .types import ValidationResult, ValidationType
+
+logger = logging.getLogger(__name__)
+
+from app.shared.domain.constraints.allowed_values import AllowedValuesConstraint
+from app.shared.domain.constraints.charset import CharsetConstraint
+from app.shared.domain.constraints.conditional import ConditionalConstraint
+from app.shared.domain.constraints.foreign_key import ForeignKeyConstraints
+from app.shared.domain.constraints.not_null import NotNullConstraint
+from app.shared.domain.constraints.range import RangeConstraint
+from app.shared.domain.constraints.regex import RegexConstraint
+from app.shared.domain.constraints.scripted import ScriptedConstraint
+from app.shared.domain.constraints.unique import UniqueConstraint
+
+from .validators.adapter import ConstraintAdapter, PreCheck
+from .validators.base import BaseValidator
+from .validators.composite import CompositeValidator
+from .validators.date_logic import DateLogicValidator
+
+
+class UnifiedValidationService:
+    r"""
+    @classdesc 统一校验服务类 - 提供所有数据校验的统一入口
+
+    本服务采用注册表模式（Registry Pattern）：
+    - _validators: 校验器注册表，键为校验类型，值为校验器实例
+    - register_validator: 动态注册新的校验器
+    - get_validator: 根据校验类型获取对应的校验器
+    - validate: 执行校验的核心方法
+
+    为什么采用注册表模式？
+    1. 解耦：新增校验器不需要修改核心服务代码
+    2. 可扩展：运行时可以动态注册新的校验器
+    3. 可测试：可以轻松替换为 Mock 对象进行单元测试
+
+    使用示例：
+        # 正则表达式校验
+        result = UnifiedValidationService.validate(
+            validation_type="regex",
+            df=dataframe,
+            column="email",
+            regex_pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
+        )
+
+        # 唯一性校验
+        result = UnifiedValidationService.validate(
+            validation_type="unique",
+            df=dataframe,
+            column="user_id"
+        )
+
+        # 非空校验
+        result = UnifiedValidationService.validate(
+            validation_type="not_null",
+            df=dataframe,
+            column="name"
+        )
+    """
+
+    # _validators: 校验器注册表
+    # 键：校验类型字符串（如 "regex", "unique"）
+    # 值：对应的校验器实例（BaseValidator 子类）
+    # 生命周期：应用启动时注册（模块底部），验证时查询
+    # 【关键数据流】所有校验请求都通过此字典路由到具体校验器
+    _validators: dict[str, BaseValidator] = {}
+
+    @classmethod
+    def register_validator(cls, validation_type: str, validator: BaseValidator) -> None:
+        """
+        @methoddesc 注册校验器到统一服务
+
+        允许在运行时动态添加新的校验器，支持插件化扩展，
+        便于测试时替换为 Mock 对象。
+
+        参数:
+            validation_type: 校验类型标识符（对应 ValidationType 常量）
+            validator: 校验器实例（需继承自 BaseValidator）
+
+        副作用:
+            将校验器添加到 _validators 字典
+        """
+        cls._validators[validation_type] = validator
+
+    @classmethod
+    def get_validator(cls, validation_type: str) -> BaseValidator | None:
+        """
+        @methoddesc 获取指定类型的校验器
+
+        本方法是校验流程的路由核心，根据 validation_type 查找对应校验器。
+
+        参数:
+            validation_type: 校验类型标识符
+
+        返回:
+            校验器实例，未找到返回 None
+        """
+        return cls._validators.get(validation_type)
+
+    @classmethod
+    def validate(cls, validation_type: str, df: pd.DataFrame, column: str, **kwargs: Any) -> ValidationResult:
+        """
+        @methoddesc 执行数据校验 - 统一入口方法
+
+        调用方无需关心具体校验器的实现细节，只需传入校验类型和相关参数，
+        返回结果格式统一，便于处理。
+
+        参数:
+            validation_type: 校验类型（如 "regex", "unique", "range"）
+            df: 待校验的 DataFrame
+            column: 待校验的列名
+            **kwargs: 校验器所需的额外参数
+                - regex: regex_pattern, regex_flags, match_mode
+                - range: min_value, max_value, boundary_mode
+                - allowed_values: allowed_values
+                - foreign_key: target_table, target_column, target_values
+                - 等等...
+
+        返回:
+            ValidationResult: 包含校验是否通过、错误数量、错误详情等信息
+
+        错误处理:
+            如果校验器不存在，返回 is_valid=False 的结果
+
+        性能考虑:
+            校验器从注册表获取是 O(1) 操作
+        """
+        # Step 1: 获取校验器
+        # 【关键路由】根据 validation_type 从注册表获取对应校验器
+        validator = cls.get_validator(validation_type)
+
+        # Step 2: 校验器不存在时返回错误结果
+        # 【副作用】返回错误结果，调用方可通过 is_valid=False 判断
+        if not validator:
+            logger.warning(f"不支持的校验类型: {validation_type}")
+            return ValidationResult(
+                is_valid=False,
+                error_count=1,
+                total_rows=len(df),
+                error_rows=[
+                    {"row_index": 0, "cell_value": None, "error_message": f"不支持的校验类型: {validation_type}"}
+                ],
+                validation_time="0.000s",
+            )
+
+        # Step 3: 执行实际校验
+        # 【核心逻辑】调用具体校验器的 validate 方法
+        # 传入 df, column 和 kwargs（包含各类校验参数）
+        logger.debug(f"执行校验: type={validation_type}, column={column}, rows={len(df)}")
+        result = validator.validate_with_error_handling(df, column, **kwargs)
+        logger.debug(f"校验完成: is_valid={result.is_valid}, errors={result.error_count}")
+        return result
+
+
+# 模块初始化时注册所有内置校验器
+# 【副作用】模块导入时自动执行，完成后服务即可用
+#
+# 注册策略:
+# - ConstraintAdapter: 通过适配器配置消除独立 Validator 文件
+#   支持预检、参数映射、自定义 datasets 和错误格式化
+# - DateLogicValidator: 保留独立实现（日期预扫描逻辑过于特殊）
+# - CompositeValidator: 元验证器，递归调用 UnifiedValidationService.validate
+
+
+def _not_null_formatter(err: dict) -> dict:
+    return {
+        "row_index": err.get("row_index"),
+        "cell_value": None,
+        "error_message": err.get("message"),
+    }
+
+
+def _conditional_kwargs_builder(column: str, kwargs: dict) -> dict:
+    if_conditions = kwargs.get("if_conditions") or []
+    then_condition = kwargs.get("then_condition") or kwargs.get("then_condition_config")
+    if if_conditions:
+        return {
+            "table": "temp",
+            "if_conditions": if_conditions,
+            "if_logic": kwargs.get("if_logic", "and"),
+            "then_column": column,
+            "then_condition": then_condition,
+        }
+    return {
+        "table": "temp",
+        "if_column": kwargs.get("if_column", ""),
+        "if_value": kwargs.get("if_value"),
+        "then_column": column,
+        "then_condition": then_condition,
+    }
+
+
+def _conditional_pre_check(df: pd.DataFrame, column: str, kwargs: dict) -> str | None:
+    then_condition = kwargs.get("then_condition") or kwargs.get("then_condition_config")
+    if not then_condition:
+        return "条件校验配置不完整"
+    if_conditions = kwargs.get("if_conditions") or []
+    if not if_conditions and not kwargs.get("if_column"):
+        return "条件校验配置不完整"
+    return None
+
+
+def _conditional_error_formatter(err: dict) -> dict:
+    return {
+        "row_index": err.get("row_index"),
+        "cell_value": err.get("value"),
+        "error_message": err.get("message"),
+    }
+
+
+def _fk_kwargs_builder(column: str, kwargs: dict) -> dict:
+    return {
+        "from_table": "temp",
+        "from_column": column,
+        "to_table": "target",
+        "to_column": kwargs.get("target_column"),
+    }
+
+
+def _fk_datasets_builder(df: pd.DataFrame, column: str, kwargs: dict) -> dict:
+    target_column = kwargs.get("target_column")
+    target_df = pd.DataFrame({target_column: kwargs.get("target_values", [])})
+    return {"temp": df, "target": target_df}
+
+
+def _fk_pre_check(df: pd.DataFrame, column: str, kwargs: dict) -> str | None:
+    if not kwargs.get("target_table") or not kwargs.get("target_column"):
+        return "外键校验缺少目标表或目标列配置"
+    # target_values 缺失（键不存在或为 None）属于配置不完整：若按空目标表处理，
+    # 所有行都会被误报为外键冲突（数据错误），误导用户去修数据而非修配置。
+    # 注意区分：显式传入空列表 [] 是合法语义（目标表确认为空 → 全部冲突）。
+    if kwargs.get("target_values") is None:
+        return "外键校验缺少目标值列表（target_values）"
+    if column not in df.columns:
+        return f"列 '{column}' 不存在"
+    return None
+
+
+def _scripted_kwargs_builder(column: str, kwargs: dict) -> dict:
+    return {
+        "table": "temp",
+        "name": kwargs.get("script_name", "custom_script"),
+        "expression": kwargs.get("script", ""),
+        "column": column,
+    }
+
+
+def _scripted_error_formatter(err: dict) -> dict:
+    row_index = err.get("row_index")
+    if row_index is None:
+        row_index = 0
+    try:
+        row_index = int(row_index)
+    except (TypeError, ValueError):
+        row_index = 0
+    return {
+        "row_index": row_index,
+        "cell_value": str(err.get("value", "")),
+        "error_message": err.get("message", ""),
+    }
+
+
+# --- ConstraintAdapter 注册 ---
+
+UnifiedValidationService.register_validator(
+    ValidationType.UNIQUE,
+    ConstraintAdapter(UniqueConstraint, column_param="column"),
+)
+
+UnifiedValidationService.register_validator(
+    ValidationType.NOT_NULL,
+    ConstraintAdapter(NotNullConstraint, column_param="column", error_formatter=_not_null_formatter),
+)
+
+UnifiedValidationService.register_validator(
+    ValidationType.ALLOWED_VALUES,
+    ConstraintAdapter(
+        AllowedValuesConstraint,
+        column_param="column",
+        kwargs_mapping={"allowed_values": "allowed_values"},
+    ),
+)
+
+UnifiedValidationService.register_validator(
+    ValidationType.RANGE,
+    ConstraintAdapter(
+        RangeConstraint,
+        column_param="column",
+        kwargs_mapping={"min_value": "min_value", "max_value": "max_value", "boundary_mode": "boundary_mode"},
+    ),
+)
+
+UnifiedValidationService.register_validator(
+    ValidationType.REGEX,
+    ConstraintAdapter(
+        RegexConstraint,
+        column_param="column",
+        kwargs_mapping={
+            "regex_pattern": "pattern",
+            "regex_flags": "flags",
+            "match_mode": "match_mode",
+            "case_sensitive": "case_sensitive",
+        },
+        pre_checks=[PreCheck.column_exists(), PreCheck.param_required("regex_pattern")],
+    ),
+)
+
+UnifiedValidationService.register_validator(
+    ValidationType.FOREIGN_KEY,
+    ConstraintAdapter(
+        ForeignKeyConstraints,
+        column_param="from_column",
+        kwargs_builder=_fk_kwargs_builder,
+        datasets_builder=_fk_datasets_builder,
+        pre_checks=[_fk_pre_check],
+    ),
+)
+
+UnifiedValidationService.register_validator(
+    ValidationType.CONDITIONAL,
+    ConstraintAdapter(
+        ConditionalConstraint,
+        column_param="then_column",
+        kwargs_builder=_conditional_kwargs_builder,
+        pre_checks=[_conditional_pre_check],
+        error_formatter=_conditional_error_formatter,
+    ),
+)
+
+UnifiedValidationService.register_validator(
+    ValidationType.SCRIPTED,
+    ConstraintAdapter(
+        ScriptedConstraint,
+        column_param="column",
+        kwargs_builder=_scripted_kwargs_builder,
+        pre_checks=[PreCheck.param_required("script")],
+        error_formatter=_scripted_error_formatter,
+        constraint_kwargs_keys=["allow_unsafe_eval"],
+    ),
+)
+
+UnifiedValidationService.register_validator(
+    ValidationType.CHARSET,
+    ConstraintAdapter(
+        CharsetConstraint,
+        column_param="column",
+        kwargs_mapping={"charset_mode": "charset_mode"},
+        pre_checks=[PreCheck.column_exists()],
+    ),
+)
+
+# --- 独立 Validator 注册 ---
+
+UnifiedValidationService.register_validator(ValidationType.DATE_LOGIC, DateLogicValidator())
+
+UnifiedValidationService.register_validator(
+    ValidationType.COMPOSITE, CompositeValidator(validate_fn=UnifiedValidationService.validate)
+)

app/shared/services/validation/types.py

@@ -0,0 +1,238 @@
+# 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 校验类型定义模块
+
+功能概述:
+- 定义 ValidationType 校验类型常量类,涵盖所有支持的校验规则
+- 定义 ValidationResult 校验结果数据类,统一校验返回格式
+- 支持 REGEX、UNIQUE、NOT_NULL、ALLOWED_VALUES、RANGE、FOREIGN_KEY 等类型
+- 所有校验结果字段均为可选,支持渐进式填充
+
+架构设计:
+- ValidationType 采用字符串常量类模式,便于 JSON 序列化和前端使用
+- ValidationResult 采用数据类模式,提供清晰的校验结果封装
+- 常量类设计便于扩展新类型,无需修改枚举定义
+
+输入示例:
+    # ValidationType 常量
+    validation_type = ValidationType.REGEX  # "regex"
+
+    # ValidationResult 对象
+    result = ValidationResult(
+        is_valid=True,
+        error_count=0,
+        total_rows=100,
+        match_count=100,
+        error_rows=[],
+        validation_time="0.023s"
+    )
+
+输出示例:
+    # 校验失败时的错误详情
+    error_rows = [
+        {
+            "row_index": 5,
+            "cell_value": "invalid",
+            "error_message": "值不符合正则表达式模式"
+        }
+    ]
+"""
+
+
+class ValidationType:
+    """
+    @classdesc 校验类型枚举类
+
+    定义系统支持的所有数据校验规则类型。每个类型对应一种特定的数据验证逻辑，
+    可通过 UnifiedValidationService 注册相应的验证器实现。
+
+    为什么要定义这些类型？
+    - 提供类型安全的校验类型标识
+    - 集中管理所有支持的校验类型，便于扩展
+    - 前端可通过字符串类型选择校验方式
+
+    扩展方式：
+    1. 在此类中添加新的类型常量
+    2. 在 service.py 中实现对应的验证器类
+    3. 在验证器工厂中注册新验证器
+    """
+
+    # 正则表达式校验：验证数据是否符合指定的正则表达式模式
+    # 适用场景：邮箱、手机号、身份证号等格式验证
+    # 示例：验证 email 列是否符合邮箱格式 r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
+    REGEX = "regex"
+
+    # 唯一性校验：验证列中是否存在重复值
+    # 适用场景：主键、用户名、订单号等必须唯一的字段
+    # 示例：验证 user_id 列的所有值是否唯一
+    UNIQUE = "unique"
+
+    # 非空校验：验证单元格是否为必填项
+    # 适用场景：必填字段的强制性检查
+    # 示例：验证 name 列是否存在空值
+    NOT_NULL = "not_null"
+
+    # 允许值校验：验证数据是否在预定义的允许值列表中
+    # 适用场景：状态字段、类型字段等有限取值范围的验证
+    # 示例：验证 status 列是否在 ["active", "inactive", "pending"] 中
+    ALLOWED_VALUES = "allowed_values"
+
+    # 范围校验：验证数值或日期是否在指定范围内
+    # 适用场景：年龄、分数、日期区间等边界值验证
+    # 示例：验证 age 列是否在 0-150 范围内
+    RANGE = "range"
+
+    # 外键校验：验证数据是否引用了另一个表中的有效记录
+    # 适用场景：关联数据完整性验证
+    # 示例：验证 user_id 列的值是否在 users 表的 id 列中存在
+    FOREIGN_KEY = "foreign_key"
+
+    # 条件校验：根据条件表达式动态决定校验规则
+    # 适用场景：复杂业务规则验证
+    # 示例：当 status="vip" 时，discount 必须 <= 500
+    CONDITIONAL = "conditional"
+
+    # 脚本校验：使用自定义脚本进行复杂业务逻辑验证
+    # 适用场景：标准校验器无法满足的自定义规则
+    # 示例：验证 total == price * quantity
+    SCRIPTED = "scripted"
+
+    # 字符集校验：验证字符串是否符合特定字符集要求
+    # 适用场景：纯中文名、纯 ASCII 用户名等
+    # 示例：验证 name 列是否只包含中文字符
+    CHARSET = "charset"
+
+    # 日期逻辑校验：验证日期之间的逻辑关系（如开始日期早于结束日期）
+    # 适用场景：日期大小关系、年龄计算等
+    # 示例：验证 birth_date 是否在 2000-01-01 之前
+    DATE_LOGIC = "date_logic"
+
+    # 复合约束校验：将多个子约束按逻辑策略聚合校验
+    # 适用场景：需要同时满足多个条件的复杂业务规则
+    # 示例：验证 email 既非空又唯一
+    COMPOSITE = "composite"
+
+
+class ValidationResult:
+    """
+    @classdesc 校验结果数据类
+
+    封装数据校验的执行结果，包含校验状态、错误统计和详细信息。
+    该类用于统一各类型校验器的返回格式，便于调用方统一处理。
+
+    数据流说明：
+    调用方接收 ValidationResult 后，通常执行以下判断：
+    1. 检查 is_valid 布尔值（推荐）
+    2. 检查 error_count 数量
+    3. 遍历 error_rows 获取详细错误信息
+
+    Attributes:
+        is_valid: 校验是否通过，True 表示所有数据均符合规则
+        error_count: 错误行数，即不符合校验规则的记录数量
+        total_rows: 总行数，即被校验的数据总行数
+        match_count: 匹配行数，适用于唯一性等需要统计匹配数量的校验
+        error_rows: 错误详情列表，每项包含行索引、单元格值和错误信息
+        validation_time: 校验耗时，格式为秒（如 "0.123s"）
+    """
+
+    def __init__(
+        self,
+        is_valid: bool,
+        error_count: int,
+        total_rows: int,
+        match_count: int | None = None,
+        error_rows: list[dict] | None = None,
+        validation_time: str = "0.000s",
+    ):
+        """
+        @methoddesc 初始化校验结果实例
+
+        Args:
+            is_valid: 校验是否通过
+                - True: 所有数据符合规则，error_count 应为 0
+                - False: 存在不符合规则的数据
+            error_count: 错误行数统计
+                - 为 0 时表示校验通过
+                - 大于 0 时表示存在错误
+            total_rows: 被校验数据的总行数
+                - 用于计算错误率
+                - 前端可显示 "错误行数/总行数"
+            match_count: 匹配行数（可选）
+                - 仅在唯一性校验时有意义
+                - 表示符合规则的数据行数
+                - 计算公式：total_rows - error_count
+            error_rows: 错误详情列表（可选）
+                - 每个元素包含 row_index、cell_value、error_message
+                - 默认为空列表，避免空引用异常
+            validation_time: 校验耗时字符串（可选）
+                - 格式为 "0.123s"（3位小数）
+                - 用于性能监控和用户等待提示
+        """
+        # 校验是否通过标记
+        # 【副作用】调用方通常首先检查此字段判断校验状态
+        self.is_valid = is_valid
+
+        # 错误行数统计
+        # 【关键数据流】error_count > 0 时，is_valid 应为 False
+        self.error_count = error_count
+
+        # 总行数
+        # 【用途】前端显示进度、计算错误率
+        self.total_rows = total_rows
+
+        # 匹配行数（可选）
+        # 【用途】唯一性校验时显示唯一值数量
+        self.match_count = match_count
+
+        # 错误行详情列表，使用 or [] 处理 None 传入，避免后续遍历时空引用异常
+        # 【关键数据流】包含错误位置的详细信息，供前端定位问题
+        self.error_rows = error_rows or []
+
+        # 校验耗时
+        # 【副作用】可能用于性能监控和 UI 加载提示
+        self.validation_time = validation_time
+
+
+# ==============================================================================
+# ValidationResult 使用示例
+# ==============================================================================
+# 示例 1: 校验通过
+# result = ValidationResult(
+#     is_valid=True,
+#     error_count=0,
+#     total_rows=100,
+#     match_count=100,
+#     error_rows=[],
+#     validation_time="0.023s"
+# )
+# 解读：100 行数据全部通过校验，耗时 23 毫秒
+#
+# 示例 2: 校验失败
+# result = ValidationResult(
+#     is_valid=False,
+#     error_count=3,
+#     total_rows=100,
+#     match_count=97,
+#     error_rows=[
+#         {"row_index": 5, "cell_value": "invalid_email", "error_message": "值 'invalid_email' 不符合正则表达式模式"},
+#         {"row_index": 15, "cell_value": "bad@format", "error_message": "值 'bad@format' 不符合正则表达式模式"},
+#         {"row_index": 88, "cell_value": "no_at_symbol", "error_message": "值 'no_at_symbol' 不符合正则表达式模式"}
+#     ],
+#     validation_time="0.015s"
+# )
+# 解读：100 行数据中有 3 行校验失败，分别在第 5、15、88 行
+# ==============================================================================

app/shared/services/validation/validators/__init__.py

@@ -0,0 +1,36 @@
+# 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 校验器模块入口
+
+功能概述:
+- 导出所有内置数据校验器实现
+- ConstraintAdapter 通用适配器替代大部分独立 Validator 文件
+- DateLogicValidator 和 CompositeValidator 保留独立实现
+"""
+
+from .adapter import ConstraintAdapter, PreCheck
+from .base import BaseValidator
+from .composite import CompositeValidator
+from .date_logic import DateLogicValidator
+
+__all__ = [
+    "BaseValidator",
+    "ConstraintAdapter",
+    "PreCheck",
+    "CompositeValidator",
+    "DateLogicValidator",
+]