xinops 1.0.1__py3-none-any.whl

xinops/__init__.py

@@ -0,0 +1,27 @@
+# Xinops/__init__.py
+
+# 包版本号（与 setup.cfg 中的 version 保持一致）
+__version__ = "1.0.0"
+
+# 各功能模块 Mixin 导入
+from ._core import CoreMixin
+from ._wecom import WeComMixin
+from ._email import EmailMixin
+from ._hive import HiveMixin
+from ._excel import ExcelMixin
+from ._export import ExportMixin
+from ._misc import MiscMixin
+
+# 飞书表格上传器（独立类，不参与 Mixin 组装）
+from ._feishu import FeishuSheetUploader
+
+
+# 组装为对外统一的类：方法名与 Functions_d 1.46 完全一致，业务脚本仅需改 import
+class DataProcessingAndMessaging(CoreMixin, WeComMixin, EmailMixin, HiveMixin,
+                                  ExcelMixin, ExportMixin, MiscMixin):
+    """数据处理与消息推送工具类（由多个功能 Mixin 组装而成）"""
+    pass
+
+
+# 明确指定包对外暴露的成员（规范导入）
+__all__ = ["DataProcessingAndMessaging", "FeishuSheetUploader", "__version__"]

xinops/_core.py

@@ -0,0 +1,213 @@
+# -*- coding:utf-8 -*-
+"""核心模块：日志初始化、脚本生命周期管理、日期时间与通用工具方法"""
+import datetime
+import inspect
+import logging
+import os
+import time
+import psutil
+import yaml
+
+
+class CoreMixin:
+    """基础设施 Mixin：日志器、运行状态属性、密钥配置加载、通用工具方法"""
+
+    def __init__(self, enable_console_log=None):
+        # -------------------------- 1. 主类日志初始化 --------------------------
+        caller_frame = inspect.stack()[1]
+        caller_filename = caller_frame.filename
+        caller_filename = os.path.abspath(caller_filename)
+        script_dir = os.path.dirname(caller_filename)
+        log_filename = os.path.splitext(os.path.basename(caller_filename))[0] + ".log"
+        self.main_log_file = os.path.join(script_dir, log_filename)
+
+        self.logger = logging.getLogger("main_logger")
+        self.logger.setLevel(logging.INFO)
+        self.logger.propagate = False  # 防止日志扩散
+        if not self.logger.handlers:
+            file_handler = logging.FileHandler(self.main_log_file, encoding='utf-8')
+            file_handler.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
+            self.logger.addHandler(file_handler)
+            if enable_console_log:
+                console_handler = logging.StreamHandler()
+                console_handler.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
+                self.logger.addHandler(console_handler)
+
+        self.logger.info("\n" * 1)  # 1行空行，可自行修改数字
+        self.logger.info("初始化 DataProcessingAndMessaging 类")
+
+        # -------------------------- 2. 主类核心参数初始化 --------------------------
+        self.start_time = None
+        self.current_script_name = None
+        self.log_filename = None
+        self.current_script_names = None
+        self.current_path = None
+        self.path = None
+
+        # -------------------------- 2.1 密钥配置加载（外部yaml，代码不再硬编码） --------------------------
+        sec = self._load_secrets(script_dir)
+
+        # 企业微信消息发送参数（环境变量 > 配置文件）
+        self.corpid = os.getenv("WECOM_CORPID") or sec.get("wecom_corpid")
+        self.corpsecret = os.getenv("WECOM_CORPSECRET") or sec.get("wecom_corpsecret")
+        self.agentid = str(sec.get("wecom_agentid", "1000026"))
+
+        # -------------------------- 3. 企业微信文档功能初始化 --------------------------
+        self.WECHAT_DOC_CORP_ID = os.getenv("WECOM_DOC_CORPID") or sec.get("wecom_doc_corpid")
+        self.WECHAT_DOC_SECRET = os.getenv("WECOM_DOC_SECRET") or sec.get("wecom_doc_corpsecret")
+        self.WECHAT_DOC_SPACE_ID = None
+        self.WECHAT_DOC_LOG_FILE = os.path.join(script_dir, "docs_operation.log")
+        self.wechat_doc_access_token = None
+        self._wechat_doc_logger = None  # 企微文档独立日志器（延迟初始化）
+
+        # -------------------------- 邮件SMTP全局配置 --------------------------
+        self.SMTP_SENDER = sec.get("smtp_sender")
+        self.SMTP_PWD = sec.get("smtp_pwd")
+        self.SMTP_HOST = sec.get("smtp_host", "smtp.exmail.qq.com")
+        self.SMTP_PORT = int(sec.get("smtp_port", 465))
+        self.SMTP_TIMEOUT = 300  # 超时延长至5分钟
+        self.MAIL_RETRY_TIMES = 3  # 失败重试3次
+        self.MAIL_RETRY_INTERVAL = 5  # 重试间隔5秒
+
+        # -------------------------- Hive连接配置（run_sql使用） --------------------------
+        self.hive_host = os.getenv("HIVE_HOST") or sec.get("hive_host")
+        self.hive_port = int(sec.get("hive_port", 10023))
+        self.hive_user = os.getenv("HIVE_USER") or sec.get("hive_user")
+        self.hive_pwd = os.getenv("HIVE_PWD") or sec.get("hive_pwd")
+
+    # -------------------------- 密钥配置文件加载 --------------------------
+    def _load_secrets(self, script_dir):
+        """按优先级查找密钥配置文件（xinops_secrets.yaml 或 pypi_ku_secrets.yaml）：
+        1. 环境变量 XINOPS_CONFIG / PYPI_KU_CONFIG 指定的路径
+        2. 调用方脚本所在目录及其各级上层目录（最多向上3层）
+        3. 用户主目录
+        配置文件放在代码仓库之外，切勿提交到 git 或打包进 PyPI。
+        """
+        candidates = []
+        for env_key in ("XINOPS_CONFIG", "PYPI_KU_CONFIG"):
+            env_path = os.getenv(env_key)
+            if env_path:
+                candidates.append(env_path)
+
+        file_names = ("xinops_secrets.yaml", "pypi_ku_secrets.yaml")
+        # 从脚本所在目录开始向上查找（本目录 + 上3层）
+        d = script_dir
+        for _ in range(4):
+            for fn in file_names:
+                candidates.append(os.path.join(d, fn))
+            parent = os.path.dirname(d)
+            if parent == d:  # 已到根目录
+                break
+            d = parent
+
+        # 用户主目录兜底
+        home = os.path.expanduser("~")
+        for fn in file_names:
+            candidates.append(os.path.join(home, fn))
+
+        for path in candidates:
+            if os.path.exists(path):
+                try:
+                    with open(path, encoding="utf-8") as f:
+                        return yaml.safe_load(f) or {}
+                except yaml.YAMLError as e:
+                    raise ValueError(f"密钥配置文件格式错误（{path}）：{e}")
+
+        raise FileNotFoundError(
+            "未找到密钥配置文件 xinops_secrets.yaml（或 pypi_ku_secrets.yaml），已查找以下位置：\n"
+            + "\n".join(candidates)
+            + "\n请把配置文件放到业务脚本上层目录，或设置环境变量 XINOPS_CONFIG 指向实际路径"
+        )
+
+    # -------------------------- 脚本路径和文件名初始化 --------------------------
+    def Start_Get_filepath_and_filename(self):
+        self.start_time = time.time()
+        # ========== 新增：运行开始时追加10行空行分隔 ==========
+        # self.logger.info('\n' * 5)
+        caller_frame = inspect.stack()[1]
+        self.current_script_name = caller_frame.filename
+        self.log_filename = os.path.splitext(self.current_script_name)[0] + ".log"
+        self.current_script_names = os.path.basename(self.current_script_name)
+        self.current_path = os.path.dirname(os.path.abspath(self.current_script_name))
+        self.path = self.current_path + os.sep
+        print(f"当前时间：{self.get_date_and_time('%Y-%m-%d %H:%M:%S', 0)}")
+        print(f"开始执行脚本：{self.current_script_names}")
+        self.logger.info(f"开始执行脚本：{self.current_script_names}")
+
+    # -------------------------- 脚本结束处理 --------------------------
+    def End_operation(self):
+        print(f"脚本：{self.current_script_names} 执行成功")
+        self.logger.info(f"脚本：{self.current_script_names} 执行成功")
+        end_time = time.time()
+        elapsed_time = round(end_time - self.start_time, 0)
+        print(f"运行时间：{elapsed_time} 秒")
+        self.logger.info(f"运行时间：{elapsed_time} 秒")
+        # self.logger.info('\n' * 2)
+
+    # -------------------------- 获取指定格式的日期时间 --------------------------
+    def get_date_and_time(self, format_type, days):
+        today = datetime.datetime.today()
+        target_date = today - datetime.timedelta(days=days)
+        result = target_date.strftime(format_type)
+        return result
+
+    # -------------------------- 获取文件大小（KB） --------------------------
+    def get_FileSize(self, img_name):
+        fsize = os.path.getsize(img_name)
+        fsize = fsize / float(1024)
+        return round(fsize, 2)
+
+    # -------------------------- 列标转换（A,B,C...） --------------------------
+    def column_label(self, n):
+        result = ""
+        while n > 0:
+            n, remainder = divmod(n - 1, 26)
+            result = chr(65 + remainder) + result
+        return result
+
+    # -------------------------- 辅助方法：检查文件是否被占用 --------------------------
+    def is_file_locked(self, file_path):
+        if not os.path.exists(file_path):
+            return False
+        try:
+            with open(file_path, 'a', encoding='utf-8') as f:
+                pass
+            return False
+        except IOError:
+            return True
+
+    # -------------------------- 辅助方法：安全关闭Excel进程 --------------------------
+    def _safe_quit_excel(self, app):
+        """安全关闭Excel进程，优化时序检查逻辑"""
+        try:
+            pid = app.pid
+            # 先尝试正常退出
+            app.quit()
+
+            # 增加短暂延迟，等待进程自然退出（解决时序问题）
+            time.sleep(0.5)
+
+            # 检查进程是否还存在
+            if psutil.pid_exists(pid):
+                # 尝试优雅终止
+                proc = psutil.Process(pid)
+                proc.terminate()  # 发送终止信号
+
+                # 等待进程退出，最多等待3秒
+                try:
+                    proc.wait(timeout=3)
+                    self.logger.debug(f"Excel进程（PID: {pid}）已被强制终止")
+                except psutil.TimeoutExpired:
+                    # 超时后强制杀死进程
+                    proc.kill()
+                    self.logger.debug(f"Excel进程（PID: {pid}）超时未退出，已强制杀死")
+            else:
+                # 进程已正常退出，不记录警告
+                self.logger.debug(f"Excel进程（PID: {pid}）已正常退出")
+
+        except psutil.NoSuchProcess:
+            # 进程在检查前已退出，属于正常情况，不记录警告
+            self.logger.debug(f"Excel进程已提前退出（PID: {pid}）")
+        except Exception as e:
+            # 其他未知错误才记录警告
+            self.logger.warning(f"关闭Excel进程时发生异常: {str(e)}")

