precis-cli 0.1.3__py3-none-any.whl

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

@@ -0,0 +1,274 @@
+# 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 钉钉自建应用消息推送报告器
+
+功能概述:
+- 通过钉钉企业内部应用发送数据验证错误报告
+- 支持 Markdown 格式消息，自动获取和管理 access_token
+- 实现 access_token 的缓存和自动刷新机制（提前 5 分钟刷新）
+
+架构设计:
+- 继承 Reporter 抽象基类，实现 configure() 和 report() 方法
+- Token 管理: _get_access_token() 实现缓存 + 自动刷新策略
+- 消息截断: 钉钉消息限制约 4KB，超长内容自动截断
+- 统一请求: _send_request() 封装 HTTP POST 请求和错误处理
+
+输入示例:
+    配置参数:
+    {
+        "app_key": "dingxxxxxxxxxxxx",
+        "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "agent_id": 123456789,
+        "userid_list": "user1,user2"
+    }
+
+    错误数据:
+    [{"error_type": "ValidationError", "row_index": 2, "column": "age", "value": "abc"}]
+
+输出示例:
+    钉钉消息 (Markdown 格式):
+    ### 【数据验证警告】发现 1 个错误!
+    **错误详情:**
+    ```json
+    [{"error_type": "ValidationError", ...}]
+    ```
+    > **报告时间:** 2024-01-15 14:30:52
+
+    控制台输出:
+    [DingTalkAppReporter] ✓ 配置成功。
+    [DingTalkAppReporter] ✓ 成功获取 Access Token。
+    [DingTalkAppReporter] ✓ 成功发送消息。
+"""
+
+import json
+import logging
+import time
+import urllib.parse
+import urllib.request
+from datetime import datetime
+from typing import Any
+
+from .base import TEMPLATE_HEADROOM_BYTES, Reporter, sanitize_url_for_log, truncate_to_byte_limit
+
+logger = logging.getLogger(__name__)
+
+
+class DingTalkAppReporter(Reporter):
+    """
+    @classdesc 钉钉自建应用消息推送报告器
+
+    通过钉钉企业内部应用发送工作通知，将数据验证错误报告推送给指定用户。
+
+    Attributes:
+        config: 存储配置参数的字典，包含 app_key, app_secret, agent_id, userid_list
+        is_configured: 配置是否有效的标志
+        access_token: 钉钉 API 访问令牌
+        token_expires_at: 令牌过期时间戳
+    """
+
+    def __init__(self) -> None:
+        """
+        @methoddesc 初始化钉钉报告器
+
+        设置默认属性，包括配置字典、配置状态标志、
+        访问令牌及其过期时间戳。
+        """
+        super().__init__("DingTalkAppReporter")
+        self.config: dict[str, Any] = {}  # 存储配置参数
+        self.is_configured = False  # 配置是否有效
+        self.access_token = None  # 钉钉 API 访问令牌
+        self.token_expires_at = 0  # 令牌过期时间戳
+
+    def configure(self, **kwargs: Any) -> bool:
+        """
+        @methoddesc 配置钉钉报告器参数
+
+        验证所有必需参数是否提供，并保存配置信息。
+
+        Args:
+            app_key: 钉钉应用 Key（企业标识下的唯一 ID）
+            app_secret: 钉钉应用密钥（用于获取 access_token）
+            agent_id: 钉钉应用 AgentID（用于指定发送目标应用）
+            userid_list: 接收者用户 ID 列表（逗号分隔的字符串）
+            **kwargs: 额外参数（保留用于扩展）
+
+        Returns:
+            bool: 配置是否成功
+        """
+        # 参数验证：确保所有必需参数都提供
+        app_key = kwargs.get("app_key")
+        app_secret = kwargs.get("app_secret")
+        agent_id = kwargs.get("agent_id")
+        userid_list = kwargs.get("userid_list")
+        if not all([app_key, app_secret, agent_id, userid_list]):
+            self.is_configured = False
+            return False
+
+        # 显式处理 None，避免 mypy 将 Any | None 传给 int() 时报错
+        if agent_id is None:
+            self.is_configured = False
+            return False
+
+        # 保存配置参数
+        self.config = {
+            "app_key": str(app_key),
+            "app_secret": str(app_secret),
+            "agent_id": int(agent_id),
+            "userid_list": str(userid_list),
+        }
+        self.is_configured = True
+        print(f"[{self.name}] ✓ 配置成功。")
+        return True
+
+    def _get_access_token(self) -> str | None:
+        """
+        @methoddesc 获取或刷新钉钉 API 访问令牌（Access Token）
+
+        访问令牌用于调用钉钉 API，有效期默认为 7200 秒（2 小时）。
+        实现自动刷新机制：在过期前 5 分钟自动刷新，避免令牌失效。
+
+        Token 刷新逻辑：
+        - 检查当前时间是否早于过期时间
+        - 如果是，直接返回缓存的令牌
+        - 否则调用钉钉 API 获取新令牌并更新缓存
+
+        Returns:
+            str: 有效的访问令牌，如果获取失败返回 None
+
+        API 调用：
+        - URL: https://oapi.dingtalk.com/gettoken
+        - 参数: appkey, appsecret
+        - 响应: access_token, expire (有效期秒数)
+        """
+        # 检查令牌是否仍然有效（提前 5 分钟刷新）
+        if time.time() < self.token_expires_at:
+            return self.access_token
+
+        # 调用钉钉 API 获取令牌
+        url = "https://oapi.dingtalk.com/gettoken"
+        params = {"appkey": self.config["app_key"], "appsecret": self.config["app_secret"]}
+        try:
+            # 构建 URL 参数
+            full_url = f"{url}?{urllib.parse.urlencode(params)}"
+
+            # 发送请求
+            with urllib.request.urlopen(full_url, timeout=10) as response:
+                data = json.loads(response.read().decode())
+                if data.get("errcode") == 0:
+                    # 成功获取令牌
+                    self.access_token = data["access_token"]
+                    # 设置过期时间：当前时间 + 有效期 - 缓冲时间（5分钟）
+                    self.token_expires_at = time.time() + data["expires_in"] - 300
+                    print(f"[{self.name}] ✓ 成功获取 Access Token。")
+                    return self.access_token
+                else:
+                    print(f"[{self.name}] !! 错误: 获取 Access Token 失败: {data.get('errmsg')}")
+                    return None
+        except Exception as e:
+            # gettoken 的 full_url query 含 appsecret，日志只打无 query 的基础 URL
+            logger.warning(
+                "[%s] !! 错误: 请求 Access Token 失败 (%s): %s",
+                self.name,
+                sanitize_url_for_log(url),
+                e,
+            )
+            return None
+
+    def report(self, errors: list[dict]) -> None:
+        """
+        @methoddesc 发送错误报告的主入口方法
+
+        流程：
+        1. 检查配置是否有效
+        2. 获取有效的访问令牌
+        3. 格式化错误信息为 Markdown
+        4. 调用钉钉发送工作通知 API
+
+        Args:
+            errors: 错误信息列表，每个元素是一个包含错误详情的字典
+        """
+        # 前置检查：确保已正确配置
+        if not self.is_configured:
+            return
+
+        # 步骤1: 获取有效的访问令牌
+        token = self._get_access_token()
+        if not token:
+            return
+
+        # 步骤2: 统计错误数量并格式化详情
+        error_count = len(errors)
+        error_details = json.dumps(errors, indent=2, ensure_ascii=False)
+
+        # 安全截断：钉钉消息内容限制约 4KB
+        # 必须按 UTF-8 字节截断：平台限额按字节计，中文按字符截断后实际字节数
+        # 仍可能超限被拒收（见 truncate_to_byte_limit）
+        error_details = truncate_to_byte_limit(error_details, 4000 - TEMPLATE_HEADROOM_BYTES)
+
+        # 步骤3: 构建 Markdown 格式消息内容
+        title = f"【数据验证警告】发现 {error_count} 个错误!"
+        text = f"""### {title}
+**错误详情:**
+```json
+{error_details}
+```
+> **报告时间:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+"""
+
+        # 步骤4: 构建发送工作通知的请求负载
+        payload = {
+            "agent_id": self.config["agent_id"],  # 应用 AgentID
+            "userid_list": self.config["userid_list"],  # 接收者用户列表
+            "msg": {
+                "msgtype": "markdown",  # 消息类型：Markdown
+                "markdown": {
+                    "title": title,  # 消息标题（通知标题）
+                    "text": text,  # 消息正文内容
+                },
+            },
+        }
+
+        # 步骤5: 发送消息
+        url = f"https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token={token}"
+        self._send_request(url, payload)
+
+    def _send_request(self, url: str, payload: dict[str, Any]) -> None:
+        """
+        @methoddesc 发送 HTTP POST 请求到钉钉 API
+
+        处理所有钉钉 API 的 HTTP 通信，包括错误处理和日志记录。
+
+        Args:
+            url: 请求目标 URL
+            payload: 请求体数据字典
+        """
+        try:
+            # 序列化请求负载为 JSON 字节
+            data = json.dumps(payload).encode("utf-8")
+            headers = {"Content-Type": "application/json"}
+
+            # 构建 HTTP 请求
+            req = urllib.request.Request(url, data=data, headers=headers)
+
+            # 发送请求并获取响应
+            with urllib.request.urlopen(req, timeout=10) as response:
+                result = json.loads(response.read().decode("utf-8"))
+                if result.get("errcode") == 0:
+                    print(f"[{self.name}] ✓ 成功发送消息。")
+                else:
+                    print(f"[{self.name}] !! 错误: 发送消息失败: {result.get('errmsg')}")
+        except Exception as e:
+            logger.warning("[%s] !! 错误: 发送请求失败: %s", self.name, e)

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

@@ -0,0 +1,271 @@
+# 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 邮件报告器模块
+
+功能概述:
+- 通过 SMTP 协议发送数据验证错误报告
+- 支持 TLS/SSL 加密传输和 HTML 格式邮件
+- 配置阶段即验证 SMTP 连接和认证，提前发现问题
+
+架构设计:
+- 继承 Reporter 抽象基类，实现 configure() 和 report() 方法
+- 双模式连接: 根据端口自动选择 SMTP + STARTTLS (587) 或 SMTP_SSL (465)
+- 配置即验证: configure() 阶段建立真实连接测试，确保参数正确
+- 资源安全: 使用 with 语句和 try-finally 确保 SMTP 连接正确关闭
+
+输入示例:
+    配置参数:
+    {
+        "smtp_server": "smtp.gmail.com",
+        "smtp_port": 587,
+        "sender_email": "precis@example.com",
+        "sender_password": "app_password",
+        "receiver_email": "admin@example.com"
+    }
+
+    错误数据:
+    [{"error_type": "ForeignKeyViolation", "table": "orders", "value": 99}]
+
+输出示例:
+    HTML 邮件内容:
+    <html><body>
+        <h2>检测到以下数据配置错误：</h2>
+        <pre style="...">[...错误JSON...]</pre>
+        <p>请尽快检查并修复。</p>
+    </body></html>
+
+    控制台输出:
+    [EmailReporter] ✓ 邮件服务配置验证成功，发件人: precis@example.com
+    [EmailReporter] ✓ 成功发送错误报告邮件至 admin@example.com。
+"""
+
+import html
+import json
+import smtplib
+from email.header import Header
+from email.mime.text import MIMEText
+from email.utils import formataddr
+from typing import Any, cast
+
+from .base import Reporter
+
+
+class EmailReporter(Reporter):
+    """
+    @classdesc 邮件报告器 - 通过 SMTP 协议发送错误报告
+
+    该报告器将数据验证错误格式化为 HTML 邮件并发送给指定的收件人。
+    使用原生 smtplib 实现，避免第三方依赖，提供更好的稳定性和控制力。
+
+    属性说明：
+        config: 存储邮件服务器配置信息的字典
+               包含 smtp_server, smtp_port, sender_email, sender_password, receiver_email
+        is_configured: 标记配置是否通过验证
+
+    功能特点：
+        - 配置阶段验证 SMTP 连接和认证
+        - 支持 TLS（端口 587）和 SSL（端口 465）两种加密方式
+        - HTML 格式邮件，带有错误详情表格
+        - 中文编码支持，使用 Header 防止乱码
+
+    使用示例：
+        reporter = EmailReporter()
+        if reporter.configure(
+            smtp_server='smtp.example.com',
+            smtp_port=587,
+            sender_email='precis@example.com',
+            sender_password='secret',
+            receiver_email='admin@example.com'
+        ):
+            reporter.report(errors)
+    """
+
+    def __init__(self) -> None:
+        """
+        初始化邮件报告器
+
+        调用父类构造函数设置报告器名称为 'EmailReporter'。
+        初始化配置字典和配置状态标志。
+        """
+        super().__init__("EmailReporter")
+        self.config: dict[str, Any] = {}
+        self.is_configured = False
+
+    def configure(self, **config: Any) -> bool:
+        """
+        @methoddesc 配置邮件服务器参数并在配置阶段验证连接
+
+        该方法会验证所有必需的 SMTP 参数，并尝试建立连接进行认证验证。
+        只有配置验证通过后，才能调用 report() 方法发送邮件。
+
+        :param smtp_server: SMTP 服务器地址（如 'smtp.gmail.com'）
+        :param smtp_port: SMTP 服务器端口
+                         通常 587 使用 TLS，465 使用 SSL
+        :param sender_email: 发件人邮箱地址
+        :param sender_password: 发件人邮箱密码或应用专用密码
+        :param receiver_email: 收件人邮箱地址
+        :param config: 额外的可选配置参数（当前未使用，保留扩展性）
+        :return: 配置验证是否成功。成功返回 True，失败返回 False
+
+        验证流程：
+            1. 检查所有必需参数是否提供
+            2. 将配置参数保存到实例变量
+            3. 尝试建立 SMTP 连接并登录
+            4. 如果连接成功，设置 is_configured 为 True
+        """
+        # 参数完整性检查：确保所有必需的配置都已提供
+        smtp_server = config.get("smtp_server")
+        smtp_port = config.get("smtp_port")
+        sender_email = config.get("sender_email")
+        sender_password = config.get("sender_password")
+        receiver_email = config.get("receiver_email")
+        if not all([smtp_server, smtp_port, sender_email, sender_password, receiver_email]):
+            print(f"[{self.name}] 邮件配置信息不完整, 无法启用。")
+            return False
+
+        # 显式处理 None，避免 mypy 将 Any | None 传给 int() 时报错
+        if smtp_port is None:
+            return False
+
+        # 将配置保存到实例变量中，供后续 report() 方法使用
+        self.config = {
+            "smtp_server": str(smtp_server),
+            "smtp_port": int(smtp_port),
+            "sender_email": str(sender_email),
+            "sender_password": str(sender_password),
+            "receiver_email": str(receiver_email),
+        }
+
+        # 尝试连接和登录以验证配置的正确性
+        # 使用 with 语句确保连接被正确关闭，即使发生异常
+        try:
+            # 与 report() 保持一致的双模式连接：
+            # - 端口 465 使用 SMTP_SSL（隐式 SSL，STARTTLS 握手会失败/超时）
+            # - 其余端口使用普通 SMTP + STARTTLS 升级加密
+            if int(smtp_port) == 465:
+                with smtplib.SMTP_SSL(str(smtp_server), int(smtp_port), timeout=10) as smtp:
+                    # 使用提供的凭证登录
+                    smtp.login(str(sender_email), str(sender_password))
+            else:
+                # 建立 SMTP 连接，设置 10 秒超时防止阻塞
+                with smtplib.SMTP(str(smtp_server), int(smtp_port), timeout=10) as smtp:
+                    # 升级到 TLS 加密连接，这是现代 SMTP 服务的安全要求
+                    # TLS 适用于端口 587，是比 SSL 更常用的选择
+                    smtp.starttls()
+                    # 使用提供的凭证登录
+                    smtp.login(str(sender_email), str(sender_password))
+
+            # 配置验证成功，打印成功信息（不包含敏感密码）
+            print(f"[{self.name}] ✓ 邮件服务配置验证成功，发件人: {sender_email}")
+            self.is_configured = True
+            return True
+
+        except Exception as e:
+            # 配置验证失败，打印错误信息用于调试
+            print(f"[{self.name}] !! 错误: 邮件服务配置验证失败: {e}")
+            self.is_configured = False
+            return False
+
+    def report(self, errors: list[dict]) -> None:
+        """
+        @methoddesc 将错误报告发送到指定的邮件地址
+
+        在发送邮件前会检查配置状态，确保邮件服务已正确配置。
+        邮件内容为 HTML 格式，包含错误数量和详细的 JSON 格式错误列表。
+
+        :param errors: 错误信息的字典列表，每个字典包含错误详情
+                      典型字段：row_index, column, value, error_type, error_message
+
+        邮件内容格式：
+            - 标题：【数据验证警告】发现 N 个错误!
+            - 正文：包含错误数量的说明和 JSON 格式的错误详情
+
+        发送流程：
+            1. 检查是否已配置（is_configured 标志）
+            2. 构建 HTML 邮件内容
+            3. 设置邮件头部（Subject, From, To）
+            4. 根据端口选择 SMTP 或 SMTP_SSL 连接
+            5. 登录并发送邮件
+            6. 在 finally 块中确保连接关闭
+        """
+        # 前置检查：确保邮件服务已配置
+        if not self.is_configured:
+            print(f"[{self.name}] !! 错误: 邮件服务未配置或配置失败，无法发送邮件。")
+            return
+
+        # 构建邮件标题，包含错误数量
+        subject = f"【数据验证警告】发现 {len(errors)} 个错误!"
+
+        # 构建 HTML 邮件正文，使用 JSON 格式化错误列表
+        # 使用 pre 标签保持 JSON 的格式和缩进
+        # html.escape 防止错误数据中的 <script>/标签注入邮件 HTML（XSS）
+        errors_json = html.escape(json.dumps(errors, indent=2, ensure_ascii=False))
+        html_body = f"""
+        <html><body>
+            <h2>检测到以下数据配置错误：</h2>
+            <pre style=\"background-color: #f0f0f0; padding: 10px; border-radius: 5px; white-space: pre-wrap; word-wrap: break-word;\">{errors_json}</pre>
+            <p>请尽快检查并修复。</p>
+        </body></html>
+        """
+
+        # 创建 MIMEText 邮件对象，指定 HTML 格式和 UTF-8 编码
+        msg = MIMEText(html_body, "html", "utf-8")
+
+        # 使用 Header 对象编码邮件标题，确保中文正确显示
+        msg["Subject"] = cast(str, Header(subject, "utf-8"))
+
+        # 使用 formataddr 正确格式化发件人和收件人地址
+        # formataddr((友好名称, 邮件地址)) 格式
+        # 使用 Header 编码友好名称以支持中文
+        msg["From"] = formataddr((Header("数据验证服务", "utf-8").encode(), self.config["sender_email"]))
+        msg["To"] = formataddr((Header("项目负责人", "utf-8").encode(), self.config["receiver_email"]))
+
+        # 建立 SMTP 连接并发送邮件
+        smtp: smtplib.SMTP | smtplib.SMTP_SSL | None = None
+        try:
+            # 根据端口号判断使用哪种连接方式：
+            # - 端口 465 通常使用 SSL 加密的 SMTP_SSL
+            # - 端口 587 通常使用 STARTTLS 升级到 TLS
+            if self.config["smtp_port"] == 465:
+                smtp = smtplib.SMTP_SSL(self.config["smtp_server"], self.config["smtp_port"], timeout=10)
+            else:
+                # 端口不是 465，使用普通 SMTP 然后升级到 TLS
+                smtp = smtplib.SMTP(self.config["smtp_server"], self.config["smtp_port"], timeout=10)
+                if isinstance(smtp, smtplib.SMTP):
+                    smtp.starttls()
+
+            # 使用配置中的凭证登录 SMTP 服务器
+            smtp.login(self.config["sender_email"], self.config["sender_password"])
+
+            # 发送邮件，sender 和 receiver 都可以是列表
+            smtp.sendmail(self.config["sender_email"], [self.config["receiver_email"]], msg.as_string())
+
+            # 发送成功，打印确认信息
+            print(f"[{self.name}] ✓ 成功发送错误报告邮件至 {self.config['receiver_email']}。")
+
+        except Exception as e:
+            # 发送失败，打印错误信息（不包含敏感内容）
+            print(f"[{self.name}] !! 错误: 发送邮件失败: {e}")
+
+        finally:
+            # 确保 SMTP 连接被正确关闭，释放资源
+            # quit() 自身的异常（连接已断等 secondary exception）不得吞掉
+            # try/except 块中捕获的原始业务异常
+            if smtp:
+                try:
+                    smtp.quit()
+                except Exception:  # noqa: BLE001  关闭失败的次要异常仅记录
+                    print(f"[{self.name}] !! 警告: 关闭 SMTP 连接失败（忽略）。")