xiaoxia-saas/packages/domain/auth/email_service.py

"""邮件服务端口（领域层接口）.

定义邮件发送服务的抽象接口，具体实现由基础设施层（adapters）提供。
遵循 DDD 依赖倒置原则：领域层定义端口，外层实现端口。
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional


@dataclass
class EmailConfig:
    """邮件配置（领域层值对象）"""

    smtp_host: str = "smtp.gmail.com"
    smtp_port: int = 587
    smtp_user: str = ""
    smtp_password: str = ""
    from_email: str = ""
    from_name: str = "小虾 SaaS"
    use_tls: bool = True


class EmailServicePort(ABC):
    """邮件服务端口（抽象接口）"""

    @abstractmethod
    def send_email(
        self,
        to_email: str,
        subject: str,
        html_body: str,
        text_body: Optional[str] = None,
        cc: Optional[list[str]] = None,
        bcc: Optional[list[str]] = None,
    ) -> tuple[bool, Optional[str]]:
        """发送邮件"""
        ...

    @abstractmethod
    def send_verification_email(
        self,
        to_email: str,
        verification_code: str,
        username: str = "",
    ) -> tuple[bool, Optional[str]]:
        """发送验证邮件"""
        ...

    @abstractmethod
    def send_password_reset_email(
        self,
        to_email: str,
        reset_token: str,
        reset_url: str = "",
        username: str = "",
    ) -> tuple[bool, Optional[str]]:
        """发送密码重置邮件"""
        ...