precis-cli 0.1.3__py3-none-any.whl

app/shared/core/reporter/reporter.py

@@ -0,0 +1,220 @@
+# 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 统一管理和调度所有激活的报告者策略
+- 支持本地文件、邮件、企业微信、飞书、钉钉等多种报告渠道
+- 从 YAML 配置文件读取报告器配置，动态加载和初始化
+
+架构设计:
+- 注册表模式: _reporter_registry 将配置名称映射到具体报告器类
+- 配置驱动: 通过 reporting_config.yaml 控制启用哪些报告器
+- 全局配置注入: 自动将全局配置（如 log_dir）合并到各报告器的配置中
+- 故障隔离: 单个报告器配置失败不影响其他报告器的正常工作
+
+输入示例:
+    YAML 配置文件 (reporting_config.yaml):
+    reporters:
+      local_file:
+        enabled: true
+      email:
+        enabled: true
+        smtp_server: "smtp.example.com"
+        smtp_port: 587
+        sender_email: "precis@example.com"
+        sender_password: "secret"
+        receiver_email: "admin@example.com"
+
+    调用代码:
+    report_service = ReportService(base_dir="/path/to/project")
+    report_service.report(errors)
+
+输出示例:
+    控制台输出:
+    报告服务已初始化。
+    正在配置报告者: 'local_file'...
+    [LocalFileReporter] 日志目录已创建: /path/to/project/logs
+    正在配置报告者: 'email'...
+    [EmailReporter] ✓ 邮件服务配置验证成功，发件人: precis@example.com
+    报告服务配置完成，共激活 2 个报告者。
+    --- 开始报告 5 个错误 ---
+    [LocalFileReporter] ✓ 成功将错误报告写入本地日志: ...
+    [EmailReporter] ✓ 成功发送错误报告邮件至 admin@example.com。
+    --- 报告流程结束 ---
+"""
+
+import json
+import logging
+import os
+from collections.abc import Callable
+
+import yaml
+
+from .reporters import (
+    DingTalkAppReporter,
+    EmailReporter,
+    FeishuReporter,
+    LocalFileReporter,
+    Reporter,
+    WeComAppReporter,
+)
+
+logger = logging.getLogger(__name__)
+
+# ==============================================================================
+# 报告服务中心
+# ==============================================================================
+
+
+class ReportService:
+    """
+    @classdesc 报告服务中心类。
+
+    负责管理和调度所有激活的报告者策略。
+    在初始化时从配置文件加载需要启用的报告者，
+    在报告时将错误信息发送给所有激活的报告者。
+
+    【属性说明】
+    - base_dir: 项目根目录路径
+    - config_path: 报告配置文件完整路径
+    - _reporter_registry: 报告者注册表（名称到类的映射）
+    - _active_reporters: 已激活的报告者实例列表
+
+    【使用示例】
+    >>> report_service = ReportService(base_dir='/path/to/project')
+    >>> errors = [{'error_type': 'ValidationError', 'message': '数据校验失败'}]
+    >>> report_service.report(errors)
+    """
+
+    def __init__(self, base_dir: str, config_filename: str = "reporting_config.yaml"):
+        """
+        初始化报告服务中心。
+
+        【初始化流程】
+        1. 设置项目根目录和配置文件路径
+        2. 初始化报告者注册表
+        3. 调用 _load_and_configure_reporters 加载配置
+
+        :param base_dir: 项目根目录路径
+        :param config_filename: 配置文件名，默认 'reporting_config.yaml'
+        """
+        self.base_dir = base_dir
+        self.config_path = os.path.join(base_dir, config_filename)
+
+        # 报告者注册表：将配置中的名称映射到对应的报告者类
+        self._reporter_registry: dict[str, Callable[[], Reporter]] = {
+            "local_file": LocalFileReporter,
+            "email": EmailReporter,
+            "wecom": WeComAppReporter,
+            "feishu": FeishuReporter,
+            "dingtalk": DingTalkAppReporter,
+        }
+
+        # 激活的报告者实例列表
+        self._active_reporters: list[Reporter] = []
+        logger.info("报告服务已初始化。")
+        self._load_and_configure_reporters()
+
+    def _load_and_configure_reporters(self) -> None:
+        """
+        @methoddesc 从配置文件加载并配置所有需要启用的报告者。
+
+        【处理流程】
+        1. 检查配置文件是否存在
+        2. 读取并解析 YAML 配置文件
+        3. 遍历配置中的 reporters 节点
+        4. 对每个启用的报告者进行实例化和配置
+        5. 将配置成功的报告者添加到激活列表
+
+        【配置合并规则】
+        - 全局配置（如 log_dir）会被自动注入
+        - 报告者特定配置会覆盖全局配置
+        """
+        # 检查配置文件是否存在
+        if not os.path.exists(self.config_path):
+            logger.warning("报告配置文件 '%s' 未找到, 将不启用任何报告服务。", self.config_path)
+            return
+
+        try:
+            # 读取并解析 YAML 配置文件
+            with open(self.config_path, encoding="utf-8") as f:
+                config = yaml.safe_load(f) or {}
+        except Exception as e:
+            logger.error("读取报告配置文件失败: %s", e)
+            return
+
+        # 全局配置，可被所有报告者共享
+        global_config = {"log_dir": os.path.join(self.base_dir, "logs")}
+
+        # 遍历配置文件中定义的 reporters（§1.29: reporters 键为 null 时 `or {}` 兜底，
+        # 单条目为 null 时跳过并警告——报告是"坏了就跳过"的可选件，不拖崩校验流程）
+        reporters = config.get("reporters") or {}
+        for reporter_name, reporter_config in reporters.items():
+            if reporter_config is None:
+                logger.warning("报告者 '%s' 配置为空，跳过。", reporter_name)
+                continue
+            # 检查报告者是否启用
+            if not reporter_config.get("enabled", False):
+                logger.info("报告者 '%s' 未启用，跳过。", reporter_name)
+                continue
+
+            # 检查报告者是否在注册表中
+            if reporter_name in self._reporter_registry:
+                reporter_class = self._reporter_registry[reporter_name]
+                reporter_instance = reporter_class()
+
+                # 合并全局配置和特定配置
+                full_config = {**global_config, **reporter_config}
+
+                logger.info("正在配置报告者: '%s'...", reporter_name)
+                if reporter_instance.configure(**full_config):
+                    self._active_reporters.append(reporter_instance)
+                else:
+                    logger.warning("报告者 '%s' 配置失败，将不被激活。", reporter_name)
+            else:
+                logger.warning("在报告者注册表中未找到名为 '%s' 的报告者。", reporter_name)
+
+        logger.info("报告服务配置完成，共激活 %d 个报告者。", len(self._active_reporters))
+
+    def report(self, errors: list[dict]) -> None:
+        """
+        @methoddesc 执行总报告流程。
+        遍历所有激活的报告者并调用它们的 report 方法。
+
+        【处理逻辑】
+        1. 如果错误列表为空，直接返回（无需报告）
+        2. 如果没有激活的报告者，将错误打印到控制台
+        3. 否则，遍历所有激活的报告者发送报告
+
+        :param errors: 错误信息字典列表
+        """
+        # 无错误时直接返回
+        if not errors:
+            logger.info("未发现错误，无需报告。")
+            return
+
+        # 无激活报告者时，打印到控制台作为后备（保留 print 确保错误在低日志级别下仍可见）
+        if not self._active_reporters:
+            logger.warning("无激活的报告者，错误将不会被报告。仅在控制台显示:")
+            print(json.dumps(errors, indent=2, ensure_ascii=False))
+            return
+
+        # 遍历所有激活的报告者发送报告
+        logger.info("--- 开始报告 %d 个错误 ---", len(errors))
+        for reporter in self._active_reporters:
+            reporter.report(errors)
+        logger.info("--- 报告流程结束 ---")

app/shared/core/reporter/reporters/__init__.py

@@ -0,0 +1,65 @@
+# 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 报告器实现统一导出模块
+
+功能概述:
+- 聚合导出所有内置报告器实现（本地文件、邮件、企业微信、飞书、钉钉）
+- 提供 Reporter 抽象基类统一入口
+
+架构设计:
+- 注册表模式: 各报告器实现继承自 Reporter 基类
+- 统一导出: 通过 __all__ 控制对外可见的报告器列表
+- 便于扩展: 新增报告器时只需在此添加导入和 __all__ 列表
+
+输入示例:
+    从外部导入所需的报告器:
+    from backend.app.shared.core.reporter.reporters import (
+        Reporter,           # 抽象基类，用于自定义报告器
+        LocalFileReporter,  # 本地文件报告器
+        EmailReporter,      # 邮件报告器
+        WeComAppReporter,   # 企业微信报告器
+        FeishuReporter,     # 飞书报告器
+        DingTalkAppReporter # 钉钉报告器
+    )
+
+输出示例:
+    导出的报告器列表:
+    __all__ = [
+        "Reporter",
+        "LocalFileReporter",
+        "EmailReporter",
+        "WeComAppReporter",
+        "FeishuReporter",
+        "DingTalkAppReporter",
+    ]
+"""
+
+from .base import Reporter
+from .dingtalk_app_reporter import DingTalkAppReporter
+from .email_reporter import EmailReporter
+from .feishu_app_reporter import FeishuReporter
+from .local_file_reporter import LocalFileReporter
+from .wecom_app_reporter import WeComAppReporter
+
+__all__ = [
+    "Reporter",
+    "LocalFileReporter",
+    "EmailReporter",
+    "WeComAppReporter",
+    "FeishuReporter",
+    "DingTalkAppReporter",
+]