xinops/_email.py

@@ -0,0 +1,338 @@
+# -*- coding:utf-8 -*-
+"""邮件模块：简洁版与增强版邮件发送（yagmail / smtplib）"""
+import os
+import time
+import smtplib
+import yagmail
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from email.mime.application import MIMEApplication
+from email.mime.image import MIMEImage
+
+
+class EmailMixin:
+    """邮件发送 Mixin"""
+
+    # -------------------------- 发送邮件（旧版） --------------------------
+    def sende_email(self, name, contact_name, title, rec, file=None, cc=None, bcc=None, remarks=None):
+        """
+        简洁版邮件发送（支持重复调用，自动过滤无效参数）
+        :param name: 收件人称呼（如"各位"）
+        :param contact_name: 联系人姓名（如"董养"）
+        :param title: 邮件主题
+        :param rec: 收件人邮箱（单个字符串或列表）
+        :param file: 附件路径（单个字符串、列表，或None）
+        :param cc: 抄送邮箱（单个字符串、列表，或None）
+        :param bcc: 密送邮箱（单个字符串、列表，或None）
+        :param remarks: 附加备注（可选，默认None，传入文本字符串时追加到正文）
+        """
+        # 1. 内部工具：格式化邮箱（转列表+过滤无效值）
+        def format_email(emails):
+            if not emails:
+                return None
+            # 单个邮箱转列表，列表直接使用
+            email_list = [emails] if isinstance(emails, str) else emails
+            # 过滤：非空字符串 + 简单格式校验（含@和.）
+            valid_emails = [
+                e.strip() for e in email_list
+                if isinstance(e, str) and e.strip() and '@' in e.strip() and '.' in e.strip()
+            ]
+            return valid_emails if valid_emails else None
+        # 2. 格式化所有邮箱参数
+        to_emails = format_email(rec)
+        cc_emails = format_email(cc)
+        bcc_emails = format_email(bcc)
+        # 3. 核心参数校验（提前报错，避免无效连接）
+        if not to_emails:
+            err_msg = "邮件发送失败：无有效收件人邮箱"
+            self.logger.error(err_msg)
+            raise ValueError(err_msg)
+        if not title.strip():
+            err_msg = "邮件发送失败：邮件主题不能为空"
+            self.logger.error(err_msg)
+            raise ValueError(err_msg)
+        # 4. 附件处理（校验存在性，支持单个/列表）
+        attachments = None
+        if file:
+            file_list = [file] if isinstance(file, str) else file
+            attachments = []
+            for f in file_list:
+                f = f.strip()
+                if not os.path.exists(f):
+                    err_msg = f"邮件发送失败：附件不存在 -> {f}"
+                    self.logger.error(err_msg)
+                    raise FileNotFoundError(err_msg)
+                attachments.append(f)
+        # ==========【已删除此处硬编码smtp_conf字典，全部读取实例self属性】==========
+        # 5. 邮件内容（新增remarks逻辑：有值则追加到"请查收！"下方，保持缩进一致）
+        email_content = f"{name} 好：\n附件为《{title}》，请查收！"
+        if remarks and isinstance(remarks, str) and remarks.strip():
+            formatted_remarks = remarks.strip().replace('\n', '\n')  # 处理多行备注
+            email_content += f"\n{formatted_remarks}"
+        email_content += f"\n\n如有疑问请联系{contact_name}，谢谢~"
+        try:
+            # 上下文管理器：自动关闭连接，重复调用不泄露资源
+            # 直接使用self实例上面初始化的邮箱配置
+            smtp_conf = {
+                "user": self.SMTP_SENDER,
+                "password": self.SMTP_PWD,
+                "host": self.SMTP_HOST,
+                "port": self.SMTP_PORT,
+                "smtp_ssl": True,
+                "smtp_starttls": False
+            }
+            with yagmail.SMTP(**smtp_conf) as yag:
+                yag.send(
+                    to=to_emails,
+                    subject=title.strip(),
+                    contents=email_content,
+                    attachments=attachments,
+                    cc=cc_emails,
+                    bcc=bcc_emails
+                )
+            # 简洁日志：关键信息+统计，便于排查
+            log_msg = f"邮件发送成功 | 主题：{title.strip()} | 收件人：{len(to_emails)}人"
+            if cc_emails:
+                log_msg += f" | 抄送：{len(cc_emails)}人"
+            if bcc_emails:
+                log_msg += f" | 密送：{len(bcc_emails)}人"
+            if attachments:
+                log_msg += f" | 附件：{len(attachments)}个"
+            if remarks and remarks.strip():
+                log_msg += f" | 包含备注：{remarks.strip()[:20]}..."  # 日志显示备注前20字（避免过长）
+            self.logger.info(log_msg)
+            print(log_msg)
+        # 7. 分类异常捕获（易排查问题）
+        except yagmail.SMTPAuthenticationError:
+            err_msg = "邮件发送失败：SMTP账号/密码/授权码错误"
+            self.logger.error(err_msg)
+            raise ValueError(err_msg)
+        except yagmail.SMTPConnectionError:
+            err_msg = "邮件发送失败：SMTP服务器连接失败（检查host/port/防火墙）"
+            self.logger.error(err_msg)
+            raise ConnectionError(err_msg)
+        except FileNotFoundError:
+            raise  # 附件错误已提前处理，直接抛出
+        except Exception as e:
+            err_msg = f"邮件发送失败：{str(e)}"
+            self.logger.error(err_msg, exc_info=True)
+            raise RuntimeError(err_msg)
+
+    # -------------------------- 发送邮件（新版-优化增强版+重试+防超时） --------------------------
+    def send_email_new(self, recipient_emails, cc_emails=None, bcc_emails=None, subject="", html_body="",
+                       attachments=None):
+        # 1. 内部工具：格式化邮箱（和旧版完全对齐，转列表+过滤无效值）
+        def format_email(emails):
+            if not emails:
+                return []
+            email_list = [emails] if isinstance(emails, str) else emails
+            valid_emails = [
+                e.strip() for e in email_list
+                if isinstance(e, str) and e.strip() and '@' in e.strip() and '.' in e.strip()
+            ]
+            return valid_emails
+
+        # 2. 内部工具：自动识别附件MIME类型（支持全格式文件）
+        def get_mime_type(file_path):
+            suffix = os.path.splitext(file_path)[1].lower()
+            mime_map = {
+                '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+                '.xls': 'application/vnd.ms-excel',
+                '.pdf': 'application/pdf',
+                '.doc': 'application/msword',
+                '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+                '.ppt': 'application/vnd.ms-powerpoint',
+                '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+                '.jpg': 'image/jpeg',
+                '.jpeg': 'image/jpeg',
+                '.png': 'image/png',
+                '.gif': 'image/gif',
+                '.txt': 'text/plain',
+                '.csv': 'text/csv',
+                '.zip': 'application/zip',
+                '.rar': 'application/x-rar-compressed'
+            }
+            return mime_map.get(suffix, 'application/octet-stream')
+
+        # 3. 参数标准化处理
+        subject = subject.strip()
+        to_emails = format_email(recipient_emails)
+        cc_emails = format_email(cc_emails)
+        bcc_emails = format_email(bcc_emails)
+        attachments = attachments or []
+        if isinstance(attachments, str):
+            attachments = [attachments.strip()]
+
+        # 4. 核心参数校验
+        if not to_emails:
+            err_msg = "❌ 邮件发送失败：无有效收件人邮箱"
+            self.logger.error(err_msg)
+            print(err_msg)
+            raise ValueError(err_msg)
+        if not subject:
+            err_msg = "❌ 邮件发送失败：邮件主题不能为空"
+            self.logger.error(err_msg)
+            print(err_msg)
+            raise ValueError(err_msg)
+
+        # 5. 控制台打印
+        print(f"📧 开始发送邮件 - 主题: {subject}")
+        print(f"📥 收件人: {', '.join(to_emails)}")
+        if cc_emails:
+            print(f"📋 抄送: {', '.join(cc_emails)}")
+        if bcc_emails:
+            print(f"🔒 密送: {', '.join(bcc_emails)}")
+        if attachments:
+            attach_names = [os.path.basename(att) for att in attachments]
+            print(f"📎 附件: {', '.join(attach_names)}")
+
+        # 6. 日志记录
+        self.logger.info(f"开始发送邮件 - 主题：{subject}")
+        self.logger.info(f"收件人: {', '.join(to_emails)}")
+        if cc_emails:
+            self.logger.info(f"抄送: {', '.join(cc_emails)}")
+        if bcc_emails:
+            self.logger.info(f"密送: {', '.join(bcc_emails)}")
+        if attachments:
+            attach_names = [os.path.basename(att) for att in attachments]
+            self.logger.info(f"附件: {', '.join(attach_names)}")
+
+        # 所有收件人提前合并去重
+        all_recipients = list(set(to_emails + cc_emails + bcc_emails))
+        last_exception = None
+
+        # 7. 循环重试发送（解决网络超时/抖动）
+        for retry_idx in range(1, self.MAIL_RETRY_TIMES + 1):
+            try:
+                # 8. 构建邮件对象
+                msg = MIMEMultipart()
+                msg['From'] = self.SMTP_SENDER
+                msg['To'] = ', '.join(to_emails)
+                if cc_emails:
+                    msg['Cc'] = ', '.join(cc_emails)
+                if bcc_emails:
+                    msg['Bcc'] = ', '.join(bcc_emails)
+                msg['Subject'] = subject
+
+                # 9. 邮件正文
+                body = MIMEText(html_body, 'html', 'utf-8')
+                msg.attach(body)
+
+                # 10. 附件处理 + 安全解码 + 中文文件名修复
+                valid_attachments = []
+                for attachment in attachments:
+                    attachment = attachment.strip()
+                    if not os.path.exists(attachment):
+                        error_msg = f"❌ 邮件发送失败：附件不存在 -> {attachment}"
+                        self.logger.error(error_msg)
+                        print(error_msg)
+                        raise FileNotFoundError(error_msg)
+
+                    file_name = os.path.basename(attachment)
+                    mime_type = get_mime_type(attachment)
+
+                    # 二进制读取，避免大文件/编码报错
+                    try:
+                        with open(attachment, 'rb') as file:
+                            file_content = file.read()
+                    except Exception as e:
+                        err = f"❌ 读取附件失败 {attachment}：{str(e)}"
+                        self.logger.error(err, exc_info=True)
+                        print(err)
+                        raise RuntimeError(err)
+
+                    # 构造附件
+                    if mime_type.startswith('image/'):
+                        part = MIMEImage(file_content, _subtype=mime_type.split('/')[1])
+                    elif mime_type in ('text/plain', 'text/csv'):
+                        # 文本文件容错解码
+                        text = file_content.decode("utf-8", errors="replace")
+                        part = MIMEText(text, _subtype=mime_type.split('/')[1], _charset='utf-8')
+                    else:
+                        part = MIMEApplication(file_content, _subtype=mime_type.split('/')[1])
+
+                    # 修复中文附件名乱码（RFC2231标准）
+                    part.add_header('Content-Disposition', 'attachment', filename=file_name)
+                    part.set_param("filename*", f"utf-8''{file_name}", header="Content-Disposition")
+                    part['Content-Type'] = f'{mime_type}'
+                    msg.attach(part)
+
+                    valid_attachments.append(file_name)
+                    self.logger.debug(f"已添加附件: {file_name}")
+                    print(f"✅ 已添加附件: {file_name}")
+
+                # 11. 连接SMTP服务器（延长超时 + 双重ehlo提升兼容性）
+                print(f"🔌 第{retry_idx}次尝试连接 SMTP {self.SMTP_HOST}:{self.SMTP_PORT}")
+                self.logger.info(f"第{retry_idx}次连接 SMTP 服务器")
+
+                # 465端口使用SMTP_SSL，不需要starttls
+                with smtplib.SMTP_SSL(self.SMTP_HOST, self.SMTP_PORT, timeout=self.SMTP_TIMEOUT) as smtp:
+                    smtp.ehlo()
+                    smtp.login(self.SMTP_SENDER, self.SMTP_PWD)
+                    print(f"🔐 SMTP服务器登录成功")
+                    smtp.sendmail(self.SMTP_SENDER, all_recipients, msg.as_string())
+
+                # 发送成功
+                success_msg = f"✅ 邮件发送成功 | 主题：{subject} | 收件人：{len(to_emails)}人"
+                if cc_emails:
+                    success_msg += f" | 抄送：{len(cc_emails)}人"
+                if bcc_emails:
+                    success_msg += f" | 密送：{len(bcc_emails)}人"
+                if valid_attachments:
+                    success_msg += f" | 附件：{len(valid_attachments)}个"
+
+                self.logger.info(success_msg)
+                print(success_msg)
+                return True
+
+            # 可重试异常：超时、连接断开
+            except (TimeoutError, smtplib.SMTPServerDisconnected) as e:
+                last_exception = e
+                err = f"⚠️ 第{retry_idx}次发送超时/连接断开：{str(e)}"
+                self.logger.warning(err)
+                print(err)
+                if retry_idx < self.MAIL_RETRY_TIMES:
+                    print(f"⏳ {self.MAIL_RETRY_INTERVAL} 秒后进行重试...")
+                    time.sleep(self.MAIL_RETRY_INTERVAL)
+                continue
+
+            # 账号密码错误：致命异常，直接终止重试
+            except smtplib.SMTPAuthenticationError:
+                err_msg = "❌ 邮件发送失败：SMTP账号/密码错误，终止重试"
+                self.logger.error(err_msg, exc_info=True)
+                print(err_msg)
+                raise ValueError(err_msg)
+
+            # 连接失败
+            except smtplib.SMTPConnectError:
+                err_msg = "❌ 邮件发送失败：SMTP服务器连接失败（检查网络/防火墙）"
+                self.logger.error(err_msg, exc_info=True)
+                print(err_msg)
+                raise ConnectionError(err_msg)
+
+            # 其他SMTP协议异常
+            except smtplib.SMTPException as e:
+                err_msg = f"❌ 邮件发送失败：SMTP协议错误 - {str(e)}"
+                self.logger.error(err_msg, exc_info=True)
+                print(err_msg)
+                raise RuntimeError(err_msg)
+
+            # 文件类异常，直接抛出
+            except (FileNotFoundError, RuntimeError):
+                raise
+
+            # 通用未知异常
+            except Exception as e:
+                last_exception = e
+                err = f"⚠️ 第{retry_idx}次发送未知异常：{str(e)}"
+                self.logger.error(err, exc_info=True)
+                print(err)
+                if retry_idx < self.MAIL_RETRY_TIMES:
+                    time.sleep(self.MAIL_RETRY_INTERVAL)
+                continue
+
+        # 所有重试全部失败
+        final_err = f"❌ 邮件{self.MAIL_RETRY_TIMES}次重试全部失败，最终异常：{str(last_exception)}"
+        self.logger.error(final_err, exc_info=True)
+        print(final_err)
+        raise RuntimeError(final_err)