precis-cli 0.1.3__py3-none-any.whl

app/shared/services/validation/validators/composite.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 复合约束校验器模块
+
+功能概述:
+- 将多个子约束按逻辑策略（all/any/none）聚合校验结果
+- 通过构造函数注入 validate_fn 回调，调用 UnifiedValidationService 为每个子约束执行校验
+- 避免直接实例化 CompositeConstraint 所需的 create_constraint 工厂 + schema_files 依赖
+
+架构设计:
+- 继承 BaseValidator，遵循统一校验器接口
+- 通过构造函数注入 validate_fn 回调，消除循环依赖
+- 每个子约束独立执行，异常被捕获视为该子约束失败
+
+输入示例:
+    CompositeValidator(validate_fn=UnifiedValidationService.validate).validate(
+        df=df,
+        column="email",
+        logic="all",
+        sub_constraints=[
+            {"type": "NotNull", "enabled": True, "params": {}},
+            {"type": "Unique", "enabled": True, "params": {}},
+        ]
+    )
+
+输出示例:
+    ValidationResult(
+        is_valid=False,
+        error_count=2,
+        total_rows=100,
+        error_rows=[...]
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+import pandas as pd
+
+from ..types import ValidationResult, ValidationType
+from .base import BaseValidator
+
+logger = logging.getLogger(__name__)
+
+
+class CompositeValidator(BaseValidator):
+    """@classdesc 复合约束校验器
+
+    接收子约束配置列表，为每个子约束调用注入的 validate_fn 执行校验，
+    然后按 logic 策略（all/any/none）聚合最终结果。
+
+    字段说明:
+        - logic: 聚合策略 ("all" | "any" | "none")
+        - sub_constraints: 子约束配置列表，每项包含 type/enabled/params
+    """
+
+    def __init__(self, validate_fn: Callable | None = None):
+        """@methoddesc 初始化复合约束校验器
+
+        参数:
+            validate_fn: 校验回调函数，签名为 (validation_type, df, column, **kwargs) -> ValidationResult
+                         在 service.py 注册时注入，避免循环依赖
+        """
+        self._validate_fn = validate_fn
+
+    def validate(self, df: pd.DataFrame, column: str, **kwargs: Any) -> ValidationResult:
+        """@methoddesc 执行复合约束校验
+
+        遍历所有子约束配置，逐个调用注入的 validate_fn 执行校验，
+        收集结果后按 logic 策略聚合。
+
+        参数:
+            df: 待校验的 DataFrame
+            column: 待校验的列名
+            **kwargs:
+                - logic: 聚合策略，默认 "all"
+                - sub_constraints: 子约束配置列表
+
+        返回:
+            ValidationResult: 标准化校验结果
+        """
+        validate_fn = self._validate_fn
+        if validate_fn is None:
+            logger.error("CompositeValidator 未注入 validate_fn，无法执行子约束校验")
+            return self._format_errors([], len(df), 0)
+
+        logic = kwargs.get("logic", "all")
+        sub_configs = kwargs.get("sub_constraints", [])
+
+        # 空子约束视为通过
+        if not sub_configs:
+            return self._format_errors([], len(df), 0)
+
+        start_time = time.time()
+        all_errors: list[dict] = []
+        passed_count = 0
+        processed_count = 0
+        # 回归 D7: 收集未知子约束类型,上报为配置错误(而非静默跳过判通过)
+        unknown_types: list[str] = []
+
+        # 前端传来的类型名 -> ValidationType 常量映射
+        # 支持多种命名风格：NotNull / notnull / not_null
+        type_map = {
+            "notnull": ValidationType.NOT_NULL,
+            "not_null": ValidationType.NOT_NULL,
+            "unique": ValidationType.UNIQUE,
+            "range": ValidationType.RANGE,
+            "allowedvalues": ValidationType.ALLOWED_VALUES,
+            "allowed_values": ValidationType.ALLOWED_VALUES,
+            "charset": ValidationType.CHARSET,
+            "regex": ValidationType.REGEX,
+            "scripted": ValidationType.SCRIPTED,
+            "foreignkey": ValidationType.FOREIGN_KEY,
+            "foreign_key": ValidationType.FOREIGN_KEY,
+            "conditional": ValidationType.CONDITIONAL,
+            "datelogic": ValidationType.DATE_LOGIC,
+            "date_logic": ValidationType.DATE_LOGIC,
+        }
+
+        for cfg in sub_configs:
+            # 跳过未启用的子约束
+            if not cfg.get("enabled", True):
+                continue
+
+            sub_type_raw = str(cfg.get("type", "")).lower().replace(" ", "")
+            validation_type = type_map.get(sub_type_raw)
+            if not validation_type:
+                # 回归 D7: 未知类型不再静默跳过,收集后上报配置错误
+                logger.warning(f"Composite 中遇到不支持的子约束类型: {sub_type_raw}")
+                unknown_types.append(sub_type_raw)
+                continue
+
+            try:
+                result = validate_fn(
+                    validation_type=validation_type,
+                    df=df,
+                    column=column,
+                    **cfg.get("params", {}),
+                )
+                processed_count += 1
+                if result.is_valid:
+                    passed_count += 1
+                else:
+                    all_errors.extend(result.error_rows)
+            except Exception as e:
+                logger.warning(f"Composite 子约束校验异常 ({validation_type}): {e}")
+                # 子约束异常视为失败：计入 processed_count（防止"全部异常"落入下方
+                # processed_count==0 的空子约束分支被误判为通过），并生成占位错误行
+                # 参与 logic 聚合——all 语义下异常必须使整条约束失败。
+                processed_count += 1
+                sub_label = getattr(validation_type, "value", validation_type)
+                all_errors.append(
+                    {
+                        "row_index": 0,
+                        "cell_value": None,
+                        "error_message": f"子约束 {sub_label} 执行异常: {e}",
+                    }
+                )
+
+        # 回归 D7: 存在未知子约束类型时上报配置错误,避免用户以为约束生效了实际全被跳过
+        if unknown_types:
+            config_errors = [
+                {
+                    "row_index": 0,
+                    "cell_value": None,
+                    "error_message": (
+                        f"复合约束包含不支持的子约束类型: {', '.join(unknown_types)};这些子约束未执行校验。"
+                    ),
+                }
+            ]
+            return self._format_errors(config_errors, len(df), time.time() - start_time)
+
+        # 如果没有成功处理的子约束，视为通过（避免空子约束报错）
+        if processed_count == 0:
+            return self._format_errors([], len(df), time.time() - start_time)
+
+        # 根据 logic 策略决定最终错误列表
+        final_errors: list[dict] = []
+
+        if logic == "all":
+            # 所有子约束都必须通过：返回所有错误的并集
+            final_errors = all_errors
+
+        elif logic == "any":
+            # 至少一个子约束通过即算通过
+            if passed_count == 0:
+                final_errors = [
+                    {
+                        "row_index": 0,
+                        "cell_value": None,
+                        "error_message": (
+                            f"复合约束（logic=any）要求至少一个子约束通过，但全部 {processed_count} 个子约束均失败"
+                        ),
+                    }
+                ]
+
+        elif logic == "none":
+            # 所有子约束都必须失败才算通过（反向校验）
+            if passed_count > 0:
+                final_errors = [
+                    {
+                        "row_index": 0,
+                        "cell_value": None,
+                        "error_message": (
+                            f"复合约束（logic=none）要求全部子约束失败，但有 {passed_count} 个子约束通过"
+                        ),
+                    }
+                ]
+
+        else:
+            # 未知逻辑策略，回退到 all 行为
+            logger.warning(f"Composite 遇到未知的 logic 策略: {logic}，回退到 all")
+            final_errors = all_errors
+
+        return self._format_errors(final_errors, len(df), time.time() - start_time)

app/shared/services/validation/validators/date_logic.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 日期逻辑校验器
+
+功能概述:
+- 对日期类型数据进行逻辑校验和计算验证
+- 支持日期比较(大于、小于、等于、范围)和日期计算(年龄、天数差)
+
+架构设计:
+- 委托模式: 将校验逻辑委托给 DateLogicConstraint 模型类处理
+- 复用机制: 使用基础校验器的错误格式化方法
+- 临时表映射: 将 DataFrame 映射为临时表 "temp" 供约束模型使用
+"""
+
+import time
+from datetime import datetime
+from typing import Any
+
+import pandas as pd
+
+from app.shared.domain import DateLogicConstraint
+
+from ..types import ValidationResult
+from .base import BaseValidator
+
+
+class DateLogicValidator(BaseValidator):
+    """
+    @classdesc 日期逻辑校验器
+
+    对日期类型数据进行多种逻辑校验和计算验证：
+    - 比较模式：验证日期与参考日期的大小关系（大于、小于、等于等）
+    - 计算模式：验证日期计算结果是否符合预期（年龄、天数差等）
+
+    设计原则：
+    - 委托设计：核心校验逻辑委托给 DateLogicConstraint 模型
+    - 统一接口：与其他校验器保持一致的 validate 方法签名
+    """
+
+    def validate(self, df: pd.DataFrame, column: str, **kwargs: Any) -> ValidationResult:
+        """
+        @methoddesc 执行日期逻辑校验
+
+        对 DataFrame 中指定列的日期数据进行逻辑校验。
+        支持两种模式：
+        - compare（比较模式）：验证日期与参考日期的大小关系
+        - calculation（计算模式）：验证日期计算结果（如年龄、天数差）
+
+        参数:
+            df: 待校验的 DataFrame 对象
+            column: 待校验的日期列名
+            **kwargs: 校验参数，包含:
+                - logic_mode: 逻辑模式，"compare" 或 "calculation"（默认 "compare"）
+                - compare_op: 比较操作符，"gt"/"lt"/"eq"/"gte"/"lte"/"range"（默认 "gt"）
+                - reference_date: 参考日期字符串，比较模式下的区间起点（可选）
+                - reference_column: 参考日期列名，比较模式下的区间起点（可选）
+                - reference_date_end: 区间终点固定日期，仅 range 模式使用（可选）
+                - reference_column_end: 区间终点列名，仅 range 模式使用（可选）
+                - calculation_type: 计算类型，"age" 或 "days_diff"（默认 "age"）
+                - target_value: 目标计算值（可选）
+                - target_column: 目标计算列（可选）
+
+        返回:
+            ValidationResult: 标准化校验结果
+        """
+        start_time = time.time()
+
+        # 提取校验参数
+        logic_mode = kwargs.get("logic_mode", "compare")
+        calculation_type = kwargs.get("calculation_type", "age")
+        # compare_op 默认值随计算类型调整：
+        # - age 模式默认 gte（满 N 岁即通过;回归 D2: 原默认 gt 会误判刚满 N 岁的边界）
+        # - days_diff 模式默认 eq（差值等于目标值通过;对账周期场景）
+        # - compare 模式默认 gt（与历史行为一致）
+        compare_op = kwargs.get("compare_op")
+        if compare_op is None:
+            if calculation_type == "days_diff":
+                compare_op = "eq"
+            elif calculation_type == "age":
+                compare_op = "gte"
+            else:
+                compare_op = "gt"
+        reference_date = kwargs.get("reference_date")
+        reference_column = kwargs.get("reference_column")
+        reference_date_end = kwargs.get("reference_date_end")
+        reference_column_end = kwargs.get("reference_column_end")
+        target_value = kwargs.get("target_value")
+        target_column = kwargs.get("target_column")
+
+        # 检查校验列是否存在
+        if column not in df.columns:
+            return ValidationResult(
+                is_valid=False,
+                error_count=1,
+                total_rows=len(df),
+                error_rows=[{"row_index": 0, "cell_value": None, "error_message": f"列 '{column}' 不存在"}],
+                validation_time=f"{time.time() - start_time:.3f}s",
+            )
+
+        # 检查参考列是否存在
+        if reference_column and reference_column not in df.columns:
+            return ValidationResult(
+                is_valid=False,
+                error_count=1,
+                total_rows=len(df),
+                error_rows=[
+                    {"row_index": 0, "cell_value": None, "error_message": f"参考列 '{reference_column}' 不存在"}
+                ],
+                validation_time=f"{time.time() - start_time:.3f}s",
+            )
+
+        # range 模式下检查终点参考列是否存在
+        if compare_op == "range" and reference_column_end and reference_column_end not in df.columns:
+            return ValidationResult(
+                is_valid=False,
+                error_count=1,
+                total_rows=len(df),
+                error_rows=[
+                    {"row_index": 0, "cell_value": None, "error_message": f"终点参考列 '{reference_column_end}' 不存在"}
+                ],
+                validation_time=f"{time.time() - start_time:.3f}s",
+            )
+
+        # 校验逻辑模式是否合法
+        if logic_mode not in ("compare", "calculation"):
+            return ValidationResult(
+                is_valid=False,
+                error_count=1,
+                total_rows=len(df),
+                error_rows=[
+                    {"row_index": 0, "cell_value": None, "error_message": f"不支持的日期逻辑模式: {logic_mode}"}
+                ],
+                validation_time=f"{time.time() - start_time:.3f}s",
+            )
+
+        # 校验计算模式下的目标值是否为有效数值
+        if logic_mode == "calculation" and target_value is not None:
+            try:
+                if calculation_type == "age":
+                    float(target_value)
+                elif calculation_type == "days_diff":
+                    int(target_value)
+            except (ValueError, TypeError):
+                type_name = "年龄" if calculation_type == "age" else "天数"
+                return ValidationResult(
+                    is_valid=False,
+                    error_count=1,
+                    total_rows=len(df),
+                    error_rows=[
+                        {
+                            "row_index": 0,
+                            "cell_value": None,
+                            "error_message": f"无效的目标{type_name}值: {target_value}，应为数值",
+                        }
+                    ],
+                    validation_time=f"{time.time() - start_time:.3f}s",
+                )
+
+        # 校验参考日期格式是否合法
+        if reference_date and self._parse_date(str(reference_date)) is None:
+            return ValidationResult(
+                is_valid=False,
+                error_count=1,
+                total_rows=len(df),
+                error_rows=[
+                    {"row_index": 0, "cell_value": None, "error_message": f"无效的参考日期格式: {reference_date}"}
+                ],
+                validation_time=f"{time.time() - start_time:.3f}s",
+            )
+
+        # range 模式下校验终点参考日期格式
+        if compare_op == "range" and reference_date_end and self._parse_date(str(reference_date_end)) is None:
+            return ValidationResult(
+                is_valid=False,
+                error_count=1,
+                total_rows=len(df),
+                error_rows=[
+                    {
+                        "row_index": 0,
+                        "cell_value": None,
+                        "error_message": f"无效的终点参考日期格式: {reference_date_end}",
+                    }
+                ],
+                validation_time=f"{time.time() - start_time:.3f}s",
+            )
+
+        # 预检查：向量化找出无法解析的日期。
+        # 严格保持 DATE_FORMATS 顺序（%d/%m/%Y 在 %m/%d/%Y 之前——歧义日期优先按日/月解析）。
+        # 对每种格式用 pd.to_datetime(errors="coerce") 尝试，取第一个非 NaT 结果。
+        series = df[column]
+        non_null_mask = series.notna() & (series != None)  # noqa: E711
+        str_series = series[non_null_mask].astype(str).str.strip()
+
+        # 逐格式解析：已解析的不再尝试后续格式（保持 DATE_FORMATS 优先级）
+        parsed_mask = pd.Series(False, index=str_series.index)
+        for fmt in self.DATE_FORMATS:
+            remaining = ~parsed_mask
+            if not remaining.any():
+                break
+            try:
+                candidate = pd.to_datetime(str_series[remaining], format=fmt, errors="coerce")
+                parsed_mask = parsed_mask | candidate.notna()
+            except (ValueError, TypeError):
+                continue
+
+        # 未解析的即为无法解析的日期
+        unparseable_idx = str_series.index[~parsed_mask]
+        unparseable_errors = [
+            {"row_index": idx, "value": str(series[idx]), "message": f"无法解析日期: {series[idx]}"}
+            for idx in unparseable_idx
+        ]
+
+        # 如果存在无法解析的日期，直接返回错误结果
+        if unparseable_errors:
+            return self._format_errors(unparseable_errors, len(df), time.time() - start_time)
+
+        # 创建日期逻辑约束对象并委托校验
+        constraint = DateLogicConstraint(
+            table="temp",
+            column=column,
+            logic_mode=logic_mode,
+            compare_op=compare_op,
+            reference_date=reference_date,
+            reference_column=reference_column,
+            reference_date_end=reference_date_end,
+            reference_column_end=reference_column_end,
+            calculation_type=calculation_type,
+            target_value=target_value,
+            target_column=target_column,
+        )
+        return self._delegate_validation(df, column, constraint)
+
+    DATE_FORMATS = [
+        "%Y-%m-%d",
+        "%Y/%m/%d",
+        "%Y年%m月%d日",
+        "%d/%m/%Y",
+        "%m/%d/%Y",
+        "%Y-%m-%d %H:%M:%S",
+        "%Y/%m/%d %H:%M:%S",
+    ]
+
+    @classmethod
+    def _parse_date(cls, date_str: str) -> datetime | None:
+        """
+        @methoddesc 解析日期字符串
+
+        尝试使用预定义的多种日期格式解析字符串。
+
+        参数:
+            date_str: 日期字符串
+
+        返回:
+            解析成功的 datetime 对象，失败则返回 None
+        """
+        date_str = str(date_str).strip()
+        for fmt in cls.DATE_FORMATS:
+            try:
+                return datetime.strptime(date_str, fmt)
+            except ValueError:
+                continue
+        return None

app/start_server.py

@@ -0,0 +1,133 @@
+# 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 Precis 后端服务启动脚本
+
+功能概述:
+- 后端启动的统一入口,被 Electron 桌面应用与 Web 开发模式(npm run dev)共用
+- 端口由 OS 原子分配(默认 port=0),通过 ``.backend-port`` 文件向外部发布实际端口
+- 支持自定义端口(固定端口逃生舱)与热重载(开发模式)
+
+使用方式:
+    python app/start_server.py                 # OS 动态分配端口(Electron 用)
+    python app/start_server.py --reload        # 开发模式热重载(npm run dev / backend:dev 用)
+    python app/start_server.py --port 18000    # 固定端口(向后兼容)
+"""
+
+import os
+
+# 禁止生成 Python 字节码文件（__pycache__ 和 .pyc）
+os.environ.setdefault("PYTHONDONTWRITEBYTECODE", "1")
+
+import argparse
+import logging
+import sys
+
+# 添加项目根目录（backend/）到 Python 路径
+# 由于脚本位于 backend/app/ 下，需要上溯两级到 backend/
+project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+
+import uvicorn
+
+from app.shared.core.config.server import (
+    DEFAULT_BACKEND_HOST,
+    acquire_port,
+    clear_port_file,
+    register_port_file_cleanup,
+    resolve_port,
+    write_port_file,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    """
+    主函数 - 解析命令行参数并启动 Uvicorn 服务器
+
+    端口策略:
+    - 默认 port=0 由 OS 动态分配(永不冲突),实际端口写入 .backend-port
+    - 显式 --port 或 VITE_BACKEND_PORT 环境变量可固定端口(向后兼容)
+    """
+    # 创建命令行参数解析器
+    parser = argparse.ArgumentParser(description="Precis Backend Server", prog="start_server")
+
+    # 添加端口参数
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="服务器监听端口 (默认: 0=OS 动态分配;可通过 VITE_BACKEND_PORT 固定端口)",
+    )
+
+    # 添加主机参数
+    parser.add_argument(
+        "--host", type=str, default=DEFAULT_BACKEND_HOST, help=f"服务器监听地址 (默认: {DEFAULT_BACKEND_HOST})"
+    )
+
+    # 添加热重载参数(开发模式用,Electron 生产模式不启用)
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="启用文件变更热重载(仅开发模式使用)",
+    )
+
+    # 解析参数
+    args = parser.parse_args()
+
+    # 解析端口:CLI 参数 > 环境变量 > 默认 0(OS 动态分配)
+    preferred_port = resolve_port(args.port)
+    # 获取实际可监听端口(OS 原子分配,无竞态)
+    actual_port = acquire_port(preferred_port)
+
+    # 将实际端口写入端口文件,供 Vite 代理 / Electron 主进程发现
+    write_port_file(actual_port)
+
+    # 通过环境变量把实际端口传递给 uvicorn --reload 派生的 app 子进程。
+    # app.api.main 在每次(重)启动时会据此重写端口文件 —— 否则任何其他
+    # Precis 进程退出清理端口文件后,本进程虽存活但发现方读到缺失,代理 502。
+    os.environ["PRECIS_BACKEND_PORT_ACTUAL"] = str(actual_port)
+
+    # 注册端口文件清理兜底(atexit + signal),Windows 下 uvicorn 的信号处理可能绕过 finally
+    register_port_file_cleanup()
+
+    # 打印启动信息
+    logger.info("[INIT] Precis Backend 启动中...")
+    logger.info("[INIT] 监听地址: %s:%s", args.host, actual_port)
+    logger.info("[INIT] Python 版本: %s", sys.version)
+
+    try:
+        # 启动 Uvicorn 服务器
+        # app.api.main:app 指向 FastAPI 应用实例
+        uvicorn.run(
+            "app.api.main:app",
+            host=args.host,
+            port=actual_port,
+            log_level="info",
+            # 热重载:开发模式 --reload 启用,Electron 生产模式关闭
+            reload=args.reload,
+            # 启用访问日志
+            access_log=True,
+        )
+    finally:
+        # 无论正常退出还是异常中断,都清理端口文件,避免残留误导外部发现方
+        clear_port_file()
+
+
+if __name__ == "__main__":
+    main()