app/shared/core/reporter/reporters/base.py

@@ -0,0 +1,188 @@
+# 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 报告器抽象基类
+
+功能概述:
+- 定义所有报告器的统一接口（Strategy 模式）
+- 提供 configure() 和 report() 抽象方法
+- 强制子类实现配置和报告的标准化流程
+
+架构设计:
+- 策略模式 (Strategy Pattern): 将不同的报告渠道封装为可互换的算法
+- 模板方法模式: 定义 report() 和 configure() 的标准接口，子类负责具体实现
+- 依赖倒置: 高层模块（ReportService）依赖抽象（Reporter），而非具体实现
+
+输入示例:
+    子类实现示例:
+    class MyReporter(Reporter):
+        def configure(self, **config) -> bool:
+            # 验证并保存配置
+            self.webhook_url = config.get("webhook_url")
+            return bool(self.webhook_url)
+
+        def report(self, errors: list[dict]):
+            # 发送错误报告到自定义渠道
+            requests.post(self.webhook_url, json=errors)
+
+输出示例:
+    客户端代码无需关心具体实现:
+    reporter: Reporter = EmailReporter()  # 或任何其他报告器
+    if reporter.configure(**config):
+        reporter.report(errors)
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+from urllib.parse import urlparse
+
+# 截断后追加的省略标记（各报告器共用，保证提示语义一致）
+TRUNCATION_SUFFIX = "\n... (内容过长，已截断)"
+
+# 各报告器的消息模板在 error_details 之外还含标题/时间戳/代码块围栏等固定文本，
+# 截断上限需为其预留字节余量，保证整条消息编码后不超过平台限额
+TEMPLATE_HEADROOM_BYTES = 256
+
+
+def sanitize_url_for_log(url: str) -> str:
+    """脱敏 URL 用于日志输出：只保留 scheme://host/path，丢弃 query/fragment。
+
+    Webhook/Token 类 URL 的凭证（token、corpsecret 等）几乎都在 query 中，
+    异常日志打印完整 URL 会把密钥写进日志文件。此函数只保留主机与路径。
+
+    Args:
+        url: 原始 URL（可能含敏感 query）
+
+    Returns:
+        形如 "https://open.feishu.cn/open-apis/bot/v2/hook/xxx" 的脱敏 URL；
+        解析失败时返回 "<invalid-url>"（不抛异常，日志路径不允许二次失败）。
+    """
+    try:
+        parsed = urlparse(url)
+        if parsed.scheme and parsed.netloc:
+            return f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
+        return "<invalid-url>"
+    except Exception:  # noqa: BLE001  日志脱敏兜底，任何解析异常都降级为占位符
+        return "<invalid-url>"
+
+
+def truncate_to_byte_limit(text: str, max_bytes: int, suffix: str = TRUNCATION_SUFFIX) -> str:
+    """按 UTF-8 字节数上限截断文本，超限时追加省略标记。
+
+    平台（飞书/钉钉/企业微信）的消息限额按字节数计算。过去"按字节检查、按字符截断"
+    的做法对中文内容无效：每个汉字 UTF-8 占 3 字节，按字符截掉一半后实际字节数
+    仍可能超限，消息会被平台拒收。
+
+    规则：
+    - 原文未超限则原样返回；
+    - 超限时按编码后字节累积截断，并回退到 UTF-8 字符边界（不截在多字节字符中间），
+      追加省略标记后总长（含标记）仍不超过 max_bytes。
+
+    Args:
+        text: 原始文本
+        max_bytes: 允许的最大 UTF-8 字节数
+        suffix: 截断时追加的省略标记
+
+    Returns:
+        截断后的字符串（UTF-8 编码后不超过 max_bytes 字节）
+    """
+    encoded = text.encode("utf-8")
+    if len(encoded) <= max_bytes:
+        return text
+
+    suffix_bytes = suffix.encode("utf-8")
+    limit = max_bytes - len(suffix_bytes)
+    if limit <= 0:
+        # 防御：上限比省略标记还小，直接返回空串，保证总长不超限
+        return ""
+
+    # 从末尾回退，跳过 UTF-8 多字节序列的续字节（0b10xxxxxx），避免截在字符中间
+    while limit > 0 and (encoded[limit] & 0xC0) == 0x80:
+        limit -= 1
+
+    return encoded[:limit].decode("utf-8", errors="ignore") + suffix
+
+
+class Reporter(ABC):
+    """
+    @classdesc 报告器抽象基类
+
+    该类定义了所有报告器必须实现的接口规范。
+    采用策略模式，任何需要报告数据验证错误的模块都可以通过统一的接口调用不同的报告策略。
+
+    属性说明：
+        name: 报告器实例的名称，用于日志和调试标识
+
+    使用示例：
+        # 客户端代码不关心具体使用哪种报告器
+        reporter: Reporter = EmailReporter()
+        reporter.configure(**email_config)
+        reporter.report(errors)
+    """
+
+    def __init__(self, name: str):
+        """
+        初始化报告器实例
+
+        :param name: 报告器的名称，用于日志输出和调试追踪
+        """
+        self.name = name
+
+    @abstractmethod
+    def configure(self, **config: Any) -> bool:
+        """
+        @methoddesc 配置当前报告器
+
+        这是一个抽象方法，每个子类必须实现自己的配置逻辑。
+        配置通常包括连接信息、认证凭证、目标路径等。
+
+        :param config: 关键字参数，包含特定报告器的配置选项
+                      不同的报告器子类有不同的配置要求
+        :return: 配置是否成功。返回 True 表示配置生效，可以调用 report()；
+                 返回 False 表示配置失败，需要检查配置参数或日志
+
+        子类实现注意事项：
+            - 应该验证所有必需的配置参数
+            - 应该在失败时打印详细的错误信息
+            - 可以选择在配置阶段建立连接（如邮件SMTP连接）进行验证
+        """
+        pass
+
+    @abstractmethod
+    def report(self, errors: list[dict]) -> None:
+        """
+        @methoddesc 执行报告操作，将错误信息发送或写入指定目标
+
+        这是一个抽象方法，每个子类必须实现自己的报告逻辑。
+        在调用此方法之前，必须确保 configure() 已经成功调用。
+
+        :param errors: 错误信息的字典列表
+                      每个字典代表一个独立的验证错误
+                      标准格式包含：row_index, column, value, error_type, error_message
+                      不同报告器可能对格式有特定要求
+
+        错误字典的推荐字段：
+            - row_index: 错误发生的行号（可选，列级别错误可能为 None）
+            - column: 涉及的数据列名
+            - value: 导致错误的原始值
+            - error_type: 错误类型标识（如 'TypeValidationError'）
+            - error_message: 人类可读的错误描述
+
+        子类实现注意事项：
+            - 应该检查是否已正确配置（如检查 is_configured 标志）
+            - 应该处理空列表的情况（空列表通常不需要报告）
+            - 应该在失败时打印错误日志，但不应抛出异常
+        """
+        pass