precis-cli 0.1.3__py3-none-any.whl

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

@@ -0,0 +1,467 @@
+# 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 飞书消息推送报告器
+
+功能概述:
+- 通过飞书 Webhook/App/Service 三种模式发送错误报告
+- 支持 Interactive Card 消息卡片和自动签名验证
+- 三种模式按安全性优先级自动选择: Service > App > Webhook
+
+架构设计:
+- 继承 Reporter 抽象基类，实现 configure() 和 report() 方法
+- 多模式策略: configure() 根据提供的参数自动选择最佳模式
+- Token 管理: App 模式下 _get_tenant_access_token() 实现缓存 + 自动刷新
+- 签名验证: Webhook 模式下 _generate_sign() 实现 HMAC-SHA256 签名
+- 消息标准化: _create_message_card() 统一生成飞书卡片消息结构
+- 通用请求: _send_request() 封装所有 HTTP 通信
+
+输入示例:
+    Service 模式配置 (推荐):
+    {"service_url": "https://my-service.com/feishu", "api_key": "xxx"}
+
+    App 模式配置:
+    {"app_id": "cli_xxx", "app_secret": "xxx", "receive_ids": "ou_xxx", "receive_id_type": "open_id"}
+
+    Webhook 模式配置:
+    {"webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx", "secret": "xxx"}
+
+输出示例:
+    飞书卡片消息:
+    {
+        "config": {"wide_screen_mode": True},
+        "header": {"template": "red", "title": {"content": "【数据验证警告】发现 3 个错误!", "tag": "plain_text"}},
+        "elements": [...]
+    }
+
+    控制台输出:
+    [FeishuReporter] ✓ 配置成功 (模式: 自建应用)。
+    [FeishuReporter] ✓ 成功获取 Tenant Access Token。
+    [FeishuReporter] ✓ 成功发送消息 给 ou_xxx。
+"""
+
+import base64
+import hashlib
+import hmac
+import ipaddress
+import json
+import logging
+import time
+import urllib.request
+from datetime import datetime
+from typing import Any
+from urllib.parse import urlparse
+
+from .base import TEMPLATE_HEADROOM_BYTES, Reporter, sanitize_url_for_log, truncate_to_byte_limit
+
+logger = logging.getLogger(__name__)
+
+_ALLOWED_URL_SCHEMES = {"https", "http"}
+_BLOCKED_NETWORKS = [
+    ipaddress.ip_network("169.254.0.0/16"),
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("::1/128"),
+    ipaddress.ip_network("fc00::/7"),
+]
+
+
+def _validate_webhook_url(url: str) -> None:
+    parsed = urlparse(url)
+    if parsed.scheme not in _ALLOWED_URL_SCHEMES:
+        raise ValueError(f"不支持的 URL scheme: {parsed.scheme}，仅允许 {_ALLOWED_URL_SCHEMES}")
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError("URL 缺少主机名")
+    try:
+        for network in _BLOCKED_NETWORKS:
+            if ipaddress.ip_address(hostname) in network:
+                raise ValueError(f"不允许访问内网地址: {hostname}")
+    except ValueError as e:
+        # B40 修复：过去用 str(ValueError) 取类本身的字符串（恒为 "<class 'ValueError'>"），
+        # 导致内网地址拦截的 raise 永不执行，SSRF 校验形同虚设。应为 str(e) 取异常消息。
+        if "不允许访问内网地址" in str(e):
+            raise
+    except Exception:
+        pass
+
+
+class FeishuReporter(Reporter):
+    """
+    @classdesc 飞书消息推送报告器
+
+    通过飞书发送数据验证错误报告，支持三种发送模式：
+    1. Webhook: 单用户快速集成，零部署
+    2. App: 团队使用，需要分发凭证
+    3. Service: 团队使用，通过中心化服务统一管理，最安全
+
+    Attributes:
+        config: 存储配置参数的字典
+        mode: 当前使用的发送模式 ('webhook', 'app', 'service')
+        is_configured: 配置是否有效的标志
+        tenant_access_token: 飞书应用访问令牌（App 模式专用）
+        token_expires_at: 令牌过期时间戳（App 模式专用）
+    """
+
+    def __init__(self) -> None:
+        """
+        @methoddesc 初始化飞书报告器
+
+        设置默认属性，包括配置字典、发送模式、配置状态标志，
+        以及 App 模式专用的访问令牌和过期时间戳。
+        """
+        super().__init__("FeishuReporter")
+        self.config: dict[str, Any] = {}  # 存储配置参数
+        self.mode: str | None = None  # 当前发送模式: 'webhook' | 'app' | 'service'
+        self.is_configured = False  # 配置是否有效
+
+        # App 模式专用属性
+        self.tenant_access_token = None  # 飞书应用访问令牌
+        self.token_expires_at = 0  # 令牌过期时间戳
+
+    def configure(self, **config: Any) -> bool:
+        """
+        @methoddesc 根据配置参数自动检测并设置最佳操作模式
+
+        配置优先级（按安全性排序）：
+        1. Service 模式：需要 service_url 和 api_key
+        2. App 模式：需要 app_id, app_secret 和 receive_ids
+        3. Webhook 模式：只需要 webhook_url
+
+        Args:
+            **config: 包含飞书配置的键值对
+                - service_url: 中心化服务地址
+                - api_key: API 密钥
+                - app_id: 应用 ID
+                - app_secret: 应用密钥
+                - receive_ids: 接收者 ID 列表
+                - receive_id_type: 接收者 ID 类型
+                - webhook_url: Webhook 地址
+                - secret: 签名密钥
+
+        Returns:
+            bool: 配置是否成功
+        """
+        self.config = config
+
+        # 模式三：中心化服务模式（最高优先级，最安全）
+        # 适用于团队统一管理所有消息通知
+        if config.get("service_url") and config.get("api_key"):
+            self.mode = "service"
+            self.is_configured = True
+            print(f"[{self.name}] ✓ 配置成功 (模式: 中心化服务)。")
+            return True
+
+        # 模式二：自建应用模式
+        # 适用于需要发送给多个用户且有飞书应用的团队
+        if config.get("app_id") and config.get("app_secret") and config.get("receive_ids"):
+            self.mode = "app"
+            self.is_configured = True
+            print(f"[{self.name}] ✓ 配置成功 (模式: 自建应用)。")
+            return True
+
+        # 模式一：Webhook 模式（最低优先级）
+        # 适用于快速集成和单用户场景
+        if config.get("webhook_url"):
+            self.mode = "webhook"
+            self.is_configured = True
+            print(f"[{self.name}] ✓ 配置成功 (模式: Webhook)。")
+            return True
+
+        # 配置不完整时输出错误提示
+        print(
+            f"[{self.name}] !! 错误: 配置不完整。请提供 'service_url'/'api_key' 或 'app_id'/'app_secret' 或 'webhook_url'。"
+        )
+        return False
+
+    def report(self, errors: list[dict]) -> None:
+        """
+        @methoddesc 发送错误报告的主入口方法
+
+        根据当前配置的模式调用相应的发送方法。
+        如果未配置，则跳过发送并输出提示。
+
+        Args:
+            errors: 错误信息列表，每个元素是一个包含错误详情的字典
+        """
+        # 前置检查：确保已正确配置
+        if not self.is_configured:
+            print(f"[{self.name}] 未配置，跳过报告。")
+            return
+
+        # 步骤1: 统一创建消息卡片内容
+        # 将错误列表转换为飞书消息卡片格式
+        card_content = self._create_message_card(errors)
+
+        # 步骤2: 根据模式分发到不同的发送方法
+        if self.mode == "service":
+            self._report_via_service(card_content)
+        elif self.mode == "app":
+            self._report_via_app(card_content)
+        elif self.mode == "webhook":
+            self._report_via_webhook(card_content)
+
+    def _create_message_card(self, errors: list[dict]) -> dict:
+        """
+        @methoddesc 统一生成飞书 Interactive Card 消息卡片结构体
+
+        消息卡片包含：
+        - 红色标题栏显示错误数量
+        - 错误详情的 JSON 格式化展示
+        - 报告时间戳
+
+        Args:
+            errors: 错误信息列表
+
+        Returns:
+            Dict: 飞书消息卡片的 JSON 结构
+        """
+        # 统计错误数量
+        error_count = len(errors)
+        # 将错误列表序列化为格式化的 JSON 字符串
+        error_details = json.dumps(errors, indent=2, ensure_ascii=False)
+
+        # 安全截断：飞书消息卡片大小限制约为 30KB
+        # 这里做保守截断（28KB）。必须按 UTF-8 字节截断：平台限额按字节计，
+        # 中文按字符截断后实际字节数仍可能超限被拒收（见 truncate_to_byte_limit）
+        error_details = truncate_to_byte_limit(error_details, 28000 - TEMPLATE_HEADROOM_BYTES)
+
+        # 构建飞书卡片消息结构
+        return {
+            "config": {"wide_screen_mode": True},  # 宽屏模式
+            "header": {
+                "template": "red",  # 红色标题表示警告
+                "title": {"content": f"【数据验证警告】发现 {error_count} 个错误!", "tag": "plain_text"},
+            },
+            "elements": [
+                # 错误详情区域：使用 Markdown 代码块格式
+                {"tag": "div", "text": {"content": f"**错误详情:**\n```{error_details}```", "tag": "lark_md"}},
+                {"tag": "hr"},  # 分割线
+                # 底部备注：显示报告时间
+                {
+                    "tag": "note",
+                    "elements": [
+                        {"content": f"报告时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}", "tag": "lark_md"}
+                    ],
+                },
+            ],
+        }
+
+    # ==============================================================================
+    # 模式一：Webhook 实现
+    # ==============================================================================
+    def _report_via_webhook(self, card_content: dict) -> None:
+        """
+        @methoddesc 通过 Webhook 发送消息（Webhook 模式）
+
+        适用于单用户快速集成场景。Webhook 是开放接口，
+        通过签名验证请求合法性。
+
+        Args:
+            card_content: 飞书消息卡片内容字典
+        """
+        # 构建消息负载：包含卡片类型和内容
+        payload: dict[str, Any] = {"msg_type": "interactive", "card": card_content}
+
+        # 可选：添加签名验证（如果配置了 secret）
+        secret = self.config.get("secret")
+        if secret:
+            # 生成签名：timestamp + secret -> HMAC-SHA256 -> Base64
+            timestamp = int(time.time())
+            sign = self._generate_sign(secret, timestamp)
+            payload["timestamp"] = timestamp
+            payload["sign"] = sign
+
+        # 发送 HTTP POST 请求
+        self._send_request(
+            url=self.config["webhook_url"], payload=payload, headers={"Content-Type": "application/json"}
+        )
+
+    def _generate_sign(self, secret: str, timestamp: int) -> str:
+        """
+        @methoddesc 生成飞书 Webhook 签名
+
+        签名算法：
+        1. 拼接 timestamp 和 secret 成字符串
+        2. 使用 HMAC-SHA256 算法加密
+        3. Base64 编码结果
+
+        Args:
+            secret: Webhook 签名密钥
+            timestamp: 时间戳（秒）
+
+        Returns:
+            str: 签名字符串
+        """
+        # 构造待签名字符串：timestamp + 换行 + secret
+        string_to_sign = f"{timestamp}\n{secret}"
+        # HMAC-SHA256 加密
+        hmac_code = hmac.new(string_to_sign.encode("utf-8"), digestmod=hashlib.sha256).digest()
+        # Base64 编码
+        return base64.b64encode(hmac_code).decode("utf-8")
+
+    # ==============================================================================
+    # 模式二：自建应用实现
+    # ==============================================================================
+    def _report_via_app(self, card_content: dict) -> None:
+        """
+        @methoddesc 通过飞书自建应用发送消息（App 模式）
+
+        适用于团队场景，需要预先创建飞书自建应用并配置权限。
+        消息通过飞书开放平台 API 发送。
+
+        Args:
+            card_content: 飞书消息卡片内容字典
+        """
+        # 步骤1: 获取有效的访问令牌
+        token = self._get_tenant_access_token()
+        if not token:
+            return
+
+        # 步骤2: 解析接收者列表
+        # 支持逗号分隔的多个接收者
+        receive_id_list = self.config["receive_ids"].split(",")
+        receive_id_type = self.config.get("receive_id_type", "open_id")
+
+        # 步骤3: 构建飞书 IM API 请求
+        url = f"https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type={receive_id_type}"
+        headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"}
+
+        # 步骤4: 逐个向接收者发送消息
+        for receive_id in receive_id_list:
+            # 构建消息负载
+            # 注意：content 字段需要 JSON 序列化为字符串
+            payload = {"receive_id": receive_id.strip(), "msg_type": "interactive", "content": json.dumps(card_content)}
+            self._send_request(url, payload, headers, target_id=receive_id.strip())
+
+    def _get_tenant_access_token(self) -> str | None:
+        """
+        @methoddesc 获取飞书应用访问令牌（Tenant Access Token）
+
+        令牌用于调用飞书开放平台 API，有效期约 2 小时。
+        实现自动刷新机制：在过期前 5 分钟自动刷新。
+
+        Returns:
+            str: 有效的访问令牌，如果获取失败返回 None
+
+        Token 刷新逻辑：
+        - 检查当前时间是否早于过期时间
+        - 如果是，直接返回缓存的令牌
+        - 否则调用 API 获取新令牌并更新缓存
+        """
+        # 检查令牌是否仍然有效（提前 5 分钟刷新）
+        if time.time() < self.token_expires_at:
+            return self.tenant_access_token
+
+        # 调用飞书 OAuth API 获取令牌
+        url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
+        payload = {"app_id": self.config["app_id"], "app_secret": self.config["app_secret"]}
+        try:
+            # 构建 HTTP 请求
+            req_data = json.dumps(payload).encode("utf-8")
+            req = urllib.request.Request(url, data=req_data, headers={"Content-Type": "application/json"})
+
+            # 发送请求并解析响应
+            with urllib.request.urlopen(req, timeout=10) as response:
+                result = json.loads(response.read().decode())
+                if result.get("code") == 0:
+                    # 成功获取令牌
+                    self.tenant_access_token = result["tenant_access_token"]
+                    # 设置过期时间：当前时间 + 有效期 - 缓冲时间
+                    self.token_expires_at = time.time() + result["expire"] - 300
+                    print(f"[{self.name}] ✓ 成功获取 Tenant Access Token。")
+                    return self.tenant_access_token
+                else:
+                    print(f"[{self.name}] !! 错误: 获取 Tenant Access Token 失败: {result.get('msg')}")
+                    return None
+        except Exception as e:
+            print(f"[{self.name}] !! 错误: 请求 Tenant Access Token 失败: {e}")
+            return None
+
+    # ==============================================================================
+    # 模式三：中心化服务实现
+    # ==============================================================================
+    def _report_via_service(self, card_content: dict) -> None:
+        """
+        @methoddesc 通过中心化服务发送消息（Service 模式）
+
+        适用于团队统一管理消息通知的场景。
+        所有消息通过自建的中转服务发送，安全性最高。
+
+        Args:
+            card_content: 飞书消息卡片内容字典
+        """
+        # 构建请求头：包含 API 密钥认证
+        headers = {"Content-Type": "application/json", "Authorization": f"Bearer {self.config['api_key']}"}
+
+        # 构建请求负载：将卡片内容序列化为 JSON 字符串
+        # 服务端负责解析和发送飞书消息
+        payload = {"message": json.dumps(card_content)}
+
+        # 发送请求到中心化服务
+        self._send_request(self.config["service_url"], payload, headers)
+
+    # ==============================================================================
+    # 通用请求发送器
+    # ==============================================================================
+    def _send_request(self, url: str, payload: dict, headers: dict, target_id: str = "N/A") -> None:
+        """
+        @methoddesc 通用 HTTP POST 请求发送器
+
+        处理所有飞书 API 的 HTTP 通信，包括错误处理和日志记录。
+
+        Args:
+            url: 请求目标 URL
+            payload: 请求体数据字典
+            headers: HTTP 请求头字典
+            target_id: 目标接收者 ID（用于日志记录）
+        """
+        try:
+            _validate_webhook_url(url)
+        except ValueError as e:
+            print(f"[{self.name}] !! 错误: URL 校验失败: {e}")
+            return
+
+        try:
+            # 序列化请求负载为 JSON 字节
+            data = json.dumps(payload).encode("utf-8")
+
+            # 构建 HTTP 请求
+            req = urllib.request.Request(url, data=data, headers=headers)
+
+            # 发送请求并获取响应
+            with urllib.request.urlopen(req, timeout=10) as response:
+                result_str = response.read().decode("utf-8")
+                result = json.loads(result_str)
+
+                # 判断不同 API 的成功响应码
+                # 飞书 Webhook/App API: code == 0
+                # 通用 HTTP: status < 300
+                if result.get("code") == 0 or result.get("status_code") == 0 or response.status < 300:
+                    target_info = f"给 {target_id}" if target_id != "N/A" else ""
+                    print(f"[{self.name}] ✓ 成功发送消息 {target_info}。")
+                else:
+                    # 提取错误信息（不同 API 字段名不同）
+                    print(f"[{self.name}] !! 错误: 发送消息失败: {result.get('msg', result_str)}")
+        except Exception as e:
+            # webhook_url 的 token 在 query 中，日志只打 host+path，避免密钥落日志
+            logger.warning(
+                "[%s] !! 错误: 发送请求到 '%s' 失败: %s",
+                self.name,
+                sanitize_url_for_log(url),
+                e,
+            )

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

@@ -0,0 +1,208 @@
+# 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 本地文件报告器模块
+
+功能概述:
+- 将数据验证错误报告以 JSON 格式写入本地文件系统
+- 支持自动创建日志目录和时间戳命名文件
+- 每个报告生成独立的文件，避免覆盖历史记录
+
+架构设计:
+- 继承 Reporter 抽象基类，实现 configure() 和 report() 方法
+- 目录管理: configure() 自动创建不存在的日志目录
+- 时间戳命名: 使用 datetime.now().strftime("%Y%m%d_%H%M%S_%f") 毫秒级时间戳生成唯一文件名，避免同秒覆盖
+- UTF-8 编码: 确保中文字符正确存储
+- 格式化输出: indent=2 使 JSON 文件便于人工阅读
+
+输入示例:
+    配置参数:
+    {"log_dir": "./logs"}
+
+    错误数据:
+    [
+        {"error_type": "TypeValidationError", "row_index": 2, "column": "price", "value": "abc"},
+        {"error_type": "NotNullViolation", "row_index": 5, "column": "email"}
+    ]
+
+输出示例:
+    生成的日志文件: ./logs/error_report_20240115_143052.json
+
+    文件内容:
+    [
+      {
+        "error_type": "TypeValidationError",
+        "row_index": 2,
+        "column": "price",
+        "value": "abc"
+      },
+      {
+        "error_type": "NotNullViolation",
+        "row_index": 5,
+        "column": "email"
+      }
+    ]
+
+    控制台输出:
+    [LocalFileReporter] 日志目录已创建: ./logs
+    [LocalFileReporter] ✓ 成功将错误报告写入本地日志: ./logs/error_report_20240115_143052.json
+"""
+
+import json
+import os
+from datetime import datetime
+from typing import Any
+
+from .base import Reporter
+
+
+class LocalFileReporter(Reporter):
+    """
+    @classdesc 本地文件报告器 - 将错误报告写入本地文件系统
+
+    该报告器将数据验证错误以 JSON 格式写入本地日志目录。
+    适用于需要本地持久化错误日志的场景，或作为邮件报告的补充方案。
+
+    属性说明：
+        log_dir: 日志文件存放的目录路径
+                 可以是相对路径或绝对路径
+
+    功能特点：
+        - 自动创建日志目录（如果不存在）
+        - 每个报告生成独立的时间戳文件名，避免覆盖
+        - JSON 格式存储，便于程序化处理
+        - UTF-8 编码，支持中文错误信息
+
+    使用示例：
+        reporter = LocalFileReporter()
+        if reporter.configure(log_dir='./logs/errors'):
+            reporter.report(errors)
+        # 将在 ./logs/errors/ 目录生成 error_report_20240215_143052.json
+    """
+
+    def __init__(self) -> None:
+        """
+        初始化本地文件报告器
+
+        调用父类构造函数设置报告器名称为 'LocalFileReporter'。
+        初始化日志目录为 None，需要通过 configure() 方法设置。
+        """
+        super().__init__("LocalFileReporter")
+        self.log_dir: str | None = None
+
+    def configure(self, **config: Any) -> bool:
+        """
+        @methoddesc 配置日志目录并确保目录存在
+
+        该方法设置错误报告文件的存储目录。
+        如果目录不存在，会尝试自动创建。
+
+        :param log_dir: 日志文件存放的目录路径
+                       可以是相对路径（如 './logs'）或绝对路径
+        :param config: 额外的可选配置参数（当前未使用，保留扩展性）
+        :return: 配置是否成功。成功返回 True，失败返回 False
+
+        配置流程：
+            1. 将日志目录路径保存到实例变量
+            2. 检查目录是否存在
+            3. 如不存在，尝试创建目录
+            4. 返回配置结果
+        """
+        # 保存日志目录路径到实例变量
+        log_dir = config.get("log_dir")
+        if not isinstance(log_dir, str) or not log_dir:
+            print(f"[{self.name}] !! 错误: 未提供 log_dir 配置。")
+            return False
+        self.log_dir = log_dir
+
+        try:
+            # 检查目录是否存在，os.path.exists() 既检查文件也检查目录
+            if not os.path.exists(self.log_dir):
+                # 目录不存在，尝试创建（包括父目录）
+                os.makedirs(self.log_dir)
+                print(f"[{self.name}] 日志目录已创建: {self.log_dir}")
+
+            # 配置成功
+            return True
+
+        except Exception as e:
+            # 创建目录失败，打印错误信息
+            print(f"[{self.name}] !! 错误: 创建日志目录失败: {e}")
+            return False
+
+    def report(self, errors: list[dict]) -> None:
+        """
+        @methoddesc 将错误报告写入本地 JSON 文件
+
+        在写入前会检查日志目录是否已配置。
+        文件名包含精确到秒的时间戳，确保每次报告都有唯一的文件。
+
+        :param errors: 错误信息的字典列表，每个字典包含错误详情
+                      典型字段：row_index, column, value, error_type, error_message
+
+        写入流程：
+            1. 检查日志目录是否已配置
+            2. 生成包含时间戳的唯一文件名
+            3. 构造完整的文件路径
+            4. 使用 json.dump() 将错误列表写入文件
+            5. 打印成功或失败消息
+
+        文件格式示例：
+            [
+              {
+                "row_index": 2,
+                "column": "price",
+                "value": "abc",
+                "error_type": "TypeValidationError",
+                "error_message": "无法将 'abc' 转换为浮点数"
+              }
+            ]
+        """
+        # 前置检查：确保日志目录已配置
+        if not self.log_dir:
+            print(f"[{self.name}] !! 错误: 未配置日志目录，无法写入日志。")
+            return
+
+        # 生成时间戳，用于构建唯一的文件名
+        # 格式：YYYYMMDD_HHMMSS_mmm，例如 20240215_143052_123。
+        # 毫秒粒度避免同一秒内的多次报告互相覆盖（同秒覆盖丢报告）；
+        # 极端情况下（同一毫秒内多次写入）追加序号兜底，保证文件名唯一。
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")[:-3]
+
+        # 构建日志文件名；已存在时追加序号去重
+        log_filename = f"error_report_{timestamp}.json"
+        sequence = 1
+        while os.path.exists(os.path.join(self.log_dir, log_filename)):
+            sequence += 1
+            log_filename = f"error_report_{timestamp}_{sequence}.json"
+
+        # 拼接完整的文件路径
+        log_filepath = os.path.join(self.log_dir, log_filename)
+
+        try:
+            # 打开文件并写入 JSON 数据
+            # 使用 utf-8 编码确保中文字符正确保存
+            with open(log_filepath, "w", encoding="utf-8") as f:
+                # 使用 json.dump 序列化错误列表
+                # indent=2 使输出的 JSON 格式化，便于人工阅读
+                # ensure_ascii=False 允许直接写入 Unicode 字符（如中文）
+                json.dump(errors, f, indent=2, ensure_ascii=False)
+
+            # 写入成功，打印确认信息
+            print(f"[{self.name}] ✓ 成功将错误报告写入本地日志: {log_filepath}")
+
+        except Exception as e:
+            # 写入失败，打印错误信息
+            print(f"[{self.name}] !! 错误: 写入日志文件失败: {e}")