[25.06.05 / TASK-184] Feature - 주간 뉴스레터 발송을 위한 mail module 추가 (#30)

* feature: boto3, botocore 라이브러리 추가
* feature: AWS 관련 환경변수 추가
* feature: mail module 및 SES Client 추가
* modify: base_client와의 시그니처 통일
* modify: 불필요한 클래스 변수 선언 삭제
* refactor: 중복되는 Common Error 핸들링을 메서드로 분리
* refactor: 불필요한 elif, else문 삭제
* modify: typing 관련 빌트인으로 수정 및 import 경로 수정
* refactor: JSON 직렬화 예외 처리 추가
* refactor: AWS Credentials를 dataclass로 추가 및 메시지 객체 분리
* refactor: except depth 정리
* delete: 템플릿 생성 & 삭제 메서드 삭제
* delete: send_templated_email 및 템플릿 관련 삭제
  메일 템플릿은 내부 상수로 관리하는 것으로 정리하여 SES의 Template 리소스를 사용하던 기존의 메서드 삭제
* modify: 사용하지 않는 import 삭제
* refactor: UnexpectedClientError 추가

Author: ooheunda

.env.sample

@@ -31,3 +31,8 @@ SENTRY_TRACES_SAMPLE_RATE=0.2
 
 # LLM
 OPENAI_API_KEY=sk-proj-...
+
+# AWS SES
+AWS_ACCESS_KEY_ID=ID
+AWS_SECRET_ACCESS_KEY=AccEssKeY
+AWS_REGION=ap-northeast-2

.github/workflows/test-ci.yaml

@@ -3,7 +3,7 @@ name: Test CI
 on:
   workflow_dispatch:
   push:
-    branches: ["main"]
+    branches: ['main']
   pull_request:
     branches:
       - main
@@ -71,6 +71,9 @@ jobs:
           echo "SENTRY_ENVIRONMENT=gitaction" >> .env
           echo "SENTRY_TRACES_SAMPLE_RATE=0.2" >> .env
           echo "OPENAI_API_KEY= sk-proj" >> .env
+          echo "AWS_ACCESS_KEY_ID=ID" >> .env
+          echo "AWS_SECRET_ACCESS_KEY=AccEssKeY" >> .env
+          echo "AWS_REGION=ap-northeast-2" >> .env
           echo "AES_KEY_0=${{ secrets.AES_KEY_0 }}" >> .env
           echo "AES_KEY_1=${{ secrets.AES_KEY_1 }}" >> .env
           echo "AES_KEY_2=${{ secrets.AES_KEY_2 }}" >> .env

modules/mail/__init__.py

@@ -0,0 +1,79 @@
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from modules.mail.schemas import EmailMessage
+
+# 클라이언트 타입을 위한 제네릭 타입 변수
+T = TypeVar("T")
+
+class MailClient(ABC, Generic[T]):
+    """
+    모든 메일 클라이언트를 위한 추상 기본 클래스로 Lazy Initialization 패턴을 따릅니다.
+    모든 메일 서비스 구현을 위한 템플릿을 제공합니다.
+    """
+
+    @classmethod
+    @abstractmethod
+    def get_client(cls, credentials: dict[str, Any]) -> "MailClient[T]":
+        """
+        메일 클라이언트를 가져오거나 초기화합니다.
+
+        Args:
+            credentials: 서비스 인증 정보 (필수)
+
+        Returns:
+            초기화된 클라이언트 인스턴스
+
+        Raises:
+            AuthenticationError: 인증 정보가 유효하지 않은 경우
+            ConnectionError: 서비스 연결에 실패한 경우
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def _initialize_client(cls, credentials: dict[str, Any]) -> T:
+        """
+        특정 메일 클라이언트를 초기화하는 추상 메서드.
+        각 구체적인 하위 클래스에서 구현되어야 합니다.
+
+        Args:
+            credentials: 서비스 인증 정보 (필수)
+
+        Returns:
+            초기화된 클라이언트 인스턴스
+
+        Raises:
+            AuthenticationError: 인증 정보가 유효하지 않은 경우
+            ConnectionError: 서비스 연결에 실패한 경우
+        """
+        pass
+
+    @abstractmethod
+    def send_email(self, message: EmailMessage) -> str:
+        """
+        이메일을 발송합니다.
+
+        Args:
+            message: 발송할 이메일 메시지 객체
+
+        Returns:
+            발송한 메시지 ID
+
+        Raises:
+            ClientNotInitializedError: 클라이언트가 초기화되지 않은 경우
+            AuthenticationError: 인증 정보가 유효하지 않은 경우
+            ValidationError: 입력이 유효하지 않은 경우
+            LimitExceededException: 발송 한도를 초과한 경우
+            SendError: 이메일 발송 과정에서 오류 발생
+            ConnectionError: API 연결 실패
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def reset_client(cls) -> None:
+        """
+        클라이언트 인스턴스를 재설정합니다(테스트나 설정 변경 시 사용하기 위함)
+        """
+        pass

modules/mail/base_client.py

@@ -0,0 +1,42 @@
+"""
+AWS SES API 에러 코드를 그룹화하여 관리합니다.
+Common API 에러 코드 참고:
+    https://docs.aws.amazon.com/ses/latest/APIReference/CommonErrors.html
+"""
+
+AWS_AUTH_ERROR_CODES = {
+    # Common
+    "InvalidClientTokenId",
+    "AccessDeniedException",
+    "MissingAuthenticationToken",
+    "IncompleteSignature",
+    "NotAuthorized",
+    "AccessDenied",
+    # SES
+    "SignatureDoesNotMatch",
+}
+
+AWS_VALUE_ERROR_CODES = {
+    # Common
+    "InvalidParameterCombination",
+    "InvalidParameterValue",
+    "InvalidQueryParameter",
+    "MalformedQueryString",
+    "MissingParameter",
+    "ValidationError",
+}
+
+AWS_LIMIT_ERROR_CODES = {
+    # Common
+    "ThrottlingException",
+    "TooManyRequestsException",
+    # SES
+    "LimitExceededException",
+}
+
+AWS_SERVICE_ERROR_CODES = {
+    # Common
+    "ServiceUnavailable",
+    "InternalFailure",
+    "InternalServerError",
+}

modules/mail/constants.py

@@ -0,0 +1,44 @@
+class MailError(Exception):
+    """메일 관련 모든 예외의 기본 클래스"""
+
+    pass
+
+
+class AuthenticationError(MailError):
+    """인증 관련 오류"""
+
+    pass
+
+
+class ConnectionError(MailError):
+    """서비스 연결 오류"""
+
+    pass
+
+
+class ClientNotInitializedError(MailError):
+    """클라이언트가 초기화되지 않은 경우"""
+
+    pass
+
+
+class SendError(MailError):
+    """이메일 발송 중 발생한 오류"""
+
+    pass
+
+class LimitExceededException(MailError):
+    """메일 서비스 할당량 초과 오류"""
+
+    pass
+
+
+class ValidationError(MailError):
+    """API 입력이 유효하지 않은 오류"""
+
+    pass
+
+class UnexpectedClientError(MailError):
+    """예상하지 못한 ClientError"""
+
+    pass

modules/mail/exceptions.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+
+@dataclass
+class EmailAttachment:
+    filename: str
+    content: bytes
+    content_type: str
+
+
+@dataclass
+class EmailMessage:
+    to: list[str]
+    from_email: str
+    subject: str
+    text_body: str
+    html_body: str | None = None
+    cc: list[str] | None = None
+    bcc: list[str] | None = None
+    attachments: list[EmailAttachment] | None = None
+
+@dataclass
+class AWSSESCredentials:
+    aws_access_key_id: str
+    aws_secret_access_key: str
+    aws_region_name: